From d5737b3f6a0239caf2dd5578a4bc8ebfccfdee3b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:28 -0600 Subject: expo: Tidy up the expo.py tool and usage Tidy up this tool a little: - define which arguments are needed - split the enum values out into a header file - warn if no enum values are found - display the dtc error if something goes wrong - avoid a Python traceback on error Signed-off-by: Simon Glass --- doc/develop/expo.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 2ac4af232da..0643283ae48 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -367,22 +367,27 @@ strings are provided inline in the nodes where they are used. :: - #define ID_PROMPT 1 - #define ID_SCENE1 2 - #define ID_SCENE1_TITLE 3 - - #define ID_CPU_SPEED 4 - #define ID_CPU_SPEED_TITLE 5 - #define ID_CPU_SPEED_1 6 - #define ID_CPU_SPEED_2 7 - #define ID_CPU_SPEED_3 8 - - #define ID_POWER_LOSS 9 - #define ID_AC_OFF 10 - #define ID_AC_ON 11 - #define ID_AC_MEMORY 12 - - #define ID_DYNAMIC_START 13 + /* this comment is parsed by the expo.py tool to insert the values below + + enum { + ZERO, + ID_PROMPT, + ID_SCENE1, + ID_SCENE1_TITLE, + + ID_CPU_SPEED, + ID_CPU_SPEED_TITLE, + ID_CPU_SPEED_1, + ID_CPU_SPEED_2, + ID_CPU_SPEED_3, + + ID_POWER_LOSS, + ID_AC_OFF, + ID_AC_ON, + ID_AC_MEMORY, + + ID_DYNAMIC_START, + */ &cedit { dynamic-start = ; -- cgit v1.3.1 From c5aacf5ef87610d92bf0651b2a935c37778768d2 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:29 -0600 Subject: expo: Add documentation for the configuration editor This is mentioned in passing in the 'cedit' command. Its file format is described under `expo`. But it would be better if it had its own entry in the documentation. Add a new 'cedit' entry with a few details about this feature. Signed-off-by: Simon Glass --- doc/develop/cedit.rst | 147 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/develop/expo.rst | 3 + doc/develop/index.rst | 1 + doc/usage/cmd/cedit.rst | 2 + 4 files changed, 153 insertions(+) create mode 100644 doc/develop/cedit.rst (limited to 'doc/develop') diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst new file mode 100644 index 00000000000..48262ee535e --- /dev/null +++ b/doc/develop/cedit.rst @@ -0,0 +1,147 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Configuration Editor +==================== + +Introduction +------------ + +U-Boot provides a configuration editor which allows settings to be changed in +a GUI or text environment. + + +This feature is still in development and has a number of limitations. For +example, cedit only supports menu items (there is no numeric or text entry), +provides no support for colour text and does not support scrolling. Still it is +possible to use it for simple applications. + + +Overview +-------- + +The configuration editor makes use of :doc:`expo` to build a description of the +configuration screens and allow user to interact with it. + +To create a single-scene cedit for your application: + +#. Design the scene, i.e. the objects that need to be present and what their + possible values are + +#. Enter this in .dts format + +#. Create a header file containing the IDs + +#. Run the 'expo.py' tool to generate a .dtb file containing the layout, which + can be used by U-Boot + +#. Use the :doc:`../usage/cmd/cedit` to create the cedit, read the settings, + present the cedit to the user and save the settings afterwards. + +Each of these is described in a separate section. See :ref:`expo_example` for +an example file. + + +Design a scene +-------------- + +Using a piece of paper or a drawing tool, lay out the objects you want in your +scene. Typically you will use the default layout engine, which simply puts items +one after the other from top to bottom. So use a single column and show the +prompt and value for each object. + +For menu items, show one of the values, but keep in mind what else you need. + + +Create an expo-format file +-------------------------- + +The description is in the form of a devicetree file, as documented at +:ref:`expo_format`. Since everything in an expo has an ID number (an integer +greater than 1) the description is written terms of these IDs. They each have +an enum value. which is typically taken care of by the `expo.py` tool. + +The expo should have a `scenes` node with a named scene as a subnode. Within the +scene, add properties for the scene, then a subnode for each object in the +scene. + +All object nodes require an `id` value and a `type` property. Other properties +depend on the type. For example, a menu has a `title` and an `item-label` list +proving the text for the menu items, as well as an `item-id` list providing the +ID of each menu item, so it can be selected. + +Text properties may have two variants. For example `title` specifies the title +of a menu, but you can instead use `title-id` to specify the string ID to use as +the title. String are defined in a separate area, common to the whole expo, +which contains a subnode for each string. Within that subnode are the ID and the +`value` (i.e. the text). For now only English is supported, but in future it may +be possible to append a language identifier to provide other values (e.g. +'value-es' for Spanish). + + +Create an ID header-file +------------------------ + +Expo needs to know the integer value to use for every ID referenced in your +expo-format file. For example, if you have defined a `cpu-speed` node with an +id of `ID_CPU_SPEED`, then Expo needs to know the value of `ID_CPU_SPEED`. + +When you write C code to use the expo, you may need to know the IDs. For +example, to find which value the user selected in `cpu-speed` menu, you must +use the `ID_CPU_SPEED` ID. The ID is the only way to refer to anything in Expo. + +Since we need a shared set of IDs, it is best to have a header file containing +them. Expo supports doing this with an enum, where every ID is listed in the +enum:: + + enum { + ZERO, + + ID_PROMPT, + + ID_SCENE1, + ID_SCENE1_TITLE, + ... + }; + +The C compiler can parse this directly. The `expo.py` tool parses it for expo. + +Create a header file containing every ID mentioned in your expo. Try to group +related things together. + + +Build the expo layout +--------------------- + +Use the `expo.py` tool to build a .dtb for your expo:: + + ./tools/expo.py -e expo_ids.h -l expo_layout.dts -o expo.dtb + +This uses the enum in the provided header file to get the ID numbers, grabs +the `.dts` file, inserts the ID numbers and then uses the devicetree compiler to +build a `.dtb` file. + +If you get an error:: + + Devicetree compiler error: + Error: :9.19-20 syntax error + FATAL ERROR: Unable to parse input tree + +that means that something is wrong with your syntax, or perhaps you have an ID +in the `.dts` file that is not mentioned in your enum. Check both files and try +again. + + +Use the command interface +------------------------- + +See the :doc:`../usage/cmd/cedit` command for information on available commands. +Typically you will use `cedit load` to load the `.dtb` file and `cedit run` to +let the user interact with it. + + +Multiple scenes +--------------- + +Expo supports multiple scenes but has no pre-determined way of moving between +them. You could use selection of a menu item as a signal to change the scene, +but this is not currently implemented in the cedit code (see `cedit_run()`). diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 0643283ae48..fde91494799 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -358,6 +358,9 @@ The `expo_arrange()` function can be called to arrange the expo objects in a suitable manner. For each scene it puts the title at the top, the prompt at the bottom and the objects in order from top to bottom. + +.. _expo_example: + Expo format example ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 5b230d0321f..0d12484ace8 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -38,6 +38,7 @@ Implementation driver-model/index environment expo + cedit event global_data logging diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 8e1110c7c77..3d815bd27af 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -22,6 +22,8 @@ It makes use of the expo subsystem. The description is in the form of a devicetree file, as documented at :ref:`expo_format`. +See :doc:`../../develop/cedit` for information about the configuration editor. + Example ------- -- cgit v1.3.1 From 2045ca5c1f51d054579d0886184b6f245b8a134e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:30 -0600 Subject: expo: Move cedit theme under bootstd This is related to standard boot, so put it under the same node. This may simplify schema upstreaming later. Mention themes in the documentation while we are here. Signed-off-by: Simon Glass --- arch/sandbox/dts/sandbox.dtsi | 12 ++++++------ arch/sandbox/dts/test.dts | 12 ++++++------ cmd/cedit.c | 2 +- doc/develop/cedit.rst | 7 +++++++ 4 files changed, 20 insertions(+), 13 deletions(-) (limited to 'doc/develop') diff --git a/arch/sandbox/dts/sandbox.dtsi b/arch/sandbox/dts/sandbox.dtsi index 8aaf911a41a..ff7e5584c55 100644 --- a/arch/sandbox/dts/sandbox.dtsi +++ b/arch/sandbox/dts/sandbox.dtsi @@ -16,12 +16,6 @@ stdout-path = "/serial"; }; - cedit-theme { - font-size = <30>; - menu-inset = <3>; - menuitem-gap-y = <1>; - }; - alarm_wdt: alarm-wdt { compatible = "sandbox,alarm-wdt"; timeout-sec = <5>; @@ -36,6 +30,12 @@ bootstd { compatible = "u-boot,boot-std"; filename-prefixes = "./"; + + cedit-theme { + font-size = <30>; + menu-inset = <3>; + menuitem-gap-y = <1>; + }; }; buttons { diff --git a/arch/sandbox/dts/test.dts b/arch/sandbox/dts/test.dts index f351d5cb84b..084cb88a232 100644 --- a/arch/sandbox/dts/test.dts +++ b/arch/sandbox/dts/test.dts @@ -100,6 +100,12 @@ menuitem-gap-y = <1>; }; + cedit-theme { + font-size = <30>; + menu-inset = <3>; + menuitem-gap-y = <1>; + }; + /* * This is used for the VBE OS-request tests. A FAT filesystem * created in a partition with the VBE information appearing @@ -144,12 +150,6 @@ cedit: cedit { }; - cedit-theme { - font-size = <30>; - menu-inset = <3>; - menuitem-gap-y = <1>; - }; - fuzzing-engine { compatible = "sandbox,fuzzing-engine"; }; diff --git a/cmd/cedit.c b/cmd/cedit.c index 5f0e84403f5..e98121b067b 100644 --- a/cmd/cedit.c +++ b/cmd/cedit.c @@ -65,7 +65,7 @@ static int do_cedit_run(struct cmd_tbl *cmdtp, int flag, int argc, return CMD_RET_FAILURE; } - node = ofnode_path("/cedit-theme"); + node = ofnode_path("/bootstd/cedit-theme"); if (ofnode_valid(node)) { ret = expo_apply_theme(cur_exp, node); if (ret) diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst index 48262ee535e..8f0a554ae91 100644 --- a/doc/develop/cedit.rst +++ b/doc/develop/cedit.rst @@ -145,3 +145,10 @@ Multiple scenes Expo supports multiple scenes but has no pre-determined way of moving between them. You could use selection of a menu item as a signal to change the scene, but this is not currently implemented in the cedit code (see `cedit_run()`). + + +Themes +------ + +The configuration editor uses simple expo themes. The theme is read from +`/bootstd/cedit-theme` in the devicetree. -- cgit v1.3.1 From eb6c71b56282d3054dbffb83793e7d2c6745578e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:37 -0600 Subject: expo: cedit: Support writing settings to CMOS RAM Add a command to write cedit settings to CMOS RAM so that it can be preserved across a reboot. This uses a simple bit-encoding, where each field has a 'bit position' and a 'bit length' in the schema. Signed-off-by: Simon Glass --- boot/cedit.c | 137 +++++++++++++++++++++++++++++++++++++++- boot/expo_build.c | 7 +- cmd/cedit.c | 36 +++++++++++ doc/develop/expo.rst | 13 ++++ doc/usage/cmd/cedit.rst | 22 +++++++ include/cedit.h | 13 ++++ include/expo.h | 6 +- test/boot/cedit.c | 30 +++++++++ test/boot/files/expo_layout.dts | 5 ++ 9 files changed, 266 insertions(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/boot/cedit.c b/boot/cedit.c index e3f6dc00399..725745aba55 100644 --- a/boot/cedit.c +++ b/boot/cedit.c @@ -15,22 +15,37 @@ #include #include #include +#include #include +#include #include #include #include "scene_internal.h" +enum { + CMOS_MAX_BITS = 2048, + CMOS_MAX_BYTES = CMOS_MAX_BITS / 8, +}; + +#define CMOS_BYTE(bit) ((bit) / 8) +#define CMOS_BIT(bit) ((bit) % 8) + /** * struct cedit_iter_priv - private data for cedit operations * * @buf: Buffer to use when writing settings to the devicetree * @node: Node to read from when reading settings from devicetree * @verbose: true to show writing to environment variables + * @mask: Mask bits for the CMOS RAM. If a bit is set the byte containing it + * will be written + * @value: Value bits for CMOS RAM. This is the actual value written */ struct cedit_iter_priv { struct abuf *buf; ofnode node; bool verbose; + u8 *mask; + u8 *value; }; int cedit_arange(struct expo *exp, struct video_priv *vpriv, uint scene_id) @@ -445,7 +460,7 @@ static int h_read_settings_env(struct scene_obj *obj, void *vpriv) struct cedit_iter_priv *priv = vpriv; struct scene_obj_menu *menu; char var[60]; - int val, ret; + int val; if (obj->type != SCENEOBJT_MENU) return 0; @@ -484,3 +499,123 @@ int cedit_read_settings_env(struct expo *exp, bool verbose) return 0; } + +/** + * get_cur_menuitem_seq() - Get the sequence number of a menu's current item + * + * Enumerates the items of a menu (0, 1, 2) and returns the sequence number of + * the currently selected item. If the first item is selected, this returns 0; + * if the second, 1; etc. + * + * @menu: Menu to check + * Return: Sequence number on success, else -ve error value + */ +static int get_cur_menuitem_seq(const struct scene_obj_menu *menu) +{ + const struct scene_menitem *mi; + int seq, found; + + seq = 0; + found = -1; + list_for_each_entry(mi, &menu->item_head, sibling) { + if (mi->id == menu->cur_item_id) { + found = seq; + break; + } + seq++; + } + + if (found == -1) + return log_msg_ret("nf", -ENOENT); + + return found; +} + +static int h_write_settings_cmos(struct scene_obj *obj, void *vpriv) +{ + const struct scene_obj_menu *menu; + struct cedit_iter_priv *priv = vpriv; + int val, ret; + uint i, seq; + + if (obj->type != SCENEOBJT_MENU) + return 0; + + menu = (struct scene_obj_menu *)obj; + val = menu->cur_item_id; + + ret = get_cur_menuitem_seq(menu); + if (ret < 0) + return log_msg_ret("cur", ret); + seq = ret; + log_debug("%s: seq=%d\n", menu->obj.name, seq); + + /* figure out where to place this item */ + if (!obj->bit_length) + return log_msg_ret("len", -EINVAL); + if (obj->start_bit + obj->bit_length > CMOS_MAX_BITS) + return log_msg_ret("bit", -E2BIG); + + for (i = 0; i < obj->bit_length; i++, seq >>= 1) { + uint bitnum = obj->start_bit + i; + + priv->mask[CMOS_BYTE(bitnum)] |= 1 << CMOS_BIT(bitnum); + if (seq & 1) + priv->value[CMOS_BYTE(bitnum)] |= BIT(CMOS_BIT(bitnum)); + log_debug("bit %x %x %x\n", bitnum, + priv->mask[CMOS_BYTE(bitnum)], + priv->value[CMOS_BYTE(bitnum)]); + } + + return 0; +} + +int cedit_write_settings_cmos(struct expo *exp, struct udevice *dev, + bool verbose) +{ + struct cedit_iter_priv priv; + int ret, i, count, first, last; + + /* write out the items */ + priv.mask = calloc(1, CMOS_MAX_BYTES); + if (!priv.mask) + return log_msg_ret("mas", -ENOMEM); + priv.value = calloc(1, CMOS_MAX_BYTES); + if (!priv.value) { + free(priv.mask); + return log_msg_ret("val", -ENOMEM); + } + + ret = expo_iter_scene_objs(exp, h_write_settings_cmos, &priv); + if (ret) { + log_debug("Failed to write CMOS (err=%d)\n", ret); + ret = log_msg_ret("set", ret); + goto done; + } + + /* write the data to the RTC */ + first = CMOS_MAX_BYTES; + last = -1; + for (i = 0, count = 0; i < CMOS_MAX_BYTES; i++) { + if (priv.mask[i]) { + log_debug("Write byte %x: %x\n", i, priv.value[i]); + ret = rtc_write8(dev, i, priv.value[i]); + if (ret) { + ret = log_msg_ret("wri", ret); + goto done; + } + count++; + first = min(first, i); + last = max(last, i); + } + } + if (verbose) { + printf("Write %d bytes from offset %x to %x\n", count, first, + last); + } + +done: + free(priv.mask); + free(priv.value); + return ret; +} diff --git a/boot/expo_build.c b/boot/expo_build.c index e8c4a40d3f0..bb33cc2a33f 100644 --- a/boot/expo_build.c +++ b/boot/expo_build.c @@ -294,7 +294,7 @@ static int obj_build(struct build_info *info, ofnode node, struct scene *scn) { struct scene_obj *obj; const char *type; - u32 id; + u32 id, val; int ret; log_debug("- object %s\n", ofnode_get_name(node)); @@ -313,6 +313,11 @@ static int obj_build(struct build_info *info, ofnode node, struct scene *scn) if (ret) return log_msg_ret("bld", ret); + if (!ofnode_read_u32(node, "start-bit", &val)) + obj->start_bit = val; + if (!ofnode_read_u32(node, "bit-length", &val)) + obj->bit_length = val; + return 0; } diff --git a/cmd/cedit.c b/cmd/cedit.c index b2548f44b57..95d5c22c2f7 100644 --- a/cmd/cedit.c +++ b/cmd/cedit.c @@ -10,6 +10,7 @@ #include #include #include +#include #include #include #include @@ -176,6 +177,39 @@ static int do_cedit_read_env(struct cmd_tbl *cmdtp, int flag, int argc, return 0; } +static int do_cedit_write_cmos(struct cmd_tbl *cmdtp, int flag, int argc, + char *const argv[]) +{ + struct udevice *dev; + bool verbose = false; + int ret; + + if (check_cur_expo()) + return CMD_RET_FAILURE; + + if (argc > 1 && !strcmp(argv[1], "-v")) { + verbose = true; + argc--; + argv++; + } + + if (argc > 1) + ret = uclass_get_device_by_name(UCLASS_RTC, argv[1], &dev); + else + ret = uclass_first_device_err(UCLASS_RTC, &dev); + if (ret) { + printf("Failed to get RTC device: %dE\n", ret); + return CMD_RET_FAILURE; + } + + if (cedit_write_settings_cmos(cur_exp, dev, verbose)) { + printf("Failed to write settings to CMOS\n"); + return CMD_RET_FAILURE; + } + + return 0; +} + static int do_cedit_run(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) { @@ -209,6 +243,7 @@ static char cedit_help_text[] = "cedit write_fdt - write settings\n" "cedit read_env [-v] - read settings from env vars\n" "cedit write_env [-v] - write settings to env vars\n" + "cedit write_cmos [-v] [dev] - write settings to CMOS RAM\n" "cedit run - run config editor"; #endif /* CONFIG_SYS_LONGHELP */ @@ -218,5 +253,6 @@ U_BOOT_CMD_WITH_SUBCMDS(cedit, "Configuration editor", cedit_help_text, U_BOOT_SUBCMD_MKENT(write_fdt, 5, 1, do_cedit_write_fdt), U_BOOT_SUBCMD_MKENT(read_env, 2, 1, do_cedit_read_env), U_BOOT_SUBCMD_MKENT(write_env, 2, 1, do_cedit_write_env), + U_BOOT_SUBCMD_MKENT(write_cmos, 2, 1, do_cedit_write_cmos), U_BOOT_SUBCMD_MKENT(run, 1, 1, do_cedit_run), ); diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index fde91494799..61b6855c72f 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -317,6 +317,18 @@ id Specifies the ID of the object. This is used when referring to the object. +Where CMOS RAM is used for reading and writing settings, the following +additional properties are required: + +start-bit + Specifies the first bit in the CMOS RAM to use for this setting. For a RAM + with 0x100 bytes, there are 0x800 bit locations. For example, register 0x80 + holds bits 0x400 to 0x407. + +bit-length + Specifies the number of CMOS RAM bits to use for this setting. The bits + extend from `start-bit` to `start-bit + bit-length - 1`. Note that the bits + must be contiguous. Menu nodes have the following additional properties: @@ -474,6 +486,7 @@ Some ideas for future work: - Support curses for proper serial-terminal menus - Add support for large menus which need to scroll - Add support for reading and writing configuration settings with cedit +- Update expo.py tool to check for overlapping names and CMOS locations .. Simon Glass .. 7-Oct-22 diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 1f92b7306a7..3d6f26e631d 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -14,6 +14,7 @@ Synopis cedit read_fdt cedit write_env [-v] cedit read_env [-v] + cedit write_cmos [-v] [dev] Description ----------- @@ -76,6 +77,18 @@ ID and its text string are written, similar to: The `-v` flag enables verbose mode, where each variable is printed before it is set. +cedit write_cmos +~~~~~~~~~~~~~~~~ + +Writes the settings to locations in the CMOS RAM. The locations used are +specified by the schema. See `expo_format_`. + +The `-v` flag enables verbose mode, which shows which CMOS locations were +updated. + +Normally the first RTC device is used to hold the data. You can specify a +different device by name using the `dev` parameter. + Example ------- @@ -117,3 +130,12 @@ This shows settings being stored in the environment:: => cedit read_env -v c.cpu-speed=7 c.power-loss=12 + +This shows writing to CMOS RAM. Notice that the bytes at 80 and 84 change:: + + => rtc read 80 8 + 00000080: 00 00 00 00 00 2f 2a 08 ...../*. + => cedit write_cmos + Write 2 bytes from offset 80 to 84 + => rtc read 80 8 + 00000080: 01 00 00 00 08 2f 2a 08 ...../*. diff --git a/include/cedit.h b/include/cedit.h index fe10e6c829c..2970965b5f6 100644 --- a/include/cedit.h +++ b/include/cedit.h @@ -97,4 +97,17 @@ int cedit_write_settings_env(struct expo *exp, bool verbose); */ int cedit_read_settings_env(struct expo *exp, bool verbose); +/** + * cedit_write_settings_cmos() - Write settings to CMOS RAM + * + * Write settings to the defined places in CMOS RAM + * + * @exp: Expo to write settings from + * @dev: UCLASS_RTC device containing space for this information + * Returns 0 if OK, -ve on error + * @verbose: true to print a summary at the end + */ +int cedit_write_settings_cmos(struct expo *exp, struct udevice *dev, + bool verbose); + #endif /* __CEDIT_H */ diff --git a/include/expo.h b/include/expo.h index da151074d20..a2b3a71c159 100644 --- a/include/expo.h +++ b/include/expo.h @@ -187,6 +187,8 @@ enum scene_obj_flags_t { * @type: Type of this object * @dim: Dimensions for this object * @flags: Flags for this object + * @bit_length: Number of bits used for this object in CMOS RAM + * @start_bit: Start bit to use for this object in CMOS RAM * @sibling: Node to link this object to its siblings */ struct scene_obj { @@ -195,7 +197,9 @@ struct scene_obj { uint id; enum scene_obj_t type; struct scene_dim dim; - int flags; + u8 flags; + u8 bit_length; + u16 start_bit; struct list_head sibling; }; diff --git a/test/boot/cedit.c b/test/boot/cedit.c index 7cf0c3e4e93..010aae615b9 100644 --- a/test/boot/cedit.c +++ b/test/boot/cedit.c @@ -155,3 +155,33 @@ static int cedit_env(struct unit_test_state *uts) return 0; } BOOTSTD_TEST(cedit_env, 0); + +/* Check the cedit write_cmos and read_cmos commands */ +static int cedit_cmos(struct unit_test_state *uts) +{ + struct scene_obj_menu *menu, *menu2; + struct video_priv *vid_priv; + extern struct expo *cur_exp; + struct scene *scn; + + console_record_reset_enable(); + ut_assertok(run_command("cedit load hostfs - cedit.dtb", 0)); + + ut_asserteq(ID_SCENE1, cedit_prepare(cur_exp, &vid_priv, &scn)); + + /* get the menus to fiddle with */ + menu = scene_obj_find(scn, ID_CPU_SPEED, SCENEOBJT_MENU); + ut_assertnonnull(menu); + menu->cur_item_id = ID_CPU_SPEED_2; + + menu2 = scene_obj_find(scn, ID_POWER_LOSS, SCENEOBJT_MENU); + ut_assertnonnull(menu2); + menu2->cur_item_id = ID_AC_MEMORY; + + ut_assertok(run_command("cedit write_cmos -v", 0)); + ut_assert_nextlinen("Write 2 bytes from offset 80 to 84"); + ut_assert_console_end(); + + return 0; +} +BOOTSTD_TEST(cedit_cmos, 0); diff --git a/test/boot/files/expo_layout.dts b/test/boot/files/expo_layout.dts index 913140bace9..cb2a674d9d5 100644 --- a/test/boot/files/expo_layout.dts +++ b/test/boot/files/expo_layout.dts @@ -38,6 +38,9 @@ /* IDs for the menu items */ item-id = ; + + start-bit = <0x400>; + bit-length = <2>; }; power-loss { @@ -49,6 +52,8 @@ "Memory"; item-id = ; + start-bit = <0x422>; + bit-length = <2>; }; }; }; -- cgit v1.3.1 From 84b08afcbb8f8b4402b940d87bf5822984eedb3d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:39 -0600 Subject: expo: doc: Update documentation for persistent settings Add mention of persistent settings in the documentation. Signed-off-by: Simon Glass --- doc/develop/cedit.rst | 15 +++++++++++++++ doc/develop/expo.rst | 1 - 2 files changed, 15 insertions(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst index 8f0a554ae91..63dff9d3f14 100644 --- a/doc/develop/cedit.rst +++ b/doc/develop/cedit.rst @@ -152,3 +152,18 @@ Themes The configuration editor uses simple expo themes. The theme is read from `/bootstd/cedit-theme` in the devicetree. + + +Reading and writing settings +---------------------------- + +Cedit provides several options for persistent settings: + +- Writing an FDT file to a filesystem +- Writing to U-Boot's environment variables, which are then typically stored in + a persistent manner +- Writing to CMOS RAM registers (common on x86 machines) + +For now, reading and writing settings is not automatic. See the +:doc:`../usage/cmd/cedit` for how to do this on the command line or in a +script. diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 61b6855c72f..f13761995d3 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -485,7 +485,6 @@ Some ideas for future work: - Support unicode - Support curses for proper serial-terminal menus - Add support for large menus which need to scroll -- Add support for reading and writing configuration settings with cedit - Update expo.py tool to check for overlapping names and CMOS locations .. Simon Glass -- cgit v1.3.1 From 831405f41de122c2a3a0908f07c632c87266709a Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 24 Aug 2023 13:55:43 -0600 Subject: bootstd: Support bootmeths which can scan any partition Some bootmeths support scanning a partition without a filesystem on it. Add a flag to support this. This will allow the ChromiumOS bootmeth to find kernel partition, which are stored in a special format, without a filesystem. Signed-off-by: Simon Glass --- boot/bootdev-uclass.c | 17 ++++++++++++++--- doc/develop/bootstd.rst | 11 ++++++----- include/bootmeth.h | 3 +++ 3 files changed, 23 insertions(+), 8 deletions(-) (limited to 'doc/develop') diff --git a/boot/bootdev-uclass.c b/boot/bootdev-uclass.c index c4044d87dc3..69506e3865f 100644 --- a/boot/bootdev-uclass.c +++ b/boot/bootdev-uclass.c @@ -111,6 +111,8 @@ int bootdev_bind(struct udevice *parent, const char *drv_name, const char *name, int bootdev_find_in_blk(struct udevice *dev, struct udevice *blk, struct bootflow_iter *iter, struct bootflow *bflow) { + struct bootmeth_uc_plat *plat = dev_get_uclass_plat(bflow->method); + bool allow_any_part = plat->flags & BOOTMETHF_ANY_PART; struct blk_desc *desc = dev_get_uclass_plat(blk); struct disk_partition info; char partstr[20]; @@ -142,6 +144,7 @@ int bootdev_find_in_blk(struct udevice *dev, struct udevice *blk, * us whether there is valid media there */ ret = part_get_info(desc, iter->part, &info); + log_debug("part_get_info() returned %d\n", ret); if (!iter->part && ret == -ENOENT) ret = 0; @@ -154,7 +157,7 @@ int bootdev_find_in_blk(struct udevice *dev, struct udevice *blk, ret = -ESHUTDOWN; else bflow->state = BOOTFLOWST_MEDIA; - if (ret) { + if (ret && !allow_any_part) { /* allow partition 1 to be missing */ if (iter->part == 1) { iter->max_part = 3; @@ -174,9 +177,15 @@ int bootdev_find_in_blk(struct udevice *dev, struct udevice *blk, if (!iter->part) { iter->first_bootable = part_get_bootable(desc); log_debug("checking bootable=%d\n", iter->first_bootable); + } else if (allow_any_part) { + /* + * allow any partition to be scanned, by skipping any checks + * for filesystems or partition contents on this disk + */ /* if there are bootable partitions, scan only those */ - } else if (iter->first_bootable ? !info.bootable : iter->part != 1) { + } else if (iter->first_bootable >= 0 && + (iter->first_bootable ? !info.bootable : iter->part != 1)) { return log_msg_ret("boot", -EINVAL); } else { ret = fs_set_blk_dev_with_part(desc, bflow->part); @@ -193,6 +202,7 @@ int bootdev_find_in_blk(struct udevice *dev, struct udevice *blk, bflow->state = BOOTFLOWST_FS; } + log_debug("method %s\n", bflow->method->name); ret = bootmeth_read_bootflow(bflow->method, bflow); if (ret) return log_msg_ret("method", ret); @@ -559,7 +569,8 @@ int bootdev_get_bootflow(struct udevice *dev, struct bootflow_iter *iter, { const struct bootdev_ops *ops = bootdev_get_ops(dev); - log_debug("->get_bootflow %s=%p\n", dev->name, ops->get_bootflow); + log_debug("->get_bootflow %s,%x=%p\n", dev->name, iter->part, + ops->get_bootflow); bootflow_init(bflow, dev, iter->method); if (!ops->get_bootflow) return default_get_bootflow(dev, iter, bflow); diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index ec313653578..c01e0971dc8 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -677,11 +677,12 @@ Assuming the bootmeth is happy, or at least indicates that it is willing to try partition. If that works it tries to detect a file system. If that works then it calls the bootmeth device once more, this time to read the bootflow. -Note: At present a filesystem is needed for the bootmeth to be called on block -devices, simply because we don't have any examples where this is not the case. -This feature can be added as needed. Note that sandbox is a special case, since -in that case the host filesystem can be accessed even though the block device -is NULL. +Note: Normally a filesystem is needed for the bootmeth to be called on block +devices, but bootmeths which don't need that can set the BOOTMETHF_ANY_PART +flag to indicate that they can scan any partition. An example is the ChromiumOS +bootmeth which can store a kernel in a raw partition. Note also that sandbox is +a special case, since in that case the host filesystem can be accessed even +though the block device is NULL. If we take the example of the `bootmeth_extlinux` driver, this call ends up at `extlinux_read_bootflow()`. It has the filesystem ready, so tries various diff --git a/include/bootmeth.h b/include/bootmeth.h index d3d8d608cd7..0fc36104ece 100644 --- a/include/bootmeth.h +++ b/include/bootmeth.h @@ -16,9 +16,12 @@ struct udevice; * enum bootmeth_flags - Flags for bootmeths * * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically + * @BOOTMETHF_ANY_PART: bootmeth is willing to check any partition, even if it + * has no filesystem */ enum bootmeth_flags { BOOTMETHF_GLOBAL = BIT(0), + BOOTMETHF_ANY_PART = BIT(1), }; /** -- cgit v1.3.1 From 3107f78485893895ef1b690a7275c45de629062a Mon Sep 17 00:00:00 2001 From: Sughosh Ganu Date: Tue, 22 Aug 2023 23:10:01 +0530 Subject: doc: Add documentation to highlight capsule generation related updates The EFI capsules can now be generated as part of U-Boot build, through binman. Highlight these changes in the documentation. Signed-off-by: Sughosh Ganu Acked-by: Heinrich Schuchardt --- doc/develop/uefi/uefi.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index a7a41f2facf..f27cabbcce8 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -318,6 +318,9 @@ Run the following command --guid \ +Capsule with firmware version +***************************** + The UEFI specification does not define the firmware versioning mechanism. EDK II reference implementation inserts the FMP Payload Header right before the payload. It coutains the fw_version and lowest supported version, @@ -345,6 +348,43 @@ add --fw-version option in mkeficapsule tool. If the --fw-version option is not set, FMP Payload Header is not inserted and fw_version is set as 0. +Capsule Generation through binman +********************************* + +Support has also been added to generate capsules during U-Boot build +through binman. This requires the platform's DTB to be populated with +the capsule entry nodes for binman. The capsules then can be generated +by specifying the capsule parameters as properties in the capsule +entry node. + +Check the test/py/tests/test_efi_capsule/capsule_gen_binman.dts file +as reference for how a typical binman node for capsule generation +looks like. For generating capsules as part of the platform's build, a +capsule node would then have to be included into the platform's +devicetree. + +A typical binman node for generating a capsule would look like:: + + capsule { + filename = "u-boot.capsule"; + efi-capsule { + image-index = <0x1>; + image-guid = "09d7cf52-0720-4710-91d1-08469b7fe9c8"; + + u-boot { + }; + }; + }; + +In the above example, a capsule file named u-boot.capsule will be +generated with u-boot.bin as it's input payload. The capsule +generation parameters like image-index and image-guid are being +specified as properties. Similarly, other properties like the private +and public key certificate can be specified for generating signed +capsules. Refer :ref:`etype_efi_capsule` for documentation about the +efi-capsule binman entry type, which describes all the properties that +can be specified. + Performing the update ********************* -- cgit v1.3.1 From 1df1d566d21f52703511e55fadd72993a137a464 Mon Sep 17 00:00:00 2001 From: Sughosh Ganu Date: Tue, 22 Aug 2023 23:10:08 +0530 Subject: doc: capsule: Document the new mechanism to embed ESL file into dtb Update the document to specify how the EFI Signature List(ESL) file can be embedded into the platform's dtb as part of the U-Boot build. Signed-off-by: Sughosh Ganu Reviewed-by: Ilias Apalodimas --- doc/develop/uefi/uefi.rst | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index f27cabbcce8..68f9b332d15 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -562,20 +562,11 @@ and used by the steps highlighted below. ... } -You can do step-4 manually with - -.. code-block:: console - - $ dtc -@ -I dts -O dtb -o signature.dtbo signature.dts - $ fdtoverlay -i orig.dtb -o new.dtb -v signature.dtbo - -where signature.dts looks like:: - - &{/} { - signature { - capsule-key = /incbin/("CRT.esl"); - }; - }; +You can perform step-4 through the Kconfig symbol +CONFIG_EFI_CAPSULE_ESL_FILE. This symbol points to the esl file +generated in step-2. Once the symbol has been populated with the path +to the esl file, it will automatically get embedded into the +platform's dtb as part of U-Boot build. Anti-rollback Protection ************************ -- cgit v1.3.1 From 12be60daab224f2cbcb7c6584ab87f0f7caba83c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 21 Aug 2023 21:16:58 -0600 Subject: event: Update documentation for simple spy Now that we have two types of spy, mention this in the documentation. Put the simple spy first, since it seems to be the common case. Signed-off-by: Simon Glass --- doc/develop/event.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/event.rst b/doc/develop/event.rst index cb09e9c85a9..d5043ec4f4c 100644 --- a/doc/develop/event.rst +++ b/doc/develop/event.rst @@ -21,16 +21,31 @@ Declaring a spy To declare a spy, use something like this:: - static int snow_setup_cpus(void *ctx, struct event *event) + static int snow_check_temperature(void) { /* do something */ return 0; } - EVENT_SPY(EVT_DM_POST_INIT_F, snow_setup_cpus); + EVENT_SPY_SIMPLE(EVT_DM_POST_INIT_F, snow_check_temperature); This function is called when EVT_DM_POST_INIT_F is emitted, i.e. after the driver model is initialized (in U-Boot proper before and after relocation). +If you need access to the event data, use `EVENT_SPY_FULL`, like this:: + + static int snow_setup_cpus(void *ctx, struct event *event) + { + /* do something that uses event->data*/ + return 0; + } + EVENT_SPY_FULL(EVT_DM_POST_INIT_F, snow_setup_cpus); + +Note that the context is always NULL for a static spy. See below for information +about how to use a dynamic spy. + +The return value is handled by the event emitter. If non-zero, then the error +is returned to the function which emitted the event, i.e. the one that called +`event_notify()`. Debugging --------- @@ -80,6 +95,10 @@ to be notified when a particular device is probed or removed. This can be handled by enabling `CONFIG_EVENT_DYNAMIC`. It is then possible to call `event_register()` to register a new handler for a particular event. +If some context is need for the spy, you can pass a pointer to +`event_register()` to provide that. Note that the context is only passed to +a spy registered with `EVENT_SPY_FULL`. + Dynamic event handlers are called after all the static event spy handlers have been processed. Of course, since dynamic event handlers are created at runtime it is not possible to use the `event_dump.py` to see them. -- cgit v1.3.1 From 3b58de4d0b6bde8f8dab0fa0c0dc417e57b6c804 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Sep 2023 10:55:55 -0600 Subject: Mark DISTRO_DEFAULTS as deprecated Standard boot has been in place for a while now. Quite a few problems have been found and fixed. It seems like a good time to mark the script-based approach as deprecated and encourage people to use standard boot. Update the DISTRO_DEFAULTS Kconfig to encourage people to move to standard boot, which is able to boot Linux distributions automatically. Add a short migration guide to make this easier. Signed-off-by: Simon Glass Reviewed-by: Tom Rini --- boot/Kconfig | 6 +++++- doc/develop/bootstd.rst | 23 +++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/boot/Kconfig b/boot/Kconfig index 4ebcf310911..7ef44a26fb9 100644 --- a/boot/Kconfig +++ b/boot/Kconfig @@ -784,7 +784,7 @@ config SYS_BOOT_RAMDISK_HIGH endmenu # Boot images config DISTRO_DEFAULTS - bool "Select defaults suitable for booting general purpose Linux distributions" + bool "(deprecated) Script-based booting of Linux distributions" select BOOT_DEFAULTS select AUTO_COMPLETE select CMDLINE_EDITING @@ -792,6 +792,10 @@ config DISTRO_DEFAULTS select HUSH_PARSER select SYS_LONGHELP help + Note: These scripts have been replaced by Standard Boot. Do not use + them on new boards. See 'Migrating from distro_boot' at + doc/develop/bootstd.rst + Select this to enable various options and commands which are suitable for building u-boot for booting general purpose Linux distributions. diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index e8b90752f08..6172dc906bd 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -464,6 +464,28 @@ ready File was loaded and is ready for use. In this state the bootflow is ======= ======================================================================= +Migrating from distro_boot +-------------------------- + +To migrate from distro_boot: + +#. Update your board header files to remove the BOOTENV and BOOT_TARGET_xxx + defines. Standard boot finds available boot devices automatically. + +#. Remove the "boot_targets" variable unless you need it. Standard boot uses a + default order from fastest to slowest, which generally matches the order used + by boards. + +#. Make sure that CONFIG_BOOTSTD_DEFAULTS is enabled by your board, so it can + boot common Linux distributions. + +An example patch is at migrate_patch_. + +If you are using custom boot scripts for your board, consider creating your +own bootmeth to hold the logic. There are various examples at +`boot/bootmeth_...`. + + Theory of operation ------------------- @@ -775,3 +797,4 @@ Other ideas: .. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ .. _distro_boot: https://github.com/u-boot/u-boot/blob/master/boot/distro.c .. _bootflow_h: https://github.com/u-boot/u-boot/blob/master/include/bootflow.h +.. _migrate_patch: https://patchwork.ozlabs.org/project/uboot/patch/20230727215433.578830-2-sjg@chromium.org/ -- cgit v1.3.1