1What:		/sys/class/firmware-attributes/*/attributes/*/
2Date:		February 2021
3KernelVersion:	5.11
4Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
5		Mario Limonciello <mario.limonciello@dell.com>,
6		Prasanth KSR <prasanth.ksr@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		Mario Limonciello <mario.limonciello@dell.com>,
134		Prasanth KSR <prasanth.ksr@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
165		mechanism:
166					The means of authentication.  This attribute is mandatory.
167					Only supported type currently is "password".
168
169		max_password_length:
170					A file that can be read to obtain the
171					maximum length of the Password
172
173		min_password_length:
174					A file that can be read to obtain the
175					minimum length of the Password
176
177		current_password:
178					A write only value used for privileged access such as
179					setting	attributes when a system or admin password is set
180					or resetting to a new password
181
182					This attribute is mandatory when mechanism == "password".
183
184		new_password:
185					A write only value that when used in tandem with
186					current_password will reset a system or admin password.
187
188		Note, password management is session specific. If Admin password is set,
189		same password must be written into current_password file (required for
190		password-validation) and must be cleared once the session is over.
191		For example::
192
193			echo "password" > current_password
194			echo "disabled" > TouchScreen/current_value
195			echo "" > current_password
196
197		Drivers may emit a CHANGE uevent when a password is set or unset
198		userspace may check it again.
199
200		On Dell systems, if Admin password is set, then all BIOS attributes
201		require password validation.
202
203What:		/sys/class/firmware-attributes/*/attributes/pending_reboot
204Date:		February 2021
205KernelVersion:	5.11
206Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
207		Mario Limonciello <mario.limonciello@dell.com>,
208		Prasanth KSR <prasanth.ksr@dell.com>
209Description:
210		A read-only attribute reads 1 if a reboot is necessary to apply
211		pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
212		generated when it changes to 1.
213
214			==	=========================================
215			0	All BIOS attributes setting are current
216			1	A reboot is necessary to get pending BIOS
217			        attribute changes applied
218			==	=========================================
219
220		Note, userspace applications need to follow below steps for efficient
221		BIOS management,
222
223		1.	Check if admin password is set. If yes, follow session method for
224			password management as briefed under authentication section above.
225		2.	Before setting any attribute, check if it has any modifiers
226			or value_modifiers. If yes, incorporate them and then modify
227			attribute.
228
229		Drivers may emit a CHANGE uevent when this value changes and userspace
230		may check it again.
231
232What:		/sys/class/firmware-attributes/*/attributes/reset_bios
233Date:		February 2021
234KernelVersion:	5.11
235Contact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
236		Mario Limonciello <mario.limonciello@dell.com>,
237		Prasanth KSR <prasanth.ksr@dell.com>
238Description:
239		This attribute can be used to reset the BIOS Configuration.
240		Specifically, it tells which type of reset BIOS configuration is being
241		requested on the host.
242
243		Reading from it returns a list of supported options encoded as:
244
245			- 'builtinsafe' (Built in safe configuration profile)
246			- 'lastknowngood' (Last known good saved configuration profile)
247			- 'factory' (Default factory settings configuration profile)
248			- 'custom' (Custom saved configuration profile)
249
250		The currently selected option is printed in square brackets as
251		shown below::
252
253		    # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
254		    # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
255		    # builtinsafe lastknowngood [factory] custom
256
257		Note that any changes to this attribute requires a reboot
258		for changes to take effect.
259