Documentation/ABI/testing/sysfs-class-firmware-attributes

   1 What:           /sys/class/firmware-attributes/*/attributes/*/
   2 Date:           February 2021
   3 KernelVersion:  5.11
   4 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
   5                 Mario Limonciello <mario.limonciello@dell.com>,
   6                 Prasanth KSR <prasanth.ksr@dell.com>
   7 Description:
   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
 129 What:           /sys/class/firmware-attributes/*/authentication/
 130 Date:           February 2021
 131 KernelVersion:  5.11
 132 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 133                 Mario Limonciello <mario.limonciello@dell.com>,
 134                 Prasanth KSR <prasanth.ksr@dell.com>
 135 Description:
 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
 203 What:           /sys/class/firmware-attributes/*/attributes/pending_reboot
 204 Date:           February 2021
 205 KernelVersion:  5.11
 206 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 207                 Mario Limonciello <mario.limonciello@dell.com>,
 208                 Prasanth KSR <prasanth.ksr@dell.com>
 209 Description:
 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
 232 What:           /sys/class/firmware-attributes/*/attributes/reset_bios
 233 Date:           February 2021
 234 KernelVersion:  5.11
 235 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 236                 Mario Limonciello <mario.limonciello@dell.com>,
 237                 Prasanth KSR <prasanth.ksr@dell.com>
 238 Description:
 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.