firmware: Add documentation for /sys/firmware/dmi

Document the new ABI added by the dmi-sysfs module.

Signed-off-by: Mike Waychison <mikew@google.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi b/Documentation/ABI/testing/sysfs-firmware-dmi
new file mode 100644 (file)
index 0000000..ba9da95
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-dmi
@@ -0,0 +1,110 @@
+What:          /sys/firmware/dmi/
+Date:          February 2011
+Contact:       Mike Waychison <mikew@google.com>
+Description:
+               Many machines' firmware (x86 and ia64) export DMI /
+               SMBIOS tables to the operating system.  Getting at this
+               information is often valuable to userland, especially in
+               cases where there are OEM extensions used.
+
+               The kernel itself does not rely on the majority of the
+               information in these tables being correct.  It equally
+               cannot ensure that the data as exported to userland is
+               without error either.
+
+               DMI is structured as a large table of entries, where
+               each entry has a common header indicating the type and
+               length of the entry, as well as 'handle' that is
+               supposed to be unique amongst all entries.
+
+               Some entries are required by the specification, but many
+               others are optional.  In general though, users should
+               never expect to find a specific entry type on their
+               system unless they know for certain what their firmware
+               is doing.  Machine to machine will vary.
+
+               Multiple entries of the same type are allowed.  In order
+               to handle these duplicate entry types, each entry is
+               assigned by the operating system an 'instance', which is
+               derived from an entry type's ordinal position.  That is
+               to say, if there are 'N' multiple entries with the same type
+               'T' in the DMI tables (adjacent or spread apart, it
+               doesn't matter), they will be represented in sysfs as
+               entries "T-0" through "T-(N-1)":
+
+               Example entry directories:
+
+                       /sys/firmware/dmi/entries/17-0
+                       /sys/firmware/dmi/entries/17-1
+                       /sys/firmware/dmi/entries/17-2
+                       /sys/firmware/dmi/entries/17-3
+                       ...
+
+               Instance numbers are used in lieu of the firmware
+               assigned entry handles as the kernel itself makes no
+               guarantees that handles as exported are unique, and
+               there are likely firmware images that get this wrong in
+               the wild.
+
+               Each DMI entry in sysfs has the common header values
+               exported as attributes:
+
+               handle  : The 16bit 'handle' that is assigned to this
+                         entry by the firmware.  This handle may be
+                         referred to by other entries.
+               length  : The length of the entry, as presented in the
+                         entry itself.  Note that this is _not the
+                         total count of bytes associated with the
+                         entry_.  This value represents the length of
+                         the "formatted" portion of the entry.  This
+                         "formatted" region is sometimes followed by
+                         the "unformatted" region composed of nul
+                         terminated strings, with termination signalled
+                         by a two nul characters in series.
+               raw     : The raw bytes of the entry. This includes the
+                         "formatted" portion of the entry, the
+                         "unformatted" strings portion of the entry,
+                         and the two terminating nul characters.
+               type    : The type of the entry.  This value is the same
+                         as found in the directory name.  It indicates
+                         how the rest of the entry should be
+                         interpreted.
+               instance: The instance ordinal of the entry for the
+                         given type.  This value is the same as found
+                         in the parent directory name.
+               position: The position of the entry within the entirety
+                         of the entirety.
+
+               === Entry Specialization ===
+
+               Some entry types may have other information available in
+               sysfs.
+
+               --- Type 15 - System Event Log ---
+
+               This entry allows the firmware to export a log of
+               events the system has taken.  This information is
+               typically backed by nvram, but the implementation
+               details are abstracted by this table.  This entries data
+               is exported in the directory:
+
+               /sys/firmware/dmi/entries/15-0/system_event_log
+
+               and has the following attributes (documented in the
+               SMBIOS / DMI specification under "System Event Log (Type 15)":
+
+               area_length
+               header_start_offset
+               data_start_offset
+               access_method
+               status
+               change_token
+               access_method_address
+               header_format
+               per_log_type_descriptor_length
+               type_descriptors_supported_count
+
+               As well, the kernel exports the binary attribute:
+
+               raw_event_log   : The raw binary bits of the event log
+                                 as described by the DMI entry.