From 9bc780fc9fef78f5af8f2d93190ab4c5876cca60 Mon Sep 17 00:00:00 2001 From: Angel Pons Date: Thu, 20 May 2021 16:43:08 +0200 Subject: [PATCH] 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 Signed-off-by: Angel Pons Reviewed-on: https://review.coreboot.org/c/coreboot/+/54729 Tested-by: build bot (Jenkins) Reviewed-by: Arthur Heymans --- Documentation/index.md | 1 + Documentation/lib/option.md | 31 +++++++++++++++++++++++++++++++ src/Kconfig | 15 +++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 Documentation/lib/option.md diff --git a/Documentation/index.md b/Documentation/index.md index 9870cf3108..c518c5085b 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -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) diff --git a/Documentation/lib/option.md b/Documentation/lib/option.md new file mode 100644 index 0000000000..eb63390ec7 --- /dev/null +++ b/Documentation/lib/option.md @@ -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. diff --git a/src/Kconfig b/src/Kconfig index b019e9d8b2..6b6076741f 100644 --- a/src/Kconfig +++ b/src/Kconfig @@ -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