tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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>
authored by
Mike Waychison
and committed by
Greg Kroah-Hartman
9effd822
a3857a5c
+110
+110
Documentation/ABI/testing/sysfs-firmware-dmi
+110
Documentation/ABI/testing/sysfs-firmware-dmi
···
1
+
What: /sys/firmware/dmi/
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 'handle' that is
18
+
supposed to be unique amongst all entries.
19
+
20
+
Some entries are required by the specification, but many
21
+
others are optional. In general though, users should
22
+
never expect to find a specific entry type on their
23
+
system unless they know for certain what their firmware
24
+
is doing. Machine to machine will vary.
25
+
26
+
Multiple entries of the same type are allowed. In order
27
+
to handle these duplicate entry types, each entry is
28
+
assigned by the operating system an 'instance', which is
29
+
derived from an entry type's ordinal position. That is
30
+
to say, if there are 'N' multiple entries with the same type
31
+
'T' in the DMI tables (adjacent or spread apart, it
32
+
doesn't matter), they will be represented in sysfs as
33
+
entries "T-0" through "T-(N-1)":
34
+
35
+
Example entry directories:
36
+
37
+
/sys/firmware/dmi/entries/17-0
38
+
/sys/firmware/dmi/entries/17-1
39
+
/sys/firmware/dmi/entries/17-2
40
+
/sys/firmware/dmi/entries/17-3
41
+
...
42
+
43
+
Instance numbers are used in lieu of the firmware
44
+
assigned entry handles as the kernel itself makes no
45
+
guarantees that handles as exported are unique, and
46
+
there are likely firmware images that get this wrong in
47
+
the wild.
48
+
49
+
Each DMI entry in sysfs has the common header values
50
+
exported as attributes:
51
+
52
+
handle : The 16bit 'handle' that is assigned to this
53
+
entry by the firmware. This handle may be
54
+
referred to by other entries.
55
+
length : The length of the entry, as presented in the
56
+
entry itself. Note that this is _not the
57
+
total count of bytes associated with the
58
+
entry_. This value represents the length of
59
+
the "formatted" portion of the entry. This
60
+
"formatted" region is sometimes followed by
61
+
the "unformatted" region composed of nul
62
+
terminated strings, with termination signalled
63
+
by a two nul characters in series.
64
+
raw : The raw bytes of the entry. This includes the
65
+
"formatted" portion of the entry, the
66
+
"unformatted" strings portion of the entry,
67
+
and the two terminating nul characters.
68
+
type : The type of the entry. This value is the same
69
+
as found in the directory name. It indicates
70
+
how the rest of the entry should be
71
+
interpreted.
72
+
instance: The instance ordinal of the entry for the
73
+
given type. This value is the same as found
74
+
in the parent directory name.
75
+
position: The position of the entry within the entirety
76
+
of the entirety.
77
+
78
+
=== Entry Specialization ===
79
+
80
+
Some entry types may have other information available in
81
+
sysfs.
82
+
83
+
--- Type 15 - System Event Log ---
84
+
85
+
This entry allows the firmware to export a log of
86
+
events the system has taken. This information is
87
+
typically backed by nvram, but the implementation
88
+
details are abstracted by this table. This entries data
89
+
is exported in the directory:
90
+
91
+
/sys/firmware/dmi/entries/15-0/system_event_log
92
+
93
+
and has the following attributes (documented in the
94
+
SMBIOS / DMI specification under "System Event Log (Type 15)":
95
+
96
+
area_length
97
+
header_start_offset
98
+
data_start_offset
99
+
access_method
100
+
status
101
+
change_token
102
+
access_method_address
103
+
header_format
104
+
per_log_type_descriptor_length
105
+
type_descriptors_supported_count
106
+
107
+
As well, the kernel exports the binary attribute:
108
+
109
+
raw_event_log : The raw binary bits of the event log
110
+
as described by the DMI entry.