option: Allow mainboards to implement the API

Some mainboards need a mainboard-specific mechanism to access option
values. Allow mainboards to implement the option API. Also, add some
documentation about the current option API, and describe when should
one reimplement the option API in mainboard code: only when the code
is mainboard-specific to comply with externally-imposed constraints.

Change-Id: Idccdb9a008b1ebb89821961659f27b1c0b17d29c
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Signed-off-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/54729
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
This commit is contained in:
Angel Pons 2021-05-20 16:43:08 +02:00
parent 17852e61df
commit 9bc780fc9f
3 changed files with 47 additions and 0 deletions

View File

@ -183,6 +183,7 @@ Contents:
* [Mainboard](mainboard/index.md)
* [Payloads](lib/payloads/index.md)
* [Libraries](lib/index.md)
* [Options](lib/option.md)
* [Security](security/index.md)
* [SuperIO](superio/index.md)
* [Vendorcode](vendorcode/index.md)

View File

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

View File

@ -122,6 +122,7 @@ config UTIL_GENPARSER
choice
prompt "Option backend to use"
default USE_MAINBOARD_SPECIFIC_OPTION_BACKEND if HAVE_MAINBOARD_SPECIFIC_OPTION_BACKEND
default USE_OPTION_TABLE if NVRAMCUI_SECONDARY_PAYLOAD
config OPTION_BACKEND_NONE
@ -134,6 +135,13 @@ config USE_OPTION_TABLE
Enable this option if coreboot shall read options from the "CMOS"
NVRAM instead of using hard-coded values.
config USE_MAINBOARD_SPECIFIC_OPTION_BACKEND
bool "Use mainboard-specific option backend"
depends on HAVE_MAINBOARD_SPECIFIC_OPTION_BACKEND
help
Use a mainboard-specific mechanism to access runtime-configurable
options.
endchoice
config STATIC_OPTION_TABLE
@ -683,6 +691,13 @@ config NUM_THREADS
help
How many execution threads to cooperatively multitask with.
config HAVE_MAINBOARD_SPECIFIC_OPTION_BACKEND
bool
help
Selected by mainboards which implement a mainboard-specific mechanism
to access the values for runtime-configurable options. For example, a
custom BMC interface or an EEPROM with an externally-imposed layout.
config HAVE_OPTION_TABLE
bool
default n