From: Andreas Reichel <[email protected]> Update for user variables and remove relict from swupdate-adapter.
Signed-off-by: Andreas Reichel <[email protected]> --- docs/API.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- docs/UPDATE.md | 16 +++++++++------- 2 files changed, 61 insertions(+), 10 deletions(-) diff --git a/docs/API.md b/docs/API.md index 1793581..e198b21 100644 --- a/docs/API.md +++ b/docs/API.md @@ -14,9 +14,7 @@ The interface provides functions to: * edit the latest environment * reset the error state * check the last update state - -An example and detailed information on how to interpret the returned state values -is given in the [swupdate-adapter documentation](../swupdate-adapter/swupdate.md). +* manage user variables To link a program to the library, you can install `efibootguard` with @@ -31,6 +29,22 @@ If you want to cross-compile this library, you have to cross-compile the `efibootguard tools` since both tools and this API library both depend on a common static library. Refer to [compilation instructions](COMPILE.md). +## User variables ## + +User variables are automatically set if the given variable key is not part of +the internally pre-defined variable set. They reside in a special memory area +of the environment managed by the API. + +The structure of an entry is explained in the [source code](../env/uservars.c). +Also see the example program below. + +There are currently two types of user variables: Those with the flag +USERVAR_TYPE_GLOBAL set in their data field and those without. + +Global variables are immune to the update process, i.e. they are stored into all +environments. If not specifying flags manually with ebg_env_set_ex, the global +flag is set per default. + ## Example programs ## The following example program creates a new environment with the latest revision @@ -76,3 +90,38 @@ int main(void) return 0; } ``` + +### Example on user variable usage ### + +```c +#include <stdbool.h> +#include "ebgenv.h" + +int main(void) +{ + ebgenv_t e; + + ebg_env_open_current(&e); + + /* This automatically creates a global user variable, stored in all + * environments */ + ebg_env_set(&e, "myvar", "myvalue"); + + /* This sets the global variable to an empty string */ + ebg_env_set(&e, "myvar", ""); + + /* This creates a user variable in the current environment only */ + ebg_env_set_ex(&e, "currentvar", USERVAR_TYPE_STRING_ASCII, "abc", + strlen("abc") + 1); + + /* This deletes the global myvar key from all environments. + * Note: value must not be NULL and datalen must be greater than 0 */ + ebg_env_set_ex(&e, "myvar", USERVAR_TYPE_DELETED | USERVAR_TYPE_GLOBAL, "", 1); + + /* This deletes the variable from the current environment */ + ebg_env_set_ex(&e, "currentvar", USERVAR_TYPE_DELETED, "", 1); + + ebg_env_close(&e); +} + +``` diff --git a/docs/UPDATE.md b/docs/UPDATE.md index bee5fd9..1cfeb71 100644 --- a/docs/UPDATE.md +++ b/docs/UPDATE.md @@ -9,13 +9,14 @@ The structure of the environment data is as follows: ```c struct _BG_ENVDATA { - uint16_t kernelfile[ENV_STRING_LENGTH]; - uint16_t kernelparams[ENV_STRING_LENGTH]; - uint8_t padding; - uint8_t ustate; - uint16_t watchdog_timeout_sec; - uint32_t revision; - uint32_t crc32; + uint16_t kernelfile[ENV_STRING_LENGTH]; + uint16_t kernelparams[ENV_STRING_LENGTH]; + uint8_t padding; + uint8_t ustate; + uint16_t watchdog_timeout_sec; + uint32_t revision; + uint8_t userdata[ENV_MEM_USERVARS]; + uint32_t crc32; }; ``` @@ -27,6 +28,7 @@ The fields have the following meaning: * `ustate`: Update status (`0` OK, `1` INSTALLED, `2` TESTING, `3`: FAILED) * `watchdog_timeout_sec`: Number of seconds, the watchdog times out after * `revision`: The revision number explained above +* `userdata`: Stores user variables. See [API.md](API.md) for explanation. * `crc32`: A crc32 checksum The following example cases demonstrate the meaning of the update-specific -- 2.14.2 -- You received this message because you are subscribed to the Google Groups "EFI Boot Guard" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/efibootguard-dev/20171103155556.32160-6-andreas.reichel.ext%40siemens.com. For more options, visit https://groups.google.com/d/optout.
