xref: /linux/Documentation/ABI/testing/sysfs-class-firmware-attributes (revision e8a60aa7404bfef37705da5607c97737073ac38d)
1*e8a60aa7SDivya BharathiWhat:		/sys/class/firmware-attributes/*/attributes/*/
2*e8a60aa7SDivya BharathiDate:		February 2021
3*e8a60aa7SDivya BharathiKernelVersion:	5.11
4*e8a60aa7SDivya BharathiContact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
5*e8a60aa7SDivya Bharathi		Mario Limonciello <mario.limonciello@dell.com>,
6*e8a60aa7SDivya Bharathi		Prasanth KSR <prasanth.ksr@dell.com>
7*e8a60aa7SDivya BharathiDescription:
8*e8a60aa7SDivya Bharathi		A sysfs interface for systems management software to enable
9*e8a60aa7SDivya Bharathi		configuration capability on supported systems.  This directory
10*e8a60aa7SDivya Bharathi		exposes interfaces for interacting with configuration options.
11*e8a60aa7SDivya Bharathi
12*e8a60aa7SDivya Bharathi		Unless otherwise specified in an attribute description all attributes are optional
13*e8a60aa7SDivya Bharathi		and will accept UTF-8 input.
14*e8a60aa7SDivya Bharathi
15*e8a60aa7SDivya Bharathi		type: A file that can be read to obtain the type of attribute.  This attribute is
16*e8a60aa7SDivya Bharathi			mandatory.
17*e8a60aa7SDivya Bharathi
18*e8a60aa7SDivya Bharathi		The following are known types:
19*e8a60aa7SDivya Bharathi			- enumeration: a set of pre-defined valid values
20*e8a60aa7SDivya Bharathi			- integer: a range of numerical values
21*e8a60aa7SDivya Bharathi			- string
22*e8a60aa7SDivya Bharathi
23*e8a60aa7SDivya Bharathi		All attribute types support the following values:
24*e8a60aa7SDivya Bharathi
25*e8a60aa7SDivya Bharathi		current_value:	A file that can be read to obtain the current
26*e8a60aa7SDivya Bharathi				value of the <attr>.
27*e8a60aa7SDivya Bharathi
28*e8a60aa7SDivya Bharathi				This file can also be written to in order to update the value of a
29*e8a60aa7SDivya Bharathi				<attr>
30*e8a60aa7SDivya Bharathi
31*e8a60aa7SDivya Bharathi				This attribute is mandatory.
32*e8a60aa7SDivya Bharathi
33*e8a60aa7SDivya Bharathi		default_value:	A file that can be read to obtain the default
34*e8a60aa7SDivya Bharathi				value of the <attr>
35*e8a60aa7SDivya Bharathi
36*e8a60aa7SDivya Bharathi		display_name:	A file that can be read to obtain a user friendly
37*e8a60aa7SDivya Bharathi				description of the at <attr>
38*e8a60aa7SDivya Bharathi
39*e8a60aa7SDivya Bharathi		display_name_language_code:	A file that can be read to obtain
40*e8a60aa7SDivya Bharathi						the IETF language tag corresponding to the
41*e8a60aa7SDivya Bharathi						"display_name" of the <attr>
42*e8a60aa7SDivya Bharathi
43*e8a60aa7SDivya Bharathi		"enumeration"-type specific properties:
44*e8a60aa7SDivya Bharathi
45*e8a60aa7SDivya Bharathi		possible_values:	A file that can be read to obtain the possible
46*e8a60aa7SDivya Bharathi					values of the <attr>. Values are separated using
47*e8a60aa7SDivya Bharathi					semi-colon (``;``).
48*e8a60aa7SDivya Bharathi
49*e8a60aa7SDivya Bharathi		"integer"-type specific properties:
50*e8a60aa7SDivya Bharathi
51*e8a60aa7SDivya Bharathi		min_value:	A file that can be read to obtain the lower
52*e8a60aa7SDivya Bharathi				bound value of the <attr>
53*e8a60aa7SDivya Bharathi
54*e8a60aa7SDivya Bharathi		max_value:	A file that can be read to obtain the upper
55*e8a60aa7SDivya Bharathi				bound value of the <attr>
56*e8a60aa7SDivya Bharathi
57*e8a60aa7SDivya Bharathi		scalar_increment:	A file that can be read to obtain the scalar value used for
58*e8a60aa7SDivya Bharathi					increments of current_value this attribute accepts.
59*e8a60aa7SDivya Bharathi
60*e8a60aa7SDivya Bharathi		"string"-type specific properties:
61*e8a60aa7SDivya Bharathi
62*e8a60aa7SDivya Bharathi		max_length:	A file that can be read to obtain the maximum
63*e8a60aa7SDivya Bharathi				length value of the <attr>
64*e8a60aa7SDivya Bharathi
65*e8a60aa7SDivya Bharathi		min_length:	A file that can be read to obtain the minimum
66*e8a60aa7SDivya Bharathi				length value of the <attr>
67*e8a60aa7SDivya Bharathi
68*e8a60aa7SDivya Bharathi		Dell specific class extensions
69*e8a60aa7SDivya Bharathi		--------------------------
70*e8a60aa7SDivya Bharathi
71*e8a60aa7SDivya Bharathi		On Dell systems the following additional attributes are available:
72*e8a60aa7SDivya Bharathi
73*e8a60aa7SDivya Bharathi		dell_modifier:	A file that can be read to obtain attribute-level
74*e8a60aa7SDivya Bharathi				dependency rule. It says an attribute X will become read-only or
75*e8a60aa7SDivya Bharathi				suppressed, if/if-not attribute Y is configured.
76*e8a60aa7SDivya Bharathi
77*e8a60aa7SDivya Bharathi				modifier rules can be in following format:
78*e8a60aa7SDivya Bharathi				[ReadOnlyIf:<attribute>=<value>]
79*e8a60aa7SDivya Bharathi				[ReadOnlyIfNot:<attribute>=<value>]
80*e8a60aa7SDivya Bharathi				[SuppressIf:<attribute>=<value>]
81*e8a60aa7SDivya Bharathi				[SuppressIfNot:<attribute>=<value>]
82*e8a60aa7SDivya Bharathi
83*e8a60aa7SDivya Bharathi				For example:
84*e8a60aa7SDivya Bharathi				AutoOnFri/dell_modifier has value,
85*e8a60aa7SDivya Bharathi					[SuppressIfNot:AutoOn=SelectDays]
86*e8a60aa7SDivya Bharathi
87*e8a60aa7SDivya Bharathi				This means AutoOnFri will be suppressed in BIOS setup if AutoOn
88*e8a60aa7SDivya Bharathi				attribute is not "SelectDays" and its value will not be effective
89*e8a60aa7SDivya Bharathi				through sysfs until this rule is met.
90*e8a60aa7SDivya Bharathi
91*e8a60aa7SDivya Bharathi		Enumeration attributes also support the following:
92*e8a60aa7SDivya Bharathi
93*e8a60aa7SDivya Bharathi		dell_value_modifier:	A file that can be read to obtain value-level dependency.
94*e8a60aa7SDivya Bharathi					This file is similar to dell_modifier but here,	an
95*e8a60aa7SDivya Bharathi					attribute's current value will be forcefully changed based
96*e8a60aa7SDivya Bharathi					dependent attributes value.
97*e8a60aa7SDivya Bharathi
98*e8a60aa7SDivya Bharathi					dell_value_modifier rules can be in following format:
99*e8a60aa7SDivya Bharathi					<value>[ForceIf:<attribute>=<value>]
100*e8a60aa7SDivya Bharathi					<value>[ForceIfNot:<attribute>=<value>]
101*e8a60aa7SDivya Bharathi
102*e8a60aa7SDivya Bharathi					For example,
103*e8a60aa7SDivya Bharathi					LegacyOrom/dell_value_modifier has value:
104*e8a60aa7SDivya Bharathi						Disabled[ForceIf:SecureBoot=Enabled]
105*e8a60aa7SDivya Bharathi					This means LegacyOrom's current value will be forced to
106*e8a60aa7SDivya Bharathi					"Disabled" in BIOS setup if SecureBoot is Enabled and its
107*e8a60aa7SDivya Bharathi					value will not be effective through sysfs until this rule is
108*e8a60aa7SDivya Bharathi					met.
109*e8a60aa7SDivya Bharathi
110*e8a60aa7SDivya BharathiWhat:		/sys/class/firmware-attributes/*/authentication/
111*e8a60aa7SDivya BharathiDate:		February 2021
112*e8a60aa7SDivya BharathiKernelVersion:	5.11
113*e8a60aa7SDivya BharathiContact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
114*e8a60aa7SDivya Bharathi		Mario Limonciello <mario.limonciello@dell.com>,
115*e8a60aa7SDivya Bharathi		Prasanth KSR <prasanth.ksr@dell.com>
116*e8a60aa7SDivya Bharathi
117*e8a60aa7SDivya Bharathi		Devices support various authentication mechanisms which can be exposed
118*e8a60aa7SDivya Bharathi		as a separate configuration object.
119*e8a60aa7SDivya Bharathi
120*e8a60aa7SDivya Bharathi		For example a "BIOS Admin" password and "System" Password can be set,
121*e8a60aa7SDivya Bharathi		reset or cleared using these attributes.
122*e8a60aa7SDivya Bharathi		- An "Admin" password is used for preventing modification to the BIOS
123*e8a60aa7SDivya Bharathi		  settings.
124*e8a60aa7SDivya Bharathi		- A "System" password is required to boot a machine.
125*e8a60aa7SDivya Bharathi
126*e8a60aa7SDivya Bharathi		Change in any of these two authentication methods will also generate an
127*e8a60aa7SDivya Bharathi		uevent KOBJ_CHANGE.
128*e8a60aa7SDivya Bharathi
129*e8a60aa7SDivya Bharathi		is_enabled:		A file that can be read to obtain a 0/1 flag to see if
130*e8a60aa7SDivya Bharathi					<attr> authentication is enabled.
131*e8a60aa7SDivya Bharathi					This attribute is mandatory.
132*e8a60aa7SDivya Bharathi
133*e8a60aa7SDivya Bharathi		role:			The type of authentication used.
134*e8a60aa7SDivya Bharathi					This attribute is mandatory.
135*e8a60aa7SDivya Bharathi					Known types:
136*e8a60aa7SDivya Bharathi						bios-admin: Representing BIOS administrator password
137*e8a60aa7SDivya Bharathi						power-on: Representing a password required to use
138*e8a60aa7SDivya Bharathi							  the system
139*e8a60aa7SDivya Bharathi
140*e8a60aa7SDivya Bharathi		mechanism:		The means of authentication.  This attribute is mandatory.
141*e8a60aa7SDivya Bharathi					Only supported type currently is "password".
142*e8a60aa7SDivya Bharathi
143*e8a60aa7SDivya Bharathi		max_password_length:	A file that can be read to obtain the
144*e8a60aa7SDivya Bharathi					maximum length of the Password
145*e8a60aa7SDivya Bharathi
146*e8a60aa7SDivya Bharathi		min_password_length:	A file that can be read to obtain the
147*e8a60aa7SDivya Bharathi					minimum length of the Password
148*e8a60aa7SDivya Bharathi
149*e8a60aa7SDivya Bharathi		current_password:	A write only value used for privileged access such as
150*e8a60aa7SDivya Bharathi					setting	attributes when a system or admin password is set
151*e8a60aa7SDivya Bharathi					or resetting to a new password
152*e8a60aa7SDivya Bharathi
153*e8a60aa7SDivya Bharathi					This attribute is mandatory when mechanism == "password".
154*e8a60aa7SDivya Bharathi
155*e8a60aa7SDivya Bharathi		new_password:		A write only value that when used in tandem with
156*e8a60aa7SDivya Bharathi					current_password will reset a system or admin password.
157*e8a60aa7SDivya Bharathi
158*e8a60aa7SDivya Bharathi		Note, password management is session specific. If Admin password is set,
159*e8a60aa7SDivya Bharathi		same password must be written into current_password file (required for
160*e8a60aa7SDivya Bharathi		password-validation) and must be cleared once the session is over.
161*e8a60aa7SDivya Bharathi		For example:
162*e8a60aa7SDivya Bharathi			echo "password" > current_password
163*e8a60aa7SDivya Bharathi			echo "disabled" > TouchScreen/current_value
164*e8a60aa7SDivya Bharathi			echo "" > current_password
165*e8a60aa7SDivya Bharathi
166*e8a60aa7SDivya Bharathi		Drivers may emit a CHANGE uevent when a password is set or unset
167*e8a60aa7SDivya Bharathi		userspace may check it again.
168*e8a60aa7SDivya Bharathi
169*e8a60aa7SDivya Bharathi		On Dell systems, if Admin password is set, then all BIOS attributes
170*e8a60aa7SDivya Bharathi		require password validation.
171*e8a60aa7SDivya Bharathi
172*e8a60aa7SDivya BharathiWhat:		/sys/class/firmware-attributes/*/attributes/pending_reboot
173*e8a60aa7SDivya BharathiDate:		February 2021
174*e8a60aa7SDivya BharathiKernelVersion:	5.11
175*e8a60aa7SDivya BharathiContact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
176*e8a60aa7SDivya Bharathi		Mario Limonciello <mario.limonciello@dell.com>,
177*e8a60aa7SDivya Bharathi		Prasanth KSR <prasanth.ksr@dell.com>
178*e8a60aa7SDivya BharathiDescription:
179*e8a60aa7SDivya Bharathi		A read-only attribute reads 1 if a reboot is necessary to apply
180*e8a60aa7SDivya Bharathi		pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
181*e8a60aa7SDivya Bharathi		generated when it changes to 1.
182*e8a60aa7SDivya Bharathi
183*e8a60aa7SDivya Bharathi			0:	All BIOS attributes setting are current
184*e8a60aa7SDivya Bharathi			1:	A reboot is necessary to get pending BIOS attribute changes
185*e8a60aa7SDivya Bharathi				applied
186*e8a60aa7SDivya Bharathi
187*e8a60aa7SDivya Bharathi		Note, userspace applications need to follow below steps for efficient
188*e8a60aa7SDivya Bharathi		BIOS management,
189*e8a60aa7SDivya Bharathi		1.	Check if admin password is set. If yes, follow session method for
190*e8a60aa7SDivya Bharathi			password management as briefed under authentication section above.
191*e8a60aa7SDivya Bharathi		2.	Before setting any attribute, check if it has any modifiers
192*e8a60aa7SDivya Bharathi			or value_modifiers. If yes, incorporate them and then modify
193*e8a60aa7SDivya Bharathi			attribute.
194*e8a60aa7SDivya Bharathi
195*e8a60aa7SDivya Bharathi		Drivers may emit a CHANGE uevent when this value changes and userspace
196*e8a60aa7SDivya Bharathi		may check it again.
197*e8a60aa7SDivya Bharathi
198*e8a60aa7SDivya BharathiWhat:		/sys/class/firmware-attributes/*/attributes/reset_bios
199*e8a60aa7SDivya BharathiDate:		February 2021
200*e8a60aa7SDivya BharathiKernelVersion:	5.11
201*e8a60aa7SDivya BharathiContact:	Divya Bharathi <Divya.Bharathi@Dell.com>,
202*e8a60aa7SDivya Bharathi		Mario Limonciello <mario.limonciello@dell.com>,
203*e8a60aa7SDivya Bharathi		Prasanth KSR <prasanth.ksr@dell.com>
204*e8a60aa7SDivya BharathiDescription:
205*e8a60aa7SDivya Bharathi		This attribute can be used to reset the BIOS Configuration.
206*e8a60aa7SDivya Bharathi		Specifically, it tells which type of reset BIOS configuration is being
207*e8a60aa7SDivya Bharathi		requested on the host.
208*e8a60aa7SDivya Bharathi
209*e8a60aa7SDivya Bharathi		Reading from it returns a list of supported options encoded as:
210*e8a60aa7SDivya Bharathi
211*e8a60aa7SDivya Bharathi			'builtinsafe' (Built in safe configuration profile)
212*e8a60aa7SDivya Bharathi			'lastknowngood' (Last known good saved configuration profile)
213*e8a60aa7SDivya Bharathi			'factory' (Default factory settings configuration profile)
214*e8a60aa7SDivya Bharathi			'custom' (Custom saved configuration profile)
215*e8a60aa7SDivya Bharathi
216*e8a60aa7SDivya Bharathi		The currently selected option is printed in square brackets as
217*e8a60aa7SDivya Bharathi		shown below:
218*e8a60aa7SDivya Bharathi
219*e8a60aa7SDivya Bharathi		# echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
220*e8a60aa7SDivya Bharathi		# cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
221*e8a60aa7SDivya Bharathi		# builtinsafe lastknowngood [factory] custom
222*e8a60aa7SDivya Bharathi
223*e8a60aa7SDivya Bharathi		Note that any changes to this attribute requires a reboot
224*e8a60aa7SDivya Bharathi		for changes to take effect.
225