Documentation/ABI/testing/sysfs-firmware-dmi-entries

   1 What:           /sys/firmware/dmi/entries/
   2 Date:           February 2011
   3 Contact:        Mike Waychison <mikew@google.com>
   4 Description:
   5                 Many machines' firmware (x86 and ia64) 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                 =============     ====================================