Documentation/drivers/cfr_internal.md

   1 # CFR - coreboot form representation - Internals
   2
   3 This documents the API internally used by coreboot to be used
   4 by ramstage code.
   5
   6 Please read [CFR](cfr.md) first.
   7
   8 ## Enabling CFR support
   9
  10 Users should select `DRIVERS_OPTION_CFR` in Kconfig to enable CFR
  11 support. Mainboards should select `DRIVERS_OPTION_CFR_ENABLED` to
  12 enable `DRIVERS_OPTION_CFR` by default.
  13
  14 ## Using CFR
  15
  16 When CFR support is enabled there are two possibilites to generate
  17 the records:
  18
  19 - mainboard specific code
  20 - automatic collection
  21
  22 In both cases you have to add `C` structs in ramstage to describe the
  23 option and group them together into a form. CFR objects should reside
  24 on the heap as they can be modified to match the current boot flow.
  25
  26 ### Updating CFR options
  27
  28 The CFR options should be updated before tables are written.
  29 You can use a callback, using the `WITH_CALLBACK()` macro, to update
  30 single or multiple options when the CFR table is written into the
  31 coreboot table.
  32
  33 **Example:** Updates the option serial_number with the contents from the
  34 EMI eeprom.
  35
  36 ```
  37 static void update_serial(const struct sm_object *obj, struct sm_object *new)
  38 {
  39         new->sm_varchar.default_value = get_emi_eeprom_vpd()->serial_number;
  40 }
  41
  42 static const struct sm_object serial_number = SM_DECLARE_VARCHAR({
  43         .flags          = CFR_OPTFLAG_READONLY | CFR_OPTFLAG_VOLATILE,
  44         .opt_name       = "serial_number",
  45         .ui_name        = "Serial Number",
  46 }, WITH_CALLBACK(update_serial));
  47 ```
  48
  49 ### Dependencies in CFR options
  50
  51 The CFR options can have a dependency that must be evaluated at runtime by
  52 the OS/payload that parses the CFR record and displays the UI.
  53 By using the `WITH_DEP()` macro you can specify another numberic option that
  54 is checked to hide the current option.
  55
  56 **Example:** Declares a dependency from `sata_disable_port0` to `sata_enable`.
  57 The option `sata_disable_port0` will be hidden as long as "sata_enable" is 0.
  58 When the user changes "sata_enable" to 1 or it was 1 then the option
  59 `sata_disable_port0` should be visible.
  60
  61 ```
  62 static struct sm_object sata_enable = SM_DECLARE_BOOL({
  63         .flags          = CFR_OPTFLAG_RUNTIME,
  64         .opt_name       = "sata_enable",
  65         .ui_name        = "Enable SATA controller",
  66         .ui_helptext    = NULL,
  67         .default_value  = true,
  68 });
  69
  70 static struct sm_object sata_disable_port0 = SM_DECLARE_BOOL({
  71         .flags          = CFR_OPTFLAG_RUNTIME,
  72         .opt_name       = "sata_disable_port0",
  73         .ui_name        = "Disable SATA port #0",
  74         .ui_helptext    = NULL,
  75         .default_value  = false,
  76 }, WITH_DEP(&sata_enable));
  77 ```
  78
  79 ### Providing mainboard custom options
  80
  81 A mainboard that uses CFR can provide a list of custom options
  82 be overwriting the weak `void mb_cfr_setup_menu(struct lb_cfr *cfr_root);`
  83 function in ramstage.
  84
  85 ### Automatic CFR collection
  86
  87 CFR forms that have the `__cfr_form` attribute are automatically collected
  88 and inserted into the coreboot table.
  89
  90 ## Example
  91
  92 The following CFR form `southbridge` will be automatically added to the
  93 coreboot table and it will have a single option called `Enable NMI` that
  94 allows the variable `nmi` to be changed to *0* or *1*.
  95
  96 **Example:**
  97 ```C
  98 static struct sm_object nmi = SM_DECLARE_BOOL({
  99         .flags          = CFR_OPTFLAG_RUNTIME,
 100         .opt_name       = "nmi",
 101         .ui_name        = "Enable NMI",
 102         .ui_helptext    = NULL,
 103         .default_value  = false,
 104 });
 105
 106 static const  __cfr_form struct sm_obj_form southbridge = {
 107         .flags          = 0,
 108         .ui_name        = "Southbridge",
 109         .obj_list       = (const struct sm_object *[]) {
 110                 &nmi,
 111                 NULL
 112         },
 113 };
 114 ```