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.2.3 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 + 3 files changed, 151 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 -- cgit v1.2.3 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 --- doc/develop/cedit.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/develop') 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.2.3 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 --- doc/develop/expo.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'doc/develop') 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 -- cgit v1.2.3 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.2.3