diff options
Diffstat (limited to 'Documentation/ABI/testing/sysfs-class-firmware-attributes')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-firmware-attributes | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes new file mode 100644 index 000000000000..8ea59fea4709 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -0,0 +1,258 @@ +What: /sys/class/firmware-attributes/*/attributes/*/ +Date: February 2021 +KernelVersion: 5.11 +Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, + Mario Limonciello <mario.limonciello@dell.com>, + Prasanth KSR <prasanth.ksr@dell.com> +Description: + A sysfs interface for systems management software to enable + configuration capability on supported systems. This directory + exposes interfaces for interacting with configuration options. + + Unless otherwise specified in an attribute description all attributes are optional + and will accept UTF-8 input. + + type: + A file that can be read to obtain the type of attribute. + This attribute is mandatory. + + The following are known types: + + - enumeration: a set of pre-defined valid values + - integer: a range of numerical values + - string + + All attribute types support the following values: + + current_value: + A file that can be read to obtain the current + value of the <attr>. + + This file can also be written to in order to update the value of a + <attr> + + This attribute is mandatory. + + default_value: + A file that can be read to obtain the default + value of the <attr> + + display_name: + A file that can be read to obtain a user friendly + description of the at <attr> + + display_name_language_code: + A file that can be read to obtain + the IETF language tag corresponding to the + "display_name" of the <attr> + + "enumeration"-type specific properties: + + possible_values: + A file that can be read to obtain the possible + values of the <attr>. Values are separated using + semi-colon (``;``). + + "integer"-type specific properties: + + min_value: + A file that can be read to obtain the lower + bound value of the <attr> + + max_value: + A file that can be read to obtain the upper + bound value of the <attr> + + scalar_increment: + A file that can be read to obtain the scalar value used for + increments of current_value this attribute accepts. + + "string"-type specific properties: + + max_length: + A file that can be read to obtain the maximum + length value of the <attr> + + min_length: + A file that can be read to obtain the minimum + length value of the <attr> + + Dell specific class extensions + ------------------------------ + + On Dell systems the following additional attributes are available: + + dell_modifier: + A file that can be read to obtain attribute-level + dependency rule. It says an attribute X will become read-only or + suppressed, if/if-not attribute Y is configured. + + modifier rules can be in following format:: + + [ReadOnlyIf:<attribute>=<value>] + [ReadOnlyIfNot:<attribute>=<value>] + [SuppressIf:<attribute>=<value>] + [SuppressIfNot:<attribute>=<value>] + + For example:: + + AutoOnFri/dell_modifier has value, + [SuppressIfNot:AutoOn=SelectDays] + + This means AutoOnFri will be suppressed in BIOS setup if AutoOn + attribute is not "SelectDays" and its value will not be effective + through sysfs until this rule is met. + + Enumeration attributes also support the following: + + dell_value_modifier: + A file that can be read to obtain value-level dependency. + This file is similar to dell_modifier but here, an + attribute's current value will be forcefully changed based + dependent attributes value. + + dell_value_modifier rules can be in following format:: + + <value>[ForceIf:<attribute>=<value>] + <value>[ForceIfNot:<attribute>=<value>] + + For example: + + LegacyOrom/dell_value_modifier has value: + Disabled[ForceIf:SecureBoot=Enabled] + + This means LegacyOrom's current value will be forced to + "Disabled" in BIOS setup if SecureBoot is Enabled and its + value will not be effective through sysfs until this rule is + met. + +What: /sys/class/firmware-attributes/*/authentication/ +Date: February 2021 +KernelVersion: 5.11 +Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, + Mario Limonciello <mario.limonciello@dell.com>, + Prasanth KSR <prasanth.ksr@dell.com> +Description: + Devices support various authentication mechanisms which can be exposed + as a separate configuration object. + + For example a "BIOS Admin" password and "System" Password can be set, + reset or cleared using these attributes. + + - An "Admin" password is used for preventing modification to the BIOS + settings. + - A "System" password is required to boot a machine. + + Change in any of these two authentication methods will also generate an + uevent KOBJ_CHANGE. + + is_enabled: + A file that can be read to obtain a 0/1 flag to see if + <attr> authentication is enabled. + This attribute is mandatory. + + role: + The type of authentication used. + This attribute is mandatory. + + Known types: + bios-admin: + Representing BIOS administrator password + power-on: + Representing a password required to use + the system + + mechanism: + The means of authentication. This attribute is mandatory. + Only supported type currently is "password". + + max_password_length: + A file that can be read to obtain the + maximum length of the Password + + min_password_length: + A file that can be read to obtain the + minimum length of the Password + + current_password: + A write only value used for privileged access such as + setting attributes when a system or admin password is set + or resetting to a new password + + This attribute is mandatory when mechanism == "password". + + new_password: + A write only value that when used in tandem with + current_password will reset a system or admin password. + + Note, password management is session specific. If Admin password is set, + same password must be written into current_password file (required for + password-validation) and must be cleared once the session is over. + For example:: + + echo "password" > current_password + echo "disabled" > TouchScreen/current_value + echo "" > current_password + + Drivers may emit a CHANGE uevent when a password is set or unset + userspace may check it again. + + On Dell systems, if Admin password is set, then all BIOS attributes + require password validation. + +What: /sys/class/firmware-attributes/*/attributes/pending_reboot +Date: February 2021 +KernelVersion: 5.11 +Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, + Mario Limonciello <mario.limonciello@dell.com>, + Prasanth KSR <prasanth.ksr@dell.com> +Description: + A read-only attribute reads 1 if a reboot is necessary to apply + pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is + generated when it changes to 1. + + == ========================================= + 0 All BIOS attributes setting are current + 1 A reboot is necessary to get pending BIOS + attribute changes applied + == ========================================= + + Note, userspace applications need to follow below steps for efficient + BIOS management, + + 1. Check if admin password is set. If yes, follow session method for + password management as briefed under authentication section above. + 2. Before setting any attribute, check if it has any modifiers + or value_modifiers. If yes, incorporate them and then modify + attribute. + + Drivers may emit a CHANGE uevent when this value changes and userspace + may check it again. + +What: /sys/class/firmware-attributes/*/attributes/reset_bios +Date: February 2021 +KernelVersion: 5.11 +Contact: Divya Bharathi <Divya.Bharathi@Dell.com>, + Mario Limonciello <mario.limonciello@dell.com>, + Prasanth KSR <prasanth.ksr@dell.com> +Description: + This attribute can be used to reset the BIOS Configuration. + Specifically, it tells which type of reset BIOS configuration is being + requested on the host. + + Reading from it returns a list of supported options encoded as: + + - 'builtinsafe' (Built in safe configuration profile) + - 'lastknowngood' (Last known good saved configuration profile) + - 'factory' (Default factory settings configuration profile) + - 'custom' (Custom saved configuration profile) + + The currently selected option is printed in square brackets as + shown below:: + + # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios + # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios + # builtinsafe lastknowngood [factory] custom + + Note that any changes to this attribute requires a reboot + for changes to take effect. |