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                 Prasanth KSR <prasanth.ksr@dell.com>
   6                 Dell.Client.Kernel@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                 Prasanth KSR <prasanth.ksr@dell.com>
 134                 Dell.Client.Kernel@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 and Lenovo systems, if Admin password is set, then all BIOS attributes
 201                 require password validation.
 202                 On Lenovo systems if you change the Admin password the new password is not active until
 203                 the next boot.
 204
 205                 Lenovo specific class extensions
 206                 ------------------------------
 207
 208                 On Lenovo systems the following additional settings are available:
 209
 210                 lenovo_encoding:
 211                                         The encoding method that is used. This can be either "ascii"
 212                                         or "scancode". Default is set to "ascii"
 213
 214                 lenovo_kbdlang:
 215                                         The keyboard language method that is used. This is generally a
 216                                         two char code (e.g. "us", "fr", "gr") and may vary per platform.
 217                                         Default is set to "us"
 218
 219 What:           /sys/class/firmware-attributes/*/attributes/pending_reboot
 220 Date:           February 2021
 221 KernelVersion:  5.11
 222 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 223                 Prasanth KSR <prasanth.ksr@dell.com>
 224                 Dell.Client.Kernel@dell.com
 225 Description:
 226                 A read-only attribute reads 1 if a reboot is necessary to apply
 227                 pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
 228                 generated when it changes to 1.
 229
 230                         ==      =========================================
 231                         0       All BIOS attributes setting are current
 232                         1       A reboot is necessary to get pending BIOS
 233                                 attribute changes applied
 234                         ==      =========================================
 235
 236                 Note, userspace applications need to follow below steps for efficient
 237                 BIOS management,
 238
 239                 1.      Check if admin password is set. If yes, follow session method for
 240                         password management as briefed under authentication section above.
 241                 2.      Before setting any attribute, check if it has any modifiers
 242                         or value_modifiers. If yes, incorporate them and then modify
 243                         attribute.
 244
 245                 Drivers may emit a CHANGE uevent when this value changes and userspace
 246                 may check it again.
 247
 248 What:           /sys/class/firmware-attributes/*/attributes/reset_bios
 249 Date:           February 2021
 250 KernelVersion:  5.11
 251 Contact:        Divya Bharathi <Divya.Bharathi@Dell.com>,
 252                 Prasanth KSR <prasanth.ksr@dell.com>
 253                 Dell.Client.Kernel@dell.com
 254 Description:
 255                 This attribute can be used to reset the BIOS Configuration.
 256                 Specifically, it tells which type of reset BIOS configuration is being
 257                 requested on the host.
 258
 259                 Reading from it returns a list of supported options encoded as:
 260
 261                         - 'builtinsafe' (Built in safe configuration profile)
 262                         - 'lastknowngood' (Last known good saved configuration profile)
 263                         - 'factory' (Default factory settings configuration profile)
 264                         - 'custom' (Custom saved configuration profile)
 265
 266                 The currently selected option is printed in square brackets as
 267                 shown below::
 268
 269                     # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
 270                     # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
 271                     # builtinsafe lastknowngood [factory] custom
 272
 273                 Note that any changes to this attribute requires a reboot
 274                 for changes to take effect.
 275
 276 What:           /sys/class/firmware-attributes/*/attributes/debug_cmd
 277 Date:           July 2021
 278 KernelVersion:  5.14
 279 Contact:        Mark Pearson <markpearson@lenovo.com>
 280 Description:
 281                 This write only attribute can be used to send debug commands to the BIOS.
 282                 This should only be used when recommended by the BIOS vendor. Vendors may
 283                 use it to enable extra debug attributes or BIOS features for testing purposes.
 284
 285                 Note that any changes to this attribute requires a reboot for changes to take effect.