Documentation/lib/option.md

   1 # Option API
   2
   3 The option API around the `set_option(const char *name, void *val)` and
   4 `get_option(void *dest, const char *name)` functions deprecated in favor
   5 of a type-safe API.
   6
   7 Historically, options were stored in RTC battery-backed CMOS RAM inside
   8 the chipset on PC platforms. Nowadays, options can also be stored in the
   9 same flash chip as the boot firmware or through some BMC interface.
  10
  11 The new type-safe option framework can be used by calling
  12 `enum cb_err set_uint_option(const char *name, unsigned int value)` and
  13 `unsigned int get_uint_option(const char *name, const unsigned int fallback)`.
  14
  15 The default setting is `OPTION_BACKEND_NONE`, which disables any runtime
  16 configurable options. If supported by a mainboard, the `USE_OPTION_TABLE`
  17 and `USE_MAINBOARD_SPECIFIC_OPTION_BACKEND` choices are visible, and can
  18 be selected to enable runtime configurability.
  19
  20 # Mainboard-specific option backend
  21
  22 Mainboards with a mainboard-specific (vendor-defined) method to access
  23 options can select `HAVE_MAINBOARD_SPECIFIC_OPTION_BACKEND` to provide
  24 implementations of the option API accessors. To allow choosing between
  25 multiple option backends, the mainboard-specific implementation should
  26 only be built when `USE_MAINBOARD_SPECIFIC_OPTION_BACKEND` is selected.
  27
  28 Where possible, using a generic, mainboard-independent mechanism should
  29 be preferred over reinventing the wheel in mainboard-specific code. The
  30 mainboard-specific approach should only be used when the option storage
  31 mechanism has to satisfy externally-imposed, vendor-defined constraints.