Documentation/drivers/cfr.md

   1 # CFR - coreboot form representation
   2
   3 This documents the API exposed by coreboot to be consumed by
   4 loaded OS image or payload.
   5
   6 ## Problem Statement
   7
   8 As per coreboot design there's no UI present to change firmware
   9 related options like "Hyper-Theading Enable". There's no way of
  10 knowing what options are supported, if they are supported in the
  11 current configuration and what they do.
  12
  13 The `USE_OPTION_TABLE` Kconfig allows to integrate a list of
  14 mainboard specific options into coreboot tables when the option
  15 API is using the *CMOS NVRAM*. It has no meaning if another option
  16 API is being used.
  17
  18 ## Design Proposal
  19
  20 Propose a new coreboot table that is independent from the option
  21 backend. The coreboot table is generated from coreboot ramstage
  22 code.
  23
  24 Every possible boot option is described by its name, the user
  25 visible name, a help text, a default value and status flags.
  26 All strings are in ASCII.
  27
  28 The boot options are grouped into forms, where each form hold
  29 one or more options. Boot options that are not used in the current
  30 boot flow, and are never reachable should be marked as hidden.
  31 Dependecies between options can be defined in the code and should
  32 be evaluated by the CFR parser/UI.
  33
  34 A boot option can be one of the following types:
  35 - boolean
  36 - number
  37 - enum
  38 - string
  39
  40 All of the information is *Position Independent Data*. That is, it is
  41 safe to relocate any of the information without its meaning/correctness
  42 changing.
  43
  44 CFR records form a tree structure. Every record starts with a `tag`
  45 and a `size` field as generic header:
  46
  47 ```C
  48 struct __packed lb_cfr_header {
  49   uint32_t tag;
  50   uint32_t size;
  51 };
  52 ```
  53
  54 The size of a record includes the size of its own fields plus the size of all
  55 child records. A record can have none or multiple child records.
  56 The record `tag` must be known by the parser to parse the record and its
  57 sub records. If it is not known to the parser it can simply skip it by
  58 jumping `size` bytes forward.
  59
  60 The coreboot table containing the CFR tree has the tag `LB_TAG_CFR`.
  61
  62 The public API can be found in
  63 `src/commonlib/include/commonlib/cfr.h` and
  64 `src/commonlib/include/commonlib/coreboot_tables.h`.
  65
  66 ## Implementation design
  67 ### Tags
  68 Tags identify the structure defined in `src/commonlib/include/commonlib/cfr.h`.
  69 Every struct might be immediately followed by additional structs (so called
  70 sub nodes), having their own tag and size field. The sum of all sub nodes size
  71 fields plus the size of the struct itself equals the size field.
  72
  73 * CFR_TAG_OPTION_FORM
  74
  75    Used in `struct lb_cfr_option_form` to describe a group of options. Every
  76    sub node is one option that should be displayed in the order found in
  77    memory.
  78
  79    Allowed sub nodes:
  80     - `CFR_TAG_OPTION_ENUM`
  81     - `CFR_TAG_OPTION_NUMBER`
  82     - `CFR_TAG_OPTION_BOOL`
  83     - `CFR_TAG_OPTION_VARCHAR`
  84     - `CFR_TAG_OPTION_FORM`
  85     - `CFR_TAG_OPTION_COMMENT`
  86     - `CFR_TAG_VARCHAR_UI_NAME`
  87
  88    Required sub nodes:
  89     - `CFR_TAG_VARCHAR_UI_NAME`
  90
  91 * CFR_TAG_ENUM_VALUE
  92
  93    Used in `struct lb_cfr_enum_value` to describe a numeric value to be
  94    used in a parent `CFR_TAG_OPTION_ENUM`.
  95
  96    Allowed sub nodes:
  97      - `CFR_TAG_VARCHAR_UI_NAME`
  98
  99    Required sub nodes:
 100      - `CFR_TAG_VARCHAR_UI_NAME`
 101
 102 * CFR_TAG_OPTION_ENUM
 103
 104    Used in `struct lb_cfr_numeric_option` to describe a numeric variable with
 105    a predefined selection of possible values in the referenced variable.
 106
 107    Allowed sub nodes:
 108      - `CFR_TAG_VARCHAR_OPT_NAME`
 109      - `CFR_TAG_VARCHAR_UI_NAME`
 110      - `CFR_TAG_ENUM_VALUE`
 111      - `CFR_TAG_VARCHAR_UI_HELPTEXT`
 112
 113    Required sub nodes:
 114      - `CFR_TAG_VARCHAR_OPT_NAME`
 115      - `CFR_TAG_VARCHAR_UI_NAME`
 116      - `CFR_TAG_ENUM_VALUE`
 117
 118 * CFR_TAG_OPTION_NUMBER
 119
 120    Used in `struct lb_cfr_numeric_option` to describe a numeric variable with
 121    any possible value in the referenced variable.
 122
 123    Allowed sub nodes:
 124      - `CFR_TAG_VARCHAR_OPT_NAME`
 125      - `CFR_TAG_VARCHAR_UI_NAME`
 126      - `CFR_TAG_VARCHAR_UI_HELPTEXT`
 127
 128    Required sub nodes:
 129      - `CFR_TAG_VARCHAR_OPT_NAME`
 130      - `CFR_TAG_VARCHAR_UI_NAME`
 131
 132 * CFR_TAG_OPTION_BOOL
 133
 134    Used in `struct lb_cfr_numeric_option` to describe a numeric variable with
 135    the possible values [0, 1] in the referenced variable.
 136
 137    Allowed sub nodes:
 138      - `CFR_TAG_VARCHAR_OPT_NAME`
 139      - `CFR_TAG_VARCHAR_UI_NAME`
 140      - `CFR_TAG_VARCHAR_UI_HELPTEXT`
 141
 142    Required sub nodes:
 143      - `CFR_TAG_VARCHAR_OPT_NAME`
 144      - `CFR_TAG_VARCHAR_UI_NAME`
 145
 146 * CFR_TAG_OPTION_VARCHAR
 147
 148    Used in `struct lb_cfr_varchar_option` to describe an ASCII string
 149    stored in the referenced variable.
 150
 151    *Example:* Linux kernel cmdline.
 152
 153    Allowed sub nodes:
 154      - `CFR_TAG_VARCHAR_DEF_VALUE`
 155      - `CFR_TAG_VARCHAR_OPT_NAME`
 156      - `CFR_TAG_VARCHAR_UI_NAME`
 157      - `CFR_TAG_VARCHAR_UI_HELPTEXT`
 158
 159    Required sub nodes:
 160      - `CFR_TAG_VARCHAR_DEF_VALUE`
 161      - `CFR_TAG_VARCHAR_OPT_NAME`
 162      - `CFR_TAG_VARCHAR_UI_NAME`
 163
 164 * CFR_TAG_OPTION_COMMENT
 165
 166    Used in `struct lb_cfr_option_comment` to describe an ASCII string visible
 167    to the user, but doesn't reference a variable. Informal use only.
 168
 169    Allowed sub nodes:
 170      - `CFR_TAG_VARCHAR_UI_NAME`
 171      - `CFR_TAG_VARCHAR_UI_HELPTEXT`
 172
 173    Required sub nodes:
 174      - `CFR_TAG_VARCHAR_UI_NAME`
 175
 176 * CFR_TAG_VARCHAR_OPT_NAME
 177
 178    Used in `struct lb_cfr_varbinary` to describe the option name used by
 179    coreboot's code. It thus must match what is used in code by
 180    `get_uint_option()`.
 181
 182    Is not user visible.
 183
 184 * CFR_TAG_VARCHAR_UI_NAME
 185
 186    Used in `struct lb_cfr_varbinary`
 187
 188    User visible name of the option.
 189
 190 * CFR_TAG_VARCHAR_UI_HELPTEXT
 191
 192    Used in `struct lb_cfr_varbinary`
 193
 194    Optional user visible description what is changed by this option.
 195
 196 * CFR_TAG_VARCHAR_DEF_VALUE
 197
 198    Used in `struct lb_cfr_varbinary`
 199
 200    Default value in case the variable is not present.
 201
 202 ### Flags
 203
 204 The optional flags describe the visibilty of the option and the
 205 effect on the non-volatile variable.
 206
 207 * `CFR_OPTFLAG_READONLY`
 208
 209    Prevents writes to the variable.
 210
 211 * `CFR_OPTFLAG_INACTIVE`
 212
 213    Implies `READONLY`. The option is visible, but cannot be modified
 214    because one of the dependencies are not given. However there's a
 215    possibility to enable the option by changing runtime configuration.
 216
 217    *For example:* Setting SATA mode, but SATA is globally disabled.
 218
 219 * `CFR_OPTFLAG_SUPPRESS`
 220
 221    Runtime code sets this flag to indicate that the option has no effect
 222    and is never reachable, not even by changing runtime configuration.
 223    This option is never shown in the UI.
 224
 225 * `CFR_OPTFLAG_VOLATILE`
 226
 227    Implies `READONLY`.
 228    The option is not backed by a non-volatile variable. This is useful
 229    to display the current state of a specific component, a dependency or
 230    a serial number. This information could be passed in a new coreboot
 231    table, but it not useful other than to be shown at this spot in the
 232    UI.
 233
 234 * `CFR_OPTFLAG_RUNTIME`
 235
 236    The option is allowed to be changed by a post payload entity. On UEFI
 237    this sets the `EFI_VARIABLE_RUNTIME_ACCESS` attribute.
 238    It is out of scope of this specification how non runtime variables
 239    are protected after the payload has hand over control.
 240
 241 ### Example
 242
 243 To display a boolean option with the label `Boolean`, that default value
 244 is `true`, on a form called `test`, that modifies the variable `First`
 245 the following structure will be generated:
 246
 247 ```
 248 struct lb_cfr_option_form {
 249   uint32_t tag;                  = CFR_TAG_OPTION_FORM
 250   uint32_t size;                 = sizeof(struct lb_cfr_option_form) +
 251                                    sizeof(struct lb_cfr_varbinary) +
 252                                    strlen(name) + 1 + 3 +
 253                                    sizeof(struct lb_cfr_numeric_option) +
 254                                    sizeof(struct lb_cfr_varbinary) +
 255                                    strlen(optname) + 1 + 2 +
 256                                    sizeof(struct lb_cfr_varbinary) +
 257                                    strlen(uiname) + 1 = 120
 258   uint64_t object_id;            = 1
 259   uint64_t dependency_id;        = 0
 260   uint32_t flags;                = 0
 261 }
 262   struct lb_cfr_varbinary {
 263     uint32_t tag;                = CFR_TAG_VARCHAR_UI_NAME
 264     uint32_t size;               = sizeof(struct lb_cfr_varbinary) +
 265                                    strlen(name) + 1 + 3 = 20
 266     uint32_t data_length;        = strlen(name) + 1
 267   };
 268     char name[5];                = "test"
 269     char padding[3];
 270   struct lb_cfr_numeric_option {
 271     uint32_t tag;                = CFR_TAG_OPTION_BOOL
 272     uint32_t size;               = sizeof(struct lb_cfr_numeric_option) +
 273                                    sizeof(struct lb_cfr_varbinary) +
 274                                    strlen(optname) + 1 + 2 +
 275                                    sizeof(struct lb_cfr_varbinary) +
 276                                    strlen(uiname) + 1 = 72
 277     uint64_t object_id;          = 2
 278     uint64_t dependency_id;      = 0
 279     uint32_t flags;              = 0
 280     uint32_t default_value;      = true
 281   };
 282     struct lb_cfr_varbinary {
 283       uint32_t tag;              = CFR_TAG_VARCHAR_OPT_NAME
 284       uint32_t size;             = sizeof(struct lb_cfr_varbinary) +
 285                                    strlen(optname) + 1 + 2 = 20
 286       uint32_t data_length;      = strlen(optname) + 1 = 6
 287     };
 288       char optname[6];           = "First"
 289       char padding[2];
 290     struct lb_cfr_varbinary {
 291       uint32_t tag;              = CFR_TAG_VARCHAR_UI_NAME
 292       uint32_t size;             = sizeof(struct lb_cfr_varbinary) +
 293                                    strlen(uiname) + 1 = 20
 294       uint32_t data_length;      = strlen(uiname) + 1 = 8
 295     };
 296       char uiname[8];            = "Boolean"
 297 ```