1What:		/sys/class/firmware-attributes/*/attributes/*/
2Date:		February 2021
3KernelVersion:	5.11
4Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
5		Prasanth KSR <prasanth.ksr@dell.com>
6		Dell.Client.Kernel@dell.com
7Description:
8		A sysfs interface for systems management software to enable
9		configuration capability on supported systems.  This directory
10		exposes interfaces for interacting with configuration options.
11
12		Unless otherwise specified in an attribute description all attributes are optional
13		and will accept UTF-8 input.
14
15		type:
16		    A file that can be read to obtain the type of attribute.
17		    This attribute is mandatory.
18
19		The following are known types:
20
21			- enumeration: a set of pre-defined valid values
22			- integer: a range of numerical values
23			- string
24
25		All attribute types support the following values:
26
27		current_value:
28				A file that can be read to obtain the current
29				value of the <attr>.
30
31				This file can also be written to in order to update the value of a
32				<attr>
33
34				This attribute is mandatory.
35
36		default_value:
37				A file that can be read to obtain the default
38				value of the <attr>
39
40		display_name:
41				A file that can be read to obtain a user friendly
42				description of the at <attr>
43
44		display_name_language_code:
45						A file that can be read to obtain
46						the IETF language tag corresponding to the
47						"display_name" of the <attr>
48
49		"enumeration"-type specific properties:
50
51		possible_values:
52					A file that can be read to obtain the possible
53					values of the <attr>. Values are separated using
54					semi-colon (``;``).
55
56		"integer"-type specific properties:
57
58		min_value:
59				A file that can be read to obtain the lower
60				bound value of the <attr>
61
62		max_value:
63				A file that can be read to obtain the upper
64				bound value of the <attr>
65
66		scalar_increment:
67					A file that can be read to obtain the scalar value used for
68					increments of current_value this attribute accepts.
69
70		"string"-type specific properties:
71
72		max_length:
73				A file that can be read to obtain the maximum
74				length value of the <attr>
75
76		min_length:
77				A file that can be read to obtain the minimum
78				length value of the <attr>
79
80		Dell specific class extensions
81		------------------------------
82
83		On Dell systems the following additional attributes are available:
84
85		dell_modifier:
86				A file that can be read to obtain attribute-level
87				dependency rule. It says an attribute X will become read-only or
88				suppressed, if/if-not attribute Y is configured.
89
90				modifier rules can be in following format::
91
92				    [ReadOnlyIf:<attribute>=<value>]
93				    [ReadOnlyIfNot:<attribute>=<value>]
94				    [SuppressIf:<attribute>=<value>]
95				    [SuppressIfNot:<attribute>=<value>]
96
97				For example::
98
99				    AutoOnFri/dell_modifier has value,
100					    [SuppressIfNot:AutoOn=SelectDays]
101
102				This means AutoOnFri will be suppressed in BIOS setup if AutoOn
103				attribute is not "SelectDays" and its value will not be effective
104				through sysfs until this rule is met.
105
106		Enumeration attributes also support the following:
107
108		dell_value_modifier:
109					A file that can be read to obtain value-level dependency.
110					This file is similar to dell_modifier but here,	an
111					attribute's current value will be forcefully changed based
112					dependent attributes value.
113
114					dell_value_modifier rules can be in following format::
115
116					    <value>[ForceIf:<attribute>=<value>]
117					    <value>[ForceIfNot:<attribute>=<value>]
118
119					For example::
120
121					    LegacyOrom/dell_value_modifier has value:
122						    Disabled[ForceIf:SecureBoot=Enabled]
123
124					This means LegacyOrom's current value will be forced to
125					"Disabled" in BIOS setup if SecureBoot is Enabled and its
126					value will not be effective through sysfs until this rule is
127					met.
128
129What:		/sys/class/firmware-attributes/*/authentication/
130Date:		February 2021
131KernelVersion:	5.11
132Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
133		Prasanth KSR <prasanth.ksr@dell.com>
134		Dell.Client.Kernel@dell.com
135Description:
136		Devices support various authentication mechanisms which can be exposed
137		as a separate configuration object.
138
139		For example a "BIOS Admin" password and "System" Password can be set,
140		reset or cleared using these attributes.
141
142		- An "Admin" password is used for preventing modification to the BIOS
143		  settings.
144		- A "System" password is required to boot a machine.
145
146		Change in any of these two authentication methods will also generate an
147		uevent KOBJ_CHANGE.
148
149		is_enabled:
150					A file that can be read to obtain a 0/1 flag to see if
151					<attr> authentication is enabled.
152					This attribute is mandatory.
153
154		role:
155					The type of authentication used.
156					This attribute is mandatory.
157
158					Known types:
159						bios-admin:
160							Representing BIOS administrator password
161						power-on:
162							Representing a password required to use
163							the system
164						system-mgmt:
165							Representing System Management password.
166							See Lenovo extensions section for details
167						HDD:
168							Representing HDD password
169							See Lenovo extensions section for details
170						NVMe:
171							Representing NVMe password
172							See Lenovo extensions section for details
173
174		mechanism:
175					The means of authentication.  This attribute is mandatory.
176					Only supported type currently is "password".
177
178		max_password_length:
179					A file that can be read to obtain the
180					maximum length of the Password
181
182		min_password_length:
183					A file that can be read to obtain the
184					minimum length of the Password
185
186		current_password:
187					A write only value used for privileged access such as
188					setting	attributes when a system or admin password is set
189					or resetting to a new password
190
191					This attribute is mandatory when mechanism == "password".
192
193		new_password:
194					A write only value that when used in tandem with
195					current_password will reset a system or admin password.
196
197		Note, password management is session specific. If Admin password is set,
198		same password must be written into current_password file (required for
199		password-validation) and must be cleared once the session is over.
200		For example::
201
202			echo "password" > current_password
203			echo "disabled" > TouchScreen/current_value
204			echo "" > current_password
205
206		Drivers may emit a CHANGE uevent when a password is set or unset
207		userspace may check it again.
208
209		On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes
210		require password validation.
211		On Lenovo systems if you change the Admin password the new password is not active until
212		the next boot.
213
214		Lenovo specific class extensions
215		--------------------------------
216
217		On Lenovo systems the following additional settings are available:
218
219		role: system-mgmt	This gives the same authority as the bios-admin password to control
220					security related features. The authorities allocated can be set via
221					the BIOS menu SMP Access Control Policy
222
223		role: HDD & NVMe	This password is used to unlock access to the drive at boot. Note see
224					'level' and 'index' extensions below.
225
226		lenovo_encoding:
227					The encoding method that is used. This can be either "ascii"
228					or "scancode". Default is set to "ascii"
229
230		lenovo_kbdlang:
231					The keyboard language method that is used. This is generally a
232					two char code (e.g. "us", "fr", "gr") and may vary per platform.
233					Default is set to "us"
234
235		level:
236					Available for HDD and NVMe authentication to set 'user' or 'master'
237					privilege level.
238					If only the user password is configured then this should be used to
239					unlock the drive at boot. If both master and user passwords are set
240					then either can be used. If a master password is set a user password
241					is required.
242					This attribute defaults to 'user' level
243
244		index:
245					Used with HDD and NVME authentication to set the drive index
246					that is being referenced (e.g hdd1, hdd2 etc)
247					This attribute defaults to device 1.
248
249		certificate, signature, save_signature:
250					These attributes are used for certificate based authentication. This is
251					used in conjunction with a signing server as an alternative to password
252					based authentication.
253					The user writes to the attribute(s) with a BASE64 encoded string obtained
254					from the signing server.
255					The attributes can be displayed to check the stored value.
256
257					Some usage examples:
258
259						Installing a certificate to enable feature::
260
261							echo "supervisor password" > authentication/Admin/current_password
262							echo "signed certificate" > authentication/Admin/certificate
263
264						Updating the installed certificate::
265
266							echo "signature" > authentication/Admin/signature
267							echo "signed certificate" > authentication/Admin/certificate
268
269						Removing the installed certificate::
270
271							echo "signature" > authentication/Admin/signature
272							echo "" > authentication/Admin/certificate
273
274						Changing a BIOS setting::
275
276							echo "signature" > authentication/Admin/signature
277							echo "save signature" > authentication/Admin/save_signature
278							echo Enable > attribute/PasswordBeep/current_value
279
280					You cannot enable certificate authentication if a supervisor password
281					has not been set.
282					Clearing the certificate results in no bios-admin authentication method
283					being configured allowing anyone to make changes.
284					After any of these operations the system must reboot for the changes to
285					take effect.
286
287		certificate_thumbprint:
288					Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints
289					for the certificate installed in the BIOS.
290
291		certificate_to_password:
292					Write only attribute used to switch from certificate based authentication
293					back to password based.
294					Usage::
295
296						echo "signature" > authentication/Admin/signature
297						echo "password" > authentication/Admin/certificate_to_password
298
299
300What:		/sys/class/firmware-attributes/*/attributes/pending_reboot
301Date:		February 2021
302KernelVersion:	5.11
303Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
304		Prasanth KSR <prasanth.ksr@dell.com>
305		Dell.Client.Kernel@dell.com
306Description:
307		A read-only attribute reads 1 if a reboot is necessary to apply
308		pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
309		generated when it changes to 1.
310
311			==	=========================================
312			0	All BIOS attributes setting are current
313			1	A reboot is necessary to get pending BIOS
314			        attribute changes applied
315			==	=========================================
316
317		Note, userspace applications need to follow below steps for efficient
318		BIOS management,
319
320		1.	Check if admin password is set. If yes, follow session method for
321			password management as briefed under authentication section above.
322		2.	Before setting any attribute, check if it has any modifiers
323			or value_modifiers. If yes, incorporate them and then modify
324			attribute.
325
326		Drivers may emit a CHANGE uevent when this value changes and userspace
327		may check it again.
328
329What:		/sys/class/firmware-attributes/*/attributes/reset_bios
330Date:		February 2021
331KernelVersion:	5.11
332Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
333		Prasanth KSR <prasanth.ksr@dell.com>
334		Dell.Client.Kernel@dell.com
335Description:
336		This attribute can be used to reset the BIOS Configuration.
337		Specifically, it tells which type of reset BIOS configuration is being
338		requested on the host.
339
340		Reading from it returns a list of supported options encoded as:
341
342			- 'builtinsafe' (Built in safe configuration profile)
343			- 'lastknowngood' (Last known good saved configuration profile)
344			- 'factory' (Default factory settings configuration profile)
345			- 'custom' (Custom saved configuration profile)
346
347		The currently selected option is printed in square brackets as
348		shown below::
349
350		    # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
351		    # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
352		    builtinsafe lastknowngood [factory] custom
353
354		Note that any changes to this attribute requires a reboot
355		for changes to take effect.
356
357What:		/sys/class/firmware-attributes/*/attributes/debug_cmd
358Date:		July 2021
359KernelVersion:	5.14
360Contact:	Mark Pearson <markpearson@lenovo.com>
361Description:
362		This write only attribute can be used to send debug commands to the BIOS.
363		This should only be used when recommended by the BIOS vendor. Vendors may
364		use it to enable extra debug attributes or BIOS features for testing purposes.
365
366		Note that any changes to this attribute requires a reboot for changes to take effect.
367