Lean Sheng Tan 1a16146795 Fix up CFR's open issues

Fix some typos and also update the naming convention of
`CFR_OPTFLAG_GRAYOUT` to `CFR_OPTFLAG_INACTIVE` as per reviews.

Signed-off-by: Lean Sheng Tan <sheng.tan@9elements.com>
Change-Id: Id66808382b93e32c58024462c18b20c2a89d6d23
Reviewed-on: https://review.coreboot.org/c/coreboot/+/85780
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-by: Christian Walter <christian.walter@9elements.com>

2024-12-30 21:27:36 +00:00

9.4 KiB

Raw Blame History

CFR - coreboot form representation

This documents the API exposed by coreboot to be consumed by loaded OS image or payload.

Problem Statement

As per coreboot design there's no UI present to change firmware related options like "Hyper-Theading Enable". There's no way of knowing what options are supported, if they are supported in the current configuration and what they do.

The USE_OPTION_TABLE Kconfig allows to integrate a list of mainboard specific options into coreboot tables when the option API is using the CMOS NVRAM. It has no meaning if another option API is being used.

Design Proposal

Propose a new coreboot table that is independent from the option backend. The coreboot table is generated from coreboot ramstage code.

Every possible boot option is described by its name, the user visible name, a help text, a default value and status flags. All strings are in ASCII.

The boot options are grouped into forms, where each form hold one or more options. Boot options that are not used in the current boot flow, and are never reachable should be marked as hidden. Dependecies between options can be defined in the code and should be evaluated by the CFR parser/UI.

A boot option can be one of the following types:

boolean
number
enum
string

All of the information is Position Independent Data. That is, it is safe to relocate any of the information without its meaning/correctness changing.

CFR records form a tree structure. Every record starts with a tag and a size field as generic header:

struct __packed lb_cfr_header {
  uint32_t tag;
  uint32_t size;
};

The size of a record includes the size of its own fields plus the size of all child records. A record can have none or multiple child records. The record tag must be known by the parser to parse the record and its sub records. If it is not known to the parser it can simply skip it by jumping size bytes forward.

The coreboot table containing the CFR tree has the tag LB_TAG_CFR.

The public API can be found in src/commonlib/include/commonlib/cfr.h and src/commonlib/include/commonlib/coreboot_tables.h.

Implementation design

Flags

The optional flags describe the visibilty of the option and the effect on the non-volatile variable.

CFR_OPTFLAG_READONLY

Prevents writes to the variable.
CFR_OPTFLAG_INACTIVE

Implies READONLY. The option is visible, but cannot be modified because one of the dependencies are not given. However there's a possibility to enable the option by changing runtime configuration.

For example: Setting SATA mode, but SATA is globally disabled.
CFR_OPTFLAG_SUPPRESS

Runtime code sets this flag to indicate that the option has no effect and is never reachable, not even by changing runtime configuration. This option is never shown in the UI.
CFR_OPTFLAG_VOLATILE

Implies READONLY. The option is not backed by a non-volatile variable. This is useful to display the current state of a specific component, a dependency or a serial number. This information could be passed in a new coreboot table, but it not useful other than to be shown at this spot in the UI.
CFR_OPTFLAG_RUNTIME

The option is allowed to be changed by a post payload entity. On UEFI this sets the EFI_VARIABLE_RUNTIME_ACCESS attribute. It is out of scope of this specification how non runtime variables are protected after the payload has hand over control.

Example

To display a boolean option with the label Boolean, that default value is true, on a form called test, that modifies the variable First the following structure will be generated:

struct lb_cfr_option_form {
  uint32_t tag;                  = CFR_TAG_OPTION_FORM
  uint32_t size;                 = sizeof(struct lb_cfr_option_form) +
                                   sizeof(struct lb_cfr_varbinary) +
                                   strlen(name) + 1 + 3 +
                                   sizeof(struct lb_cfr_numeric_option) +
                                   sizeof(struct lb_cfr_varbinary) +
                                   strlen(optname) + 1 + 2 +
                                   sizeof(struct lb_cfr_varbinary) +
                                   strlen(uiname) + 1 = 120
  uint64_t object_id;            = 1
  uint64_t dependency_id;        = 0
  uint32_t flags;                = 0
}
  struct lb_cfr_varbinary {
    uint32_t tag;                = CFR_TAG_VARCHAR_UI_NAME
    uint32_t size;               = sizeof(struct lb_cfr_varbinary) +
                                   strlen(name) + 1 + 3 = 20
    uint32_t data_length;        = strlen(name) + 1
  };
    char name[5];                = "test"
    char padding[3];
  struct lb_cfr_numeric_option {
    uint32_t tag;                = CFR_TAG_OPTION_BOOL
    uint32_t size;               = sizeof(struct lb_cfr_numeric_option) +
                                   sizeof(struct lb_cfr_varbinary) +
                                   strlen(optname) + 1 + 2 +
                                   sizeof(struct lb_cfr_varbinary) +
                                   strlen(uiname) + 1 = 72
    uint64_t object_id;          = 2
    uint64_t dependency_id;      = 0
    uint32_t flags;              = 0
    uint32_t default_value;      = true
  };
    struct lb_cfr_varbinary {
      uint32_t tag;              = CFR_TAG_VARCHAR_OPT_NAME
      uint32_t size;             = sizeof(struct lb_cfr_varbinary) +
                                   strlen(optname) + 1 + 2 = 20
      uint32_t data_length;      = strlen(optname) + 1 = 6
    };
      char optname[6];           = "First"
      char padding[2];
    struct lb_cfr_varbinary {
      uint32_t tag;              = CFR_TAG_VARCHAR_UI_NAME
      uint32_t size;             = sizeof(struct lb_cfr_varbinary) +
                                   strlen(uiname) + 1 = 20
      uint32_t data_length;      = strlen(uiname) + 1 = 8
    };
      char uiname[8];            = "Boolean"

9.4 KiB Raw Blame History