From 40b9e0dd0505cc505bb31823c11aad59f5abdd43 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Oct 2021 21:08:50 -0600 Subject: doc: Improve environment documentation further Make various other updates suggested during review of the rST conversion. Signed-off-by: Simon Glass Suggested-by: Heinrich Schuchardt --- doc/develop/environment.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 52 insertions(+) create mode 100644 doc/develop/environment.rst (limited to 'doc/develop') diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst new file mode 100644 index 00000000000..0b86fafbff7 --- /dev/null +++ b/doc/develop/environment.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Environment implementation +========================== + +See :doc:`../usage/environment` for usage information. + +Callback functions for environment variables +-------------------------------------------- + +For some environment variables, the behavior of u-boot needs to change +when their values are changed. This functionality allows functions to +be associated with arbitrary variables. On creation, overwrite, or +deletion, the callback will provide the opportunity for some side +effect to happen or for the change to be rejected. + +The callbacks are named and associated with a function using the +U_BOOT_ENV_CALLBACK macro in your board or driver code. + +These callbacks are associated with variables in one of two ways. The +static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC +in the board configuration to a string that defines a list of +associations. The list must be in the following format:: + + entry = variable_name[:callback_name] + list = entry[,list] + +If the callback name is not specified, then the callback is deleted. +Spaces are also allowed anywhere in the list. + +Callbacks can also be associated by defining the ".callbacks" variable +with the same list format above. Any association in ".callbacks" will +override any association in the static list. You can define +CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the +".callbacks" environment variable in the default or embedded environment. + +If CONFIG_REGEX is defined, the variable_name above is evaluated as a +regular expression. This allows multiple variables to be connected to +the same callback without explicitly listing them all out. + +The signature of the callback functions is:: + + int callback(const char *name, const char *value, enum env_op op, int flags) + +* name - changed environment variable +* value - new value of the environment variable +* op - operation (create, overwrite, or delete) +* flags - attributes of the environment variable change, see flags H_* in + include/search.h + +The return value is 0 if the variable change is accepted and 1 otherwise. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index b3871b16f35..9592d193fca 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -16,6 +16,7 @@ Implementation devicetree/index distro driver-model/index + environment global_data logging makefiles -- cgit v1.2.3 From d5b6e91ba2cac6cb0a2f7437fdbbe792d1acb387 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 3 Nov 2021 21:09:20 -0600 Subject: bloblist: Support allocating the bloblist Typically the bloblist is positioned at a fixed address in memory until relocation. This is convenient when it is set up in SPL or before relocation. But for EFI we want to set it up only when U-Boot proper is running. Add a way to allocate it using malloc() and update the documentation to cover this aspect of bloblist. Note there are no tests of this feature at present, nor any direct testing of bloblist_init(). This can be added, e.g. by making this option controllable at runtime. Signed-off-by: Simon Glass --- doc/develop/bloblist.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/bloblist.rst b/doc/develop/bloblist.rst index 317ebc4919d..47274cf8e26 100644 --- a/doc/develop/bloblist.rst +++ b/doc/develop/bloblist.rst @@ -59,6 +59,22 @@ Bloblist provides a fairly simple API which allows blobs to be created and found. All access is via the blob's tag. Blob records are zeroed when added. +Placing the bloblist +-------------------- + +The bloblist is typically positioned at a fixed address by TPL, or SPL. This +is controlled by `CONFIG_BLOBLIST_ADDR`. But in some cases it is preferable to +allocate the bloblist in the malloc() space. Use the `CONFIG_BLOBLIST_ALLOC` +option to enable this. + +The bloblist is automatically relocated as part of U-Boot relocation. Sometimes +it is useful to expand the bloblist in U-Boot proper, since it may want to add +information for use by Linux. Note that this does not mean that Linux needs to +know anything about the bloblist format, just that it is convenient to use +bloblist to place things contiguously in memory. Set +`CONFIG_BLOBLIST_SIZE_RELOC` to define the expanded size, if needed. + + Finishing the bloblist ---------------------- -- cgit v1.2.3 From 89050244c40e79fc24b24ee84e4e668a6dfc336d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 24 Nov 2021 09:26:39 -0700 Subject: trace: sandbox: Use only the Kconfig options At present there are Kconfig options for tracing, but sandbox uses plain #defines to set them. Correct this and make the tracing command default to enabled so that this is not needed. Signed-off-by: Simon Glass --- doc/develop/trace.rst | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/trace.rst b/doc/develop/trace.rst index 09f5745a909..b22e068ef9e 100644 --- a/doc/develop/trace.rst +++ b/doc/develop/trace.rst @@ -30,16 +30,11 @@ Sandbox is a build of U-Boot that can run under Linux so it is a convenient way of trying out tracing before you use it on your actual board. To do this, follow these steps: -Add the following to include/configs/sandbox.h (if not already there) +Add the following to config/sandbox_defconfig .. code-block:: c - #define CONFIG_TRACE - #define CONFIG_CMD_TRACE - #define CONFIG_TRACE_BUFFER_SIZE (16 << 20) - #define CONFIG_TRACE_EARLY_SIZE (8 << 20) - #define CONFIG_TRACE_EARLY - #define CONFIG_TRACE_EARLY_ADDR 0x00100000 + CONFIG_TRACE=y Build sandbox U-Boot with tracing enabled: -- cgit v1.2.3 From 6ce2237a4076a323e6dcaa92c6f22a149fef6f28 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 24 Nov 2021 09:26:45 -0700 Subject: keyboard: Add a migration message A few boards still use the old keyboard mechanism. Set a deadline for them to update to driver model. Signed-off-by: Simon Glass --- doc/develop/driver-model/migration.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/driver-model/migration.rst b/doc/develop/driver-model/migration.rst index 8bb8601c582..3dbeea6537c 100644 --- a/doc/develop/driver-model/migration.rst +++ b/doc/develop/driver-model/migration.rst @@ -98,3 +98,11 @@ Deadline: 2021.10 The I2C subsystem has supported the driver model since early 2015. Maintainers should submit patches switching over to using CONFIG_DM_I2C and other base driver model options in time for inclusion in the 2021.10 release. + +CONFIG_KEYBOARD +--------------- +Deadline: 2022.10 + +This is a legacy option which has been replaced by driver model. +Maintainers should submit patches switching over to using CONFIG_DM_KEYBOARD and +other base driver model options in time for inclusion in the 2022.10 release. -- cgit v1.2.3 From c3c1614537d4fd2c5b7f1c29887541210bf0b8bd Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 16 Dec 2021 20:59:09 -0700 Subject: arm: riscv: qemu: Explain how to extract the generated dt QEMU currently generates a devicetree for use with U-Boot. Explain how to obtain it. Also explain how to merge it to produce a devicetree with the U-Boot features included. Signed-off-by: Simon Glass --- doc/develop/devicetree/dt_qemu.rst | 48 ++++++++++++++++++++++++++++++++++++++ doc/develop/devicetree/index.rst | 1 + 2 files changed, 49 insertions(+) create mode 100644 doc/develop/devicetree/dt_qemu.rst (limited to 'doc/develop') diff --git a/doc/develop/devicetree/dt_qemu.rst b/doc/develop/devicetree/dt_qemu.rst new file mode 100644 index 00000000000..c25c4fb053d --- /dev/null +++ b/doc/develop/devicetree/dt_qemu.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Devicetree in QEMU +================== + +For QEMU on ARM, RISC-V and one PPC target, the devicetree is created on-the-fly +by QEMU. It is intended for use in Linux but can be used by U-Boot also, so long +as any nodes/properties needed by U-Boot are merged in. + +When `CONFIG_OF_BOARD` is enabled + + +Obtaining the QEMU devicetree +----------------------------- + +Where QEMU generates its own devicetree to pass to U-Boot tou can use +`-dtb u-boot.dtb` to force QEMU to use U-Boot's in-tree version. + +To obtain the devicetree that qemu generates, add `-machine dumpdtb=qemu.dtb`, +e.g.:: + + qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb + + qemu-system-aarch64 -machine virt -machine dumpdtb=qemu.dtb + + qemu-system-riscv64 -machine virt -machine dumpdtb=qemu.dtb + + +Merging in U-Boot nodes/properties +---------------------------------- + +Various U-Boot features require nodes and properties in the U-Boot devicetree +and at present QEMU is unaware of these. To use these you must manually merge +in the appropriate pieces. + +One way to do this is with dtc. This command runs dtc on each .dtb file in turn, +to produce a text file. It drops the duplicate header on the qemu one. Then it +joins them up and runs them through dtc to compile the output:: + + qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb + cat <(dtc -I dtb qemu.dtb) <(dtc -I dtb u-boot.dtb |grep -v /dts-v1/) |dtc - -o merged.dtb + +You can then run qemu with the merged devicetree, e.g.:: + + qemu-system-arm -machine virt -nographic -bios u-boot.bin -dtb merged.dtb + +Note that there seems to be a bug in some versions of qemu where the output of +dumpdtb does not quite match what is provided to U-Boot. diff --git a/doc/develop/devicetree/index.rst b/doc/develop/devicetree/index.rst index fa5db3eb76e..2edb69572dd 100644 --- a/doc/develop/devicetree/index.rst +++ b/doc/develop/devicetree/index.rst @@ -11,3 +11,4 @@ build-time and runtime configuration. intro control + dt_qemu -- cgit v1.2.3 From 613cd0c46796cae340382679bc01ef220daf3768 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 29 Dec 2021 11:57:36 -0700 Subject: efi: Locate all block devices in the app When starting the app, locate all block devices and make them available to U-Boot. This allows listing partitions and accessing files in filesystems. EFI also has the concept of 'disks', meaning boot media. For now, this is not obviously useful in U-Boot, but add code to at least locate these. This can be expanded later as needed. We cannot use printf() in the early stub or app since it is not compiled in Signed-off-by: Simon Glass Reviewed-by: Heinrich Schuchardt --- doc/develop/uefi/u-boot_on_efi.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/uefi/u-boot_on_efi.rst b/doc/develop/uefi/u-boot_on_efi.rst index 5f2f850f071..8f81b799072 100644 --- a/doc/develop/uefi/u-boot_on_efi.rst +++ b/doc/develop/uefi/u-boot_on_efi.rst @@ -265,9 +265,7 @@ This work could be extended in a number of ways: - Figure out how to solve the interrupt problem -- Add more drivers to the application side (e.g. block devices, USB, - environment access). This would mostly be an academic exercise as a strong - use case is not readily apparent, but it might be fun. +- Add more drivers to the application side (e.g.USB, environment access). - Avoid turning off boot services in the stub. Instead allow U-Boot to make use of boot services in case it wants to. It is unclear what it might want -- cgit v1.2.3 From 6e7ad4a45f6e2b036fc56942293b8471ece3341d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 29 Dec 2021 11:57:38 -0700 Subject: x86: Allow booting a kernel from the EFI app At present this is disabled, but it should work so long as the kernel does not need EFI services. Enable it and add a note about remaining work. Signed-off-by: Simon Glass --- doc/develop/uefi/u-boot_on_efi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/uefi/u-boot_on_efi.rst b/doc/develop/uefi/u-boot_on_efi.rst index 8f81b799072..acad6397e81 100644 --- a/doc/develop/uefi/u-boot_on_efi.rst +++ b/doc/develop/uefi/u-boot_on_efi.rst @@ -269,7 +269,7 @@ This work could be extended in a number of ways: - Avoid turning off boot services in the stub. Instead allow U-Boot to make use of boot services in case it wants to. It is unclear what it might want - though. + though. It is better to use the app. Where is the code? ------------------ -- cgit v1.2.3