1What:		/sys/firmware/dmi/entries/
  2Date:		February 2011
  3Contact:	Mike Waychison <mikew@google.com>
  4Description:
  5		Many machines' firmware (x86 and arm64) export DMI /
  6		SMBIOS tables to the operating system.  Getting at this
  7		information is often valuable to userland, especially in
  8		cases where there are OEM extensions used.
  9
 10		The kernel itself does not rely on the majority of the
 11		information in these tables being correct.  It equally
 12		cannot ensure that the data as exported to userland is
 13		without error either.
 14
 15		DMI is structured as a large table of entries, where
 16		each entry has a common header indicating the type and
 17		length of the entry, as well as a firmware-provided
 18		'handle' that is supposed to be unique amongst all
 19		entries.
 20
 21		Some entries are required by the specification, but many
 22		others are optional.  In general though, users should
 23		never expect to find a specific entry type on their
 24		system unless they know for certain what their firmware
 25		is doing.  Machine to machine experiences will vary.
 26
 27		Multiple entries of the same type are allowed.  In order
 28		to handle these duplicate entry types, each entry is
 29		assigned by the operating system an 'instance', which is
 30		derived from an entry type's ordinal position.  That is
 31		to say, if there are 'N' multiple entries with the same type
 32		'T' in the DMI tables (adjacent or spread apart, it
 33		doesn't matter), they will be represented in sysfs as
 34		entries "T-0" through "T-(N-1)":
 35
 36		Example entry directories::
 37
 38			/sys/firmware/dmi/entries/17-0
 39			/sys/firmware/dmi/entries/17-1
 40			/sys/firmware/dmi/entries/17-2
 41			/sys/firmware/dmi/entries/17-3
 42			...
 43
 44		Instance numbers are used in lieu of the firmware
 45		assigned entry handles as the kernel itself makes no
 46		guarantees that handles as exported are unique, and
 47		there are likely firmware images that get this wrong in
 48		the wild.
 49
 50		Each DMI entry in sysfs has the common header values
 51		exported as attributes:
 52
 53		========  =================================================
 54		handle	  The 16bit 'handle' that is assigned to this
 55			  entry by the firmware.  This handle may be
 56			  referred to by other entries.
 57		length	  The length of the entry, as presented in the
 58			  entry itself.  Note that this is _not the
 59			  total count of bytes associated with the
 60			  entry.  This value represents the length of
 61			  the "formatted" portion of the entry.  This
 62			  "formatted" region is sometimes followed by
 63			  the "unformatted" region composed of nul
 64			  terminated strings, with termination signalled
 65			  by a two nul characters in series.
 66		raw	  The raw bytes of the entry. This includes the
 67			  "formatted" portion of the entry, the
 68			  "unformatted" strings portion of the entry,
 69			  and the two terminating nul characters.
 70		type	  The type of the entry.  This value is the same
 71			  as found in the directory name.  It indicates
 72			  how the rest of the entry should be interpreted.
 73		instance  The instance ordinal of the entry for the
 74			  given type.  This value is the same as found
 75			  in the parent directory name.
 76		position  The ordinal position (zero-based) of the entry
 77			  within the entirety of the DMI entry table.
 78		========  =================================================
 79
 80		**Entry Specialization**
 81
 82		Some entry types may have other information available in
 83		sysfs.  Not all types are specialized.
 84
 85		**Type 15 - System Event Log**
 86
 87		This entry allows the firmware to export a log of
 88		events the system has taken.  This information is
 89		typically backed by nvram, but the implementation
 90		details are abstracted by this table.  This entry's data
 91		is exported in the directory::
 92
 93		  /sys/firmware/dmi/entries/15-0/system_event_log
 94
 95		and has the following attributes (documented in the
 96		SMBIOS / DMI specification under "System Event Log (Type 15)":
 97
 98		- area_length
 99		- header_start_offset
100		- data_start_offset
101		- access_method
102		- status
103		- change_token
104		- access_method_address
105		- header_format
106		- per_log_type_descriptor_length
107		- type_descriptors_supported_count
108
109		As well, the kernel exports the binary attribute:
110
111		=============	  ====================================
112		raw_event_log	  The raw binary bits of the event log
113				  as described by the DMI entry.
114		=============	  ====================================