From ea754aa5658f395200a2b9a2573291a03c63bc77 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Oct 2021 21:08:45 -0600 Subject: doc: Move environment documentation to rST MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move this from the README to rST format. Drop i2cfast since it is obviously obsolete and breaks the formatting. Other changes and improvements are in a following patch. Signed-off-by: Simon Glass Acked-by: Marek Behún --- doc/usage/environment.rst | 381 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 381 insertions(+) create mode 100644 doc/usage/environment.rst (limited to 'doc') diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst new file mode 100644 index 00000000000..7a733b44556 --- /dev/null +++ b/doc/usage/environment.rst @@ -0,0 +1,381 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Environment Variables +===================== + +U-Boot supports user configuration using Environment Variables which +can be made persistent by saving to Flash memory. + +Environment Variables are set using "setenv", printed using +"printenv", and saved to Flash using "saveenv". Using "setenv" +without a value can be used to delete a variable from the +environment. As long as you don't save the environment you are +working with an in-memory copy. In case the Flash area containing the +environment is erased by accident, a default environment is provided. + +Some configuration options can be set using Environment Variables. + +List of environment variables (most likely not complete): + +baudrate + see CONFIG_BAUDRATE + +bootdelay + see CONFIG_BOOTDELAY + +bootcmd + see CONFIG_BOOTCOMMAND + +bootargs + Boot arguments when booting an RTOS image + +bootfile + Name of the image to load with TFTP + +bootm_low + Memory range available for image processing in the bootm + command can be restricted. This variable is given as + a hexadecimal number and defines lowest address allowed + for use by the bootm command. See also "bootm_size" + environment variable. Address defined by "bootm_low" is + also the base of the initial memory mapping for the Linux + kernel -- see the description of CONFIG_SYS_BOOTMAPSZ and + bootm_mapsize. + +bootm_mapsize + Size of the initial memory mapping for the Linux kernel. + This variable is given as a hexadecimal number and it + defines the size of the memory region starting at base + address bootm_low that is accessible by the Linux kernel + during early boot. If unset, CONFIG_SYS_BOOTMAPSZ is used + as the default value if it is defined, and bootm_size is + used otherwise. + +bootm_size + Memory range available for image processing in the bootm + command can be restricted. This variable is given as + a hexadecimal number and defines the size of the region + allowed for use by the bootm command. See also "bootm_low" + environment variable. + +bootstopkeysha256, bootdelaykey, bootstopkey + See README.autoboot + +updatefile + Location of the software update file on a TFTP server, used + by the automatic software update feature. Please refer to + documentation in doc/README.update for more details. + +autoload + if set to "no" (any string beginning with 'n'), + "bootp" will just load perform a lookup of the + configuration from the BOOTP server, but not try to + load any image using TFTP + +autostart + if set to "yes", an image loaded using the "bootp", + "rarpboot", "tftpboot" or "diskboot" commands will + be automatically started (by internally calling + "bootm") + + If set to "no", a standalone image passed to the + "bootm" command will be copied to the load address + (and eventually uncompressed), but NOT be started. + This can be used to load and uncompress arbitrary + data. + +fdt_high + if set this restricts the maximum address that the + flattened device tree will be copied into upon boot. + For example, if you have a system with 1 GB memory + at physical address 0x10000000, while Linux kernel + only recognizes the first 704 MB as low memory, you + may need to set fdt_high as 0x3C000000 to have the + device tree blob be copied to the maximum address + of the 704 MB low memory, so that Linux kernel can + access it during the boot procedure. + + If this is set to the special value 0xFFFFFFFF then + the fdt will not be copied at all on boot. For this + to work it must reside in writable memory, have + sufficient padding on the end of it for u-boot to + add the information it needs into it, and the memory + must be accessible by the kernel. + +fdtcontroladdr + if set this is the address of the control flattened + device tree used by U-Boot when CONFIG_OF_CONTROL is + defined. + +initrd_high + restrict positioning of initrd images: + If this variable is not set, initrd images will be + copied to the highest possible address in RAM; this + is usually what you want since it allows for + maximum initrd size. If for some reason you want to + make sure that the initrd image is loaded below the + CONFIG_SYS_BOOTMAPSZ limit, you can set this environment + variable to a value of "no" or "off" or "0". + Alternatively, you can set it to a maximum upper + address to use (U-Boot will still check that it + does not overwrite the U-Boot stack and data). + + For instance, when you have a system with 16 MB + RAM, and want to reserve 4 MB from use by Linux, + you can do this by adding "mem=12M" to the value of + the "bootargs" variable. However, now you must make + sure that the initrd image is placed in the first + 12 MB as well - this can be done with:: + + setenv initrd_high 00c00000 + + If you set initrd_high to 0xFFFFFFFF, this is an + indication to U-Boot that all addresses are legal + for the Linux kernel, including addresses in flash + memory. In this case U-Boot will NOT COPY the + ramdisk at all. This may be useful to reduce the + boot time on your system, but requires that this + feature is supported by your Linux kernel. + +ipaddr + IP address; needed for tftpboot command + +loadaddr + Default load address for commands like "bootp", + "rarpboot", "tftpboot", "loadb" or "diskboot" + +loads_echo + see CONFIG_LOADS_ECHO + +serverip + TFTP server IP address; needed for tftpboot command + +bootretry + see CONFIG_BOOT_RETRY_TIME + +bootdelaykey + see CONFIG_AUTOBOOT_DELAY_STR + +bootstopkey + see CONFIG_AUTOBOOT_STOP_STR + +ethprime + controls which interface is used first. + +ethact + controls which interface is currently active. + For example you can do the following:: + + => setenv ethact FEC + => ping 192.168.0.1 # traffic sent on FEC + => setenv ethact SCC + => ping 10.0.0.1 # traffic sent on SCC + +ethrotate + When set to "no" U-Boot does not go through all + available network interfaces. + It just stays at the currently selected interface. + +netretry + When set to "no" each network operation will + either succeed or fail without retrying. + When set to "once" the network operation will + fail when all the available network interfaces + are tried once without success. + Useful on scripts which control the retry operation + themselves. + +npe_ucode + set load address for the NPE microcode + +silent_linux + If set then Linux will be told to boot silently, by + changing the console to be empty. If "yes" it will be + made silent. If "no" it will not be made silent. If + unset, then it will be made silent if the U-Boot console + is silent. + +tftpsrcp + If this is set, the value is used for TFTP's + UDP source port. + +tftpdstp + If this is set, the value is used for TFTP's UDP + destination port instead of the Well Know Port 69. + +tftpblocksize + Block size to use for TFTP transfers; if not set, + we use the TFTP server's default block size + +tftptimeout + Retransmission timeout for TFTP packets (in milli- + seconds, minimum value is 1000 = 1 second). Defines + when a packet is considered to be lost so it has to + be retransmitted. The default is 5000 = 5 seconds. + Lowering this value may make downloads succeed + faster in networks with high packet loss rates or + with unreliable TFTP servers. + +tftptimeoutcountmax + maximum count of TFTP timeouts (no + unit, minimum value = 0). Defines how many timeouts + can happen during a single file transfer before that + transfer is aborted. The default is 10, and 0 means + 'no timeouts allowed'. Increasing this value may help + downloads succeed with high packet loss rates, or with + unreliable TFTP servers or client hardware. + +tftpwindowsize + if this is set, the value is used for TFTP's + window size as described by RFC 7440. + This means the count of blocks we can receive before + sending ack to server. + +vlan + When set to a value < 4095 the traffic over + Ethernet is encapsulated/received over 802.1q + VLAN tagged frames. + +bootpretryperiod + Period during which BOOTP/DHCP sends retries. + Unsigned value, in milliseconds. If not set, the period will + be either the default (28000), or a value based on + CONFIG_NET_RETRY_COUNT, if defined. This value has + precedence over the valu based on CONFIG_NET_RETRY_COUNT. + +memmatches + Number of matches found by the last 'ms' command, in hex + +memaddr + Address of the last match found by the 'ms' command, in hex, + or 0 if none + +mempos + Index position of the last match found by the 'ms' command, + in units of the size (.b, .w, .l) of the search + +zbootbase + (x86 only) Base address of the bzImage 'setup' block + +zbootaddr + (x86 only) Address of the loaded bzImage, typically + BZIMAGE_LOAD_ADDR which is 0x100000 + + +Image locations +--------------- + +The following image location variables contain the location of images +used in booting. The "Image" column gives the role of the image and is +not an environment variable name. The other columns are environment +variable names. "File Name" gives the name of the file on a TFTP +server, "RAM Address" gives the location in RAM the image will be +loaded to, and "Flash Location" gives the image's address in NOR +flash or offset in NAND flash. + +*Note* - these variables don't have to be defined for all boards, some +boards currently use other variables for these purposes, and some +boards use these variables for other purposes. + +================= ============== ================ ============== +Image File Name RAM Address Flash Location +================= ============== ================ ============== +u-boot u-boot u-boot_addr_r u-boot_addr +Linux kernel bootfile kernel_addr_r kernel_addr +device tree blob fdtfile fdt_addr_r fdt_addr +ramdisk ramdiskfile ramdisk_addr_r ramdisk_addr +================= ============== ================ ============== + + +Automatically updated variables +------------------------------- + +The following environment variables may be used and automatically +updated by the network boot commands ("bootp" and "rarpboot"), +depending the information provided by your boot server: + +========= =================================================== +Variable Notes +========= =================================================== +bootfile see above +dnsip IP address of your Domain Name Server +dnsip2 IP address of your secondary Domain Name Server +gatewayip IP address of the Gateway (Router) to use +hostname Target hostname +ipaddr See above +netmask Subnet Mask +rootpath Pathname of the root filesystem on the NFS server +serverip see above +========= =================================================== + + +Special environment variables +----------------------------- + +There are two special Environment Variables: + +serial# + contains hardware identification information such as type string and/or + serial number +ethaddr + Ethernet address + +These variables can be set only once (usually during manufacturing of +the board). U-Boot refuses to delete or overwrite these variables +once they have been set once. + +Also: + +ver + Contains the U-Boot version string as printed + with the "version" command. This variable is + readonly (see CONFIG_VERSION_VARIABLE). + +Please note that changes to some configuration parameters may take +only effect after the next boot (yes, that's just like Windoze :-). + + +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. -- cgit From 86b9c3e4e48ba47ef28781d06b97846aca74bc8e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Oct 2021 21:08:46 -0600 Subject: env: Allow U-Boot scripts to be placed in a .env file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit At present U-Boot environment variables, and thus scripts, are defined by CONFIG_EXTRA_ENV_SETTINGS. It is painful to add large amounts of text to this file and dealing with quoting and newlines is harder than it should be. It would be better if we could just type the script into a text file and have it included by U-Boot. Add a feature that brings in a .env file associated with the board config, if present. To use it, create a file in a board/ directory, typically called .env and controlled by the CONFIG_ENV_SOURCE_FILE option. The environment variables should be of the form "var=value". Values can extend to multiple lines. See the README under 'Environment Variables:' for more information and an example. In many cases environment variables need access to the U-Boot CONFIG variables to select different options. Enable this so that the environment scripts can be as useful as the ones currently in the board config files. This uses the C preprocessor, means that comments can be included in the environment using /* ... */ Also support += to allow variables to be appended to. This is needed when using the preprocessor. Signed-off-by: Simon Glass Reviewed-by: Marek Behún Tested-by: Marek Behún --- doc/usage/environment.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++- doc/usage/index.rst | 1 + 2 files changed, 81 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 7a733b44556..043c02d9a94 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -15,7 +15,86 @@ environment is erased by accident, a default environment is provided. Some configuration options can be set using Environment Variables. -List of environment variables (most likely not complete): +Text-based Environment +---------------------- + +The default environment for a board is created using a `.env` environment file +using a simple text format. The base filename for this is defined by +`CONFIG_ENV_SOURCE_FILE`, or `CONFIG_SYS_BOARD` if that is empty. + +The file must be in the board directory and have a .env extension, so +assuming that there is a board vendor, the resulting filename is therefore:: + + board///.env + +or:: + + board///.env + +This is a plain text file where you can type your environment variables in +the form `var=value`. Blank lines and multi-line variables are supported. +The conversion script looks for a line that starts in column 1 with a string +and has an equals sign immediately afterwards. Spaces before the = are not +permitted. It is a good idea to indent your scripts so that only the 'var=' +appears at the start of a line. + +To add additional text to a variable you can use `var+=value`. This text is +merged into the variable during the make process and made available as a +single value to U-Boot. Variables can contain `+` characters but in the unlikely +event that you want to have a variable name ending in plus, put a backslash +before the `+` so that the script knows you are not adding to an existing +variable but assigning to a new one:: + + maximum\+=value + +This file can include C-style comments. Blank lines and multi-line +variables are supported, and you can use normal C preprocessor directives +and CONFIG defines from your board config also. + +For example, for snapper9260 you would create a text file called +`board/bluewater/snapper9260.env` containing the environment text. + +Example:: + + stdout=serial + #ifdef CONFIG_LCD + stdout+=,lcd + #endif + bootcmd= + /* U-Boot script for booting */ + + if [ -z ${tftpserverip} ]; then + echo "Use 'setenv tftpserverip a.b.c.d' to set IP address." + fi + + usb start; setenv autoload n; bootp; + tftpboot ${tftpserverip}: + bootm + failed= + /* Print a message when boot fails */ + echo CONFIG_SYS_BOARD boot failed - please check your image + echo Load address is CONFIG_SYS_LOAD_ADDR + +If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then +the old-style C environment is used instead. See below. + +Old-style C environment +----------------------- + +Traditionally, the default environment is created in `include/env_default.h`, +and can be augmented by various `CONFIG` defines. See that file for details. In +particular you can define `CONFIG_EXTRA_ENV_SETTINGS` in your board file +to add environment variables. + +Board maintainers are encouraged to migrate to the text-based environment as it +is easier to maintain. The distro-board script still requires the old-style +environment but work is underway to address this. + + +List of environment variables +----------------------------- + +This is most-likely not complete: baudrate see CONFIG_BAUDRATE diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 356f2a56181..4314112ff34 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -10,6 +10,7 @@ Use U-Boot netconsole partitions cmdline + environment Shell commands -------------- -- cgit From 1df02d1d0152b5029e96517f7a7dc1c389610b66 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Oct 2021 21:08:48 -0600 Subject: doc: Mention CONFIG_DEFAULT_ENV_FILE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add mention of this option since it does a similar thing to the text environment. Signed-off-by: Simon Glass Suggested-by: Rasmus Villemoes Reviewed-by: Marek Behún --- doc/usage/environment.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'doc') diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 043c02d9a94..6f3066e2b65 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -458,3 +458,18 @@ The signature of the callback functions is:: include/search.h The return value is 0 if the variable change is accepted and 1 otherwise. + + +External environment file +------------------------- + +The `CONFIG_USE_DEFAULT_ENV_FILE` option provides a way to bypass the +environment generation in U-Boot. If enabled, then `CONFIG_DEFAULT_ENV_FILE` +provides the name of a file which is converted into the environment, +completely bypassing the standard environment variables in `env_default.h`. + +The format is the same as accepted by the mkenvimage tool, with lines containing +key=value pairs. Blank lines and lines beginning with # are ignored. + +Future work may unify this feature with the text-based environment, perhaps +moving the contents of `env_default.h` to a text file. -- cgit From 5ba9e01a3e70985e5839d941b307b894c13d78dc Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Oct 2021 21:08:49 -0600 Subject: doc: Improve environment documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make various updates suggested during review of the rST conversion. Signed-off-by: Simon Glass Reviewed-by: Marek Behún Suggested-by: Wolfgang Denk --- doc/usage/environment.rst | 36 +++++++++++++++++++++++++++--------- doc/usage/index.rst | 1 + 2 files changed, 28 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 6f3066e2b65..af193739a5a 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -4,16 +4,20 @@ Environment Variables ===================== U-Boot supports user configuration using Environment Variables which -can be made persistent by saving to Flash memory. +can be made persistent by saving to persistent storage, for example flash +memory. -Environment Variables are set using "setenv", printed using -"printenv", and saved to Flash using "saveenv". Using "setenv" +Environment Variables are set using "env set" (alias "setenv"), printed using +"env print" (alias "printenv"), and saved to persistent storage using +"env save" (alias "saveenv"). Using "env set" without a value can be used to delete a variable from the -environment. As long as you don't save the environment you are +environment. As long as you don't save the environment, you are working with an in-memory copy. In case the Flash area containing the environment is erased by accident, a default environment is provided. -Some configuration options can be set using Environment Variables. +Some configuration is controlled by Environment Variables, so that setting the +variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading +from tftp). Text-based Environment ---------------------- @@ -94,16 +98,24 @@ environment but work is underway to address this. List of environment variables ----------------------------- +Some configuration options can be set using Environment Variables. In many cases +the value in the default environment comes from a CONFIG option - see +`include/env_default.h`) for this. + This is most-likely not complete: baudrate - see CONFIG_BAUDRATE + Current baud rate used by the serial console. The built-in value is set by + CONFIG_BAUDRATE (see `drivers/serial/Kconfig`) bootdelay - see CONFIG_BOOTDELAY + Current autoboot delay. The built-in value is set by CONFIG_BOOTDELAY (see + `common/Kconfig`) bootcmd - see CONFIG_BOOTCOMMAND + Defines a command string that is automatically executed when no character + is read on the console interface within a cetain boot delay after reset. + The built-in value is set by CONFIG_BOOTCOMMAND (see `common/Kconfig`) bootargs Boot arguments when booting an RTOS image @@ -149,7 +161,7 @@ autoload if set to "no" (any string beginning with 'n'), "bootp" will just load perform a lookup of the configuration from the BOOTP server, but not try to - load any image using TFTP + load any image using TFTP or DHCP. autostart if set to "yes", an image loaded using the "bootp", @@ -315,6 +327,8 @@ vlan Ethernet is encapsulated/received over 802.1q VLAN tagged frames. + Note: This appears not to be used in U-Boot. See `README.VLAN`. + bootpretryperiod Period during which BOOTP/DHCP sends retries. Unsigned value, in milliseconds. If not set, the period will @@ -356,6 +370,10 @@ flash or offset in NAND flash. boards currently use other variables for these purposes, and some boards use these variables for other purposes. +Also note that most of these variables are just a commonly used set of variable +names, used in some other variable definitions, but are not hard-coded anywhere +in U-Boot code. + ================= ============== ================ ============== Image File Name RAM Address Flash Location ================= ============== ================ ============== diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 4314112ff34..04dea9f0f8e 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -5,6 +5,7 @@ Use U-Boot :maxdepth: 1 dfu + environment fdt_overlays fit netconsole -- cgit 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 + doc/usage/environment.rst | 115 +++++++++++++++++--------------------------- 3 files changed, 95 insertions(+), 72 deletions(-) create mode 100644 doc/develop/environment.rst (limited to 'doc') 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 diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index af193739a5a..8ddc672d467 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -3,11 +3,11 @@ Environment Variables ===================== -U-Boot supports user configuration using Environment Variables which +U-Boot supports user configuration using environment variables which can be made persistent by saving to persistent storage, for example flash memory. -Environment Variables are set using "env set" (alias "setenv"), printed using +Environment variables are set using "env set" (alias "setenv"), printed using "env print" (alias "printenv"), and saved to persistent storage using "env save" (alias "saveenv"). Using "env set" without a value can be used to delete a variable from the @@ -98,27 +98,37 @@ environment but work is underway to address this. List of environment variables ----------------------------- -Some configuration options can be set using Environment Variables. In many cases -the value in the default environment comes from a CONFIG option - see +Some device configuration options can be set using environment variables. In +many cases the value in the default environment comes from a CONFIG option - see `include/env_default.h`) for this. This is most-likely not complete: baudrate - Current baud rate used by the serial console. The built-in value is set by - CONFIG_BAUDRATE (see `drivers/serial/Kconfig`) + Used to set the baudrate of the UART - it defaults to CONFIG_BAUDRATE (which + defaults to 115200). bootdelay - Current autoboot delay. The built-in value is set by CONFIG_BOOTDELAY (see - `common/Kconfig`) + Delay before automatically running bootcmd. During this time the user + can choose to enter the shell (or the boot menu if + CONFIG_AUTOBOOT_MENU_SHOW=y): + + - 0 to autoboot with no delay, but you can stop it by key input. + - -1 to disable autoboot. + - -2 to autoboot with no delay and not check for abort + + The default value is defined by CONFIG_BOOTDELAY. + The value of 'bootdelay' is overridden by the /config/bootdelay value in + the device-tree if CONFIG_OF_CONTROL=y. + Does it really make sense that the devicetree overrides the user setting? bootcmd - Defines a command string that is automatically executed when no character - is read on the console interface within a cetain boot delay after reset. - The built-in value is set by CONFIG_BOOTCOMMAND (see `common/Kconfig`) + The command that is run if the user does not enter the shell during the + boot delay. bootargs - Boot arguments when booting an RTOS image + Command line arguments passed when booting an operating system or binary + image bootfile Name of the image to load with TFTP @@ -159,12 +169,12 @@ updatefile autoload if set to "no" (any string beginning with 'n'), - "bootp" will just load perform a lookup of the + "bootp" and "dhcp" will just load perform a lookup of the configuration from the BOOTP server, but not try to load any image using TFTP or DHCP. autostart - if set to "yes", an image loaded using the "bootp", + if set to "yes", an image loaded using the "bootp", "dhcp", "rarpboot", "tftpboot" or "diskboot" commands will be automatically started (by internally calling "bootm") @@ -186,7 +196,8 @@ fdt_high of the 704 MB low memory, so that Linux kernel can access it during the boot procedure. - If this is set to the special value 0xFFFFFFFF then + If this is set to the special value 0xffffffff (32-bit machines) or + 0xffffffffffffffff (64-bit machines) then the fdt will not be copied at all on boot. For this to work it must reside in writable memory, have sufficient padding on the end of it for u-boot to @@ -220,7 +231,8 @@ initrd_high setenv initrd_high 00c00000 - If you set initrd_high to 0xFFFFFFFF, this is an + If you set initrd_high to 0xffffffff (32-bit machines) or + 0xffffffffffffffff (64-bit machines), this is an indication to U-Boot that all addresses are legal for the Linux kernel, including addresses in flash memory. In this case U-Boot will NOT COPY the @@ -251,7 +263,7 @@ bootstopkey see CONFIG_AUTOBOOT_STOP_STR ethprime - controls which interface is used first. + controls which network interface is used first. ethact controls which interface is currently active. @@ -265,7 +277,9 @@ ethact ethrotate When set to "no" U-Boot does not go through all available network interfaces. - It just stays at the currently selected interface. + It just stays at the currently selected interface. When unset or set to + anything other than "no", U-Boot does go through all + available network interfaces. netretry When set to "no" each network operation will @@ -276,12 +290,9 @@ netretry Useful on scripts which control the retry operation themselves. -npe_ucode - set load address for the NPE microcode - silent_linux If set then Linux will be told to boot silently, by - changing the console to be empty. If "yes" it will be + adding 'console=' to its command line. If "yes" it will be made silent. If "no" it will not be made silent. If unset, then it will be made silent if the U-Boot console is silent. @@ -292,7 +303,7 @@ tftpsrcp tftpdstp If this is set, the value is used for TFTP's UDP - destination port instead of the Well Know Port 69. + destination port instead of the default port 69. tftpblocksize Block size to use for TFTP transfers; if not set, @@ -415,11 +426,12 @@ serial# contains hardware identification information such as type string and/or serial number ethaddr - Ethernet address + Ethernet address. If CONFIG_REGEX=y, also eth*addr (where * is an integer). These variables can be set only once (usually during manufacturing of the board). U-Boot refuses to delete or overwrite these variables -once they have been set once. +once they have been set, unless CONFIG_ENV_OVERWRITE is enabled in the board +configuration. Also: @@ -429,53 +441,7 @@ ver readonly (see CONFIG_VERSION_VARIABLE). Please note that changes to some configuration parameters may take -only effect after the next boot (yes, that's just like Windoze :-). - - -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. +only effect after the next boot (yes, that's just like Windows). External environment file @@ -491,3 +457,8 @@ key=value pairs. Blank lines and lines beginning with # are ignored. Future work may unify this feature with the text-based environment, perhaps moving the contents of `env_default.h` to a text file. + +Implementation +-------------- + +See :doc:`../develop/environment` for internal development details. -- cgit From 78398652723b6fe743751ffb19d8256b7e3e0a4e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Oct 2021 21:08:52 -0600 Subject: bootm: Tidy up use of autostart env var This has different semantics in different places. Go with the bootm method and put it in a common function so that the behaviour is consistent in U-Boot. Update the docs. To be clear, this changes the way that 'bootelf' and standalone boot work. Before, if autostart was set to "fred" or "YES", for example, they would consider that a "yes". This may change behaviour for some boards, but the only in-tree boards which mention autostart use "no" to disable it, which will still work. Signed-off-by: Simon Glass Suggested-by: Wolfgang Denk --- doc/usage/environment.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 8ddc672d467..d295cc89878 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -179,8 +179,9 @@ autostart be automatically started (by internally calling "bootm") - If set to "no", a standalone image passed to the - "bootm" command will be copied to the load address + If unset, or set to "1"/"yes"/"true" (case insensitive, just the first + character is enough), a standalone image + passed to the "bootm" command will be copied to the load address (and eventually uncompressed), but NOT be started. This can be used to load and uncompress arbitrary data. -- cgit From b814e0007e060b5cce314edcf5c0507a67cafd73 Mon Sep 17 00:00:00 2001 From: Mark Kettenis Date: Tue, 2 Nov 2021 18:21:57 +0100 Subject: pinctrl: Add Apple pinctrl driver This driver supports both pin muxing and GPIO support for the pin control logic found on Apple SoCs. Signed-off-by: Mark Kettenis --- .../pinctrl/apple,pinctrl.yaml | 106 +++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 doc/device-tree-bindings/pinctrl/apple,pinctrl.yaml (limited to 'doc') diff --git a/doc/device-tree-bindings/pinctrl/apple,pinctrl.yaml b/doc/device-tree-bindings/pinctrl/apple,pinctrl.yaml new file mode 100644 index 00000000000..d50571affd1 --- /dev/null +++ b/doc/device-tree-bindings/pinctrl/apple,pinctrl.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/apple,pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple GPIO controller + +maintainers: + - Mark Kettenis + +description: | + The Apple GPIO controller is a simple combined pin and GPIO + controller present on Apple ARM SoC platforms, including various + iPhone and iPad devices and the "Apple Silicon" Macs. + +properties: + compatible: + items: + - const: apple,t8103-pinctrl + - const: apple,pinctrl + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + gpio-ranges: + maxItems: 1 + + interrupts: + description: One interrupt for each of the (up to 7) interrupt + groups supported by the controller sorted by interrupt group + number in ascending order. + minItems: 1 + maxItems: 7 + + interrupt-controller: true + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + pinmux: + description: + Values are constructed from pin number and alternate function + configuration number using the APPLE_PINMUX() helper macro + defined in include/dt-bindings/pinctrl/apple.h. + + required: + - pinmux + + additionalProperties: false + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - gpio-ranges + +additionalProperties: false + +examples: + - | + #include + #include + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pinctrl: pinctrl@23c100000 { + compatible = "apple,t8103-pinctrl", "apple,pinctrl"; + reg = <0x2 0x3c100000 0x0 0x100000>; + clocks = <&gpio_clk>; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pinctrl 0 0 212>; + + interrupt-controller; + interrupt-parent = <&aic>; + interrupts = , + , + , + , + , + , + ; + + pcie_pins: pcie-pins { + pinmux = , + , + ; + }; + }; + }; -- cgit From fcb41d4db287129aaac3135881b669ad64e12a69 Mon Sep 17 00:00:00 2001 From: Etienne Carriere Date: Tue, 9 Nov 2021 17:08:23 +0100 Subject: dt-bindings: arm: scmi: OP-TEE as transport channel for SCMI messages Introduce compatible "linaro,scmi-optee" for SCMI transport channel based on an OP-TEE service invocation. Define "linaro,optee-channel-id" property to identify the OP-TEE SCMI channel used by the protocol(s). OP-TEE SCMI transport can either use shared memory or a static shared memory buffer identified by the DT. These bindings were posted to the Linux kernel DT bindings mailing list and acked by maintainer [1]. Link: [1] https://lore.kernel.org/linux-arm-kernel/20211029102118.GG6526@e120937-lin/T/ Cc: Jaehoon Chung Reviewed-by: Patrick Delaunay Signed-off-by: Etienne Carriere --- doc/device-tree-bindings/arm/arm,scmi.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/device-tree-bindings/arm/arm,scmi.txt b/doc/device-tree-bindings/arm/arm,scmi.txt index a76124f4a30..92572eabb58 100644 --- a/doc/device-tree-bindings/arm/arm,scmi.txt +++ b/doc/device-tree-bindings/arm/arm,scmi.txt @@ -14,7 +14,8 @@ Required properties: The scmi node with the following properties shall be under the /firmware/ node. -- compatible : shall be "arm,scmi" or "arm,scmi-smc" for smc/hvc transports +- compatible : shall be "arm,scmi" or "arm,scmi-smc" for smc/hvc transports, + or "linaro,scmi-optee" for OP-TEE transport. - mboxes: List of phandle and mailbox channel specifiers. It should contain exactly one or two mailboxes, one for transmitting messages("tx") and another optional for receiving the notifications("rx") if @@ -26,6 +27,8 @@ The scmi node with the following properties shall be under the /firmware/ node. - #size-cells : should be '0' as 'reg' property doesn't have any size associated with it. - arm,smc-id : SMC id required when using smc or hvc transports +- linaro,optee-channel-id : Channel specifier required when using OP-TEE + transport. Optional properties: @@ -33,16 +36,16 @@ Optional properties: See Documentation/devicetree/bindings/mailbox/mailbox.txt for more details about the generic mailbox controller and client driver bindings. - -The mailbox is the only permitted method of calling the SCMI firmware. Mailbox doorbell is used as a mechanism to alert the presence of a messages and/or notification. Each protocol supported shall have a sub-node with corresponding compatible as described in the following sections. If the platform supports dedicated -communication channel for a particular protocol, the 3 properties namely: -mboxes, mbox-names and shmem shall be present in the sub-node corresponding -to that protocol. +communication channel for a particular protocol, properties shall be present +in the sub-node corresponding to that protocol. These properties are: +- mboxes, mbox-names and shmem for mailbox transport +- arm,smc-id and shmem for smc/hvc transport +- linaro,optee-channel-id and possibly shmem for OP-TEE transport Clock/Performance bindings for the clocks/OPPs based on SCMI Message Protocol ------------------------------------------------------------ -- cgit From 1fb115e4d2a69118388e82af13b1159e102e539b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 19 Sep 2021 15:49:35 -0600 Subject: sf: doc: Add documentation for the 'sf' command This command is fairly complicated so documentation is useful. Unfortunately I an not sure how the MTD side of things works and cannot find information about that. Signed-off-by: Simon Glass Acked-by: Pratyush Yadav Reviewed-by: Jagan Teki Acked-by: Heinrich Schuchardt --- doc/usage/index.rst | 1 + doc/usage/sf.rst | 245 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 246 insertions(+) create mode 100644 doc/usage/sf.rst (limited to 'doc') diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 04dea9f0f8e..3905540735c 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -45,6 +45,7 @@ Shell commands qfw reset sbi + sf scp03 setexpr size diff --git a/doc/usage/sf.rst b/doc/usage/sf.rst new file mode 100644 index 00000000000..71bd1be5175 --- /dev/null +++ b/doc/usage/sf.rst @@ -0,0 +1,245 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +sf command +========== + +Synopis +------- + +:: + + sf probe [[[:]] [ []]] + sf read | + sf write | + sf erase | + sf update | + sf protect lock|unlock + sf test | + +Description +----------- + +The *sf* command is used to access SPI flash, supporting read/write/erase and +a few other functions. + +Probe +----- + +The flash must first be probed with *sf probe* before any of the other +subcommands can be used. All of the parameters are optional: + +bus + SPI bus number containing the SPI-flash chip, e.g. 0. If you don't know + the number, you can use 'dm uclass' to see all the spi devices, + and check the value for 'seq' for each one (here 0 and 2):: + + uclass 89: spi + 0 spi@0 @ 05484960, seq 0 + 1 spi@1 @ 05484b40, seq 2 + +cs + SPI chip-select to use for the chip. This is often 0 and can be omitted, + but in some cases multiple slaves are attached to a SPI controller, + selected by a chip-select line for each one. + +hz + Speed of the SPI bus in hertz. This normally defaults to 100000, i.e. + 100KHz, which is very slow. Note that if the device exists in the + device tree, there might be a speed provided there, in which case this + setting is ignored. + +mode + SPI mode to use: + + ===== ================ + Mode Meaning + ===== ================ + 0 CPOL=0, CPHA=0 + 1 CPOL=0, CPHA=1 + 2 CPOL=1, CPHA=0 + 3 CPOL=1, CPHA=1 + ===== ================ + + Clock phase (CPHA) 0 means that data is transferred (sampled) on the + first clock edge; 1 means the second. + + Clock polarity (CPOL) controls the idle state of the clock, 0 for low, + 1 for high. + The active state is the opposite of idle. + + You may find this `SPI documentation`_ useful. + +Parameters for other subcommands (described below) are as follows: + +addr + Memory address to start transfer + +offset + Flash offset to start transfer + +partition + If the parameter is not numeric, it is assumed to be a partition + description in the format , which is not + covered here. This requires CONFIG_CMD_MTDPARTS. + +len + Number of bytes to transfer + +Read +~~~~ + +Use *sf read* to read from SPI flash to memory. The read will fail if an +attempt is made to read past the end of the flash. + + +Write +~~~~~ + +Use *sf write* to write from memory to SPI flash. The SPI flash should be +erased first, since otherwise the result is undefined. + +The write will fail if an attempt is made to read past the end of the flash. + + +Erase +~~~~~ + +Use *sf erase* to erase a region of SPI flash. The erase will fail if any part +of the region to be erased is protected or lies past the end of the flash. It +may also fail if the start offset or length are not aligned to an erase region +(e.g. 256 bytes). + + +Update +~~~~~~ + +Use *sf update* to automatically erase and update a region of SPI flash from +memory. This works a sector at a time (typical 4KB or 64KB). For each +sector it first checks if the sector already has the right data. If so it is +skipped. If not, the sector is erased and the new data written. Note that if +the length is not a multiple of the erase size, the space after the data in +the last sector will be erased. If the offset does not start at the beginning +of an erase block, the operation will fail. + +Speed statistics are shown including the number of bytes that were already +correct. + + +Protect +~~~~~~~ + +SPI-flash chips often have a protection feature where the chip is split up into +regions which can be locked or unlocked. With *sf protect* it is possible to +change these settings, if supported by the driver. + +lock|unlock + Selects whether to lock or unlock the sectors + + + Start sector number to lock/unlock. This may be the byte offset or some + other value, depending on the chip. + + + Number of bytes to lock/unlock + + +Test +~~~~ + +A convenient and fast *sf test* subcommand provides a way to check that SPI +flash is working as expected. This works in four stages: + + * erase - erases the entire region + * check - checks that the region is erased + * write - writes a test pattern to the region, consisting of the U-Boot code + * read - reads back the test pattern to check that it was written correctly + +Memory is allocated for two buffers, each bytes in size. At typical +size is 64KB to 1MB. The offset and size must be aligned to an erase boundary. + +Note that this test will fail if any part of the SPI flash is write-protected. + + +Examples +-------- + +This first example uses sandbox:: + + => sf probe + SF: Detected m25p16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB + => sf read 1000 1100 80000 + device 0 offset 0x1100, size 0x80000 + SF: 524288 bytes @ 0x1100 Read: OK + => md 1000 + 00001000: edfe0dd0 f33a0000 78000000 84250000 ......:....x..%. + 00001010: 28000000 11000000 10000000 00000000 ...(............ + 00001020: 6f050000 0c250000 00000000 00000000 ...o..%......... + 00001030: 00000000 00000000 00000000 00000000 ................ + 00001040: 00000000 00000000 00000000 00000000 ................ + 00001050: 00000000 00000000 00000000 00000000 ................ + 00001060: 00000000 00000000 00000000 00000000 ................ + 00001070: 00000000 00000000 01000000 00000000 ................ + 00001080: 03000000 04000000 00000000 01000000 ................ + 00001090: 03000000 04000000 0f000000 01000000 ................ + 000010a0: 03000000 08000000 1b000000 646e6173 ............sand + 000010b0: 00786f62 03000000 08000000 21000000 box............! + 000010c0: 646e6173 00786f62 01000000 61696c61 sandbox.....alia + 000010d0: 00736573 03000000 07000000 2c000000 ses............, + 000010e0: 6332692f 00003040 03000000 07000000 /i2c@0.......... + 000010f0: 31000000 6963702f 00003040 03000000 ...1/pci@0...... + => sf erase 0 80000 + SF: 524288 bytes @ 0x0 Erased: OK + => sf read 1000 1100 80000 + device 0 offset 0x1100, size 0x80000 + SF: 524288 bytes @ 0x1100 Read: OK + => md 1000 + 00001000: ffffffff ffffffff ffffffff ffffffff ................ + 00001010: ffffffff ffffffff ffffffff ffffffff ................ + 00001020: ffffffff ffffffff ffffffff ffffffff ................ + 00001030: ffffffff ffffffff ffffffff ffffffff ................ + 00001040: ffffffff ffffffff ffffffff ffffffff ................ + 00001050: ffffffff ffffffff ffffffff ffffffff ................ + 00001060: ffffffff ffffffff ffffffff ffffffff ................ + 00001070: ffffffff ffffffff ffffffff ffffffff ................ + 00001080: ffffffff ffffffff ffffffff ffffffff ................ + 00001090: ffffffff ffffffff ffffffff ffffffff ................ + 000010a0: ffffffff ffffffff ffffffff ffffffff ................ + 000010b0: ffffffff ffffffff ffffffff ffffffff ................ + 000010c0: ffffffff ffffffff ffffffff ffffffff ................ + 000010d0: ffffffff ffffffff ffffffff ffffffff ................ + 000010e0: ffffffff ffffffff ffffffff ffffffff ................ + 000010f0: ffffffff ffffffff ffffffff ffffffff ................ + +This second example is running on coral, an x86 Chromebook:: + + => sf probe + SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB + => sf erase 300000 80000 + SF: 524288 bytes @ 0x300000 Erased: OK + => sf update 1110000 300000 80000 + device 0 offset 0x300000, size 0x80000 + 524288 bytes written, 0 bytes skipped in 0.457s, speed 1164578 B/s + + # This does nothing as the flash is already updated + => sf update 1110000 300000 80000 + device 0 offset 0x300000, size 0x80000 + 0 bytes written, 524288 bytes skipped in 0.196s, speed 2684354 B/s + => sf test 00000 80000 # try a protected region + SPI flash test: + Erase failed (err = -5) + Test failed + => sf test 800000 80000 + SPI flash test: + 0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps + 1 check: 192 ticks, 2666 KiB/s 21.328 Mbps + 2 write: 227 ticks, 2255 KiB/s 18.040 Mbps + 3 read: 189 ticks, 2708 KiB/s 21.664 Mbps + Test passed + 0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps + 1 check: 192 ticks, 2666 KiB/s 21.328 Mbps + 2 write: 227 ticks, 2255 KiB/s 18.040 Mbps + 3 read: 189 ticks, 2708 KiB/s 21.664 Mbps + + +.. _SPI documentation: + https://en.wikipedia.org/wiki/Serial_Peripheral_Interface -- cgit From 0bf61aced283a4ec256f1d8fe919e8890da2191c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 23 Oct 2021 17:25:59 -0600 Subject: sandbox: mmc: Support a backing file Provide a way for sandbox MMC to present data from a backing file. This allows a filesystem to be created on the host and easily served via an emulated mmc device. Signed-off-by: Simon Glass --- doc/device-tree-bindings/mmc/sandbox,mmc.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 doc/device-tree-bindings/mmc/sandbox,mmc.txt (limited to 'doc') diff --git a/doc/device-tree-bindings/mmc/sandbox,mmc.txt b/doc/device-tree-bindings/mmc/sandbox,mmc.txt new file mode 100644 index 00000000000..1170bcd6a00 --- /dev/null +++ b/doc/device-tree-bindings/mmc/sandbox,mmc.txt @@ -0,0 +1,18 @@ +Sandbox MMC +=========== + +Required properties: +- compatible : "sandbox,mmc" + +Optional properties: +- filename : Name of backing file, if any. This is mapped into the MMC device + so can be used to provide a filesystem or other test data + + +Example +------- + +mmc2 { + compatible = "sandbox,mmc"; + non-removable; +}; -- cgit From 9819fe345cc9de8ab1ca8c53999b5d460a8d0e7d Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Mon, 15 Nov 2021 15:32:29 +0100 Subject: stm32mp1: ram: remove the support of calibration result The support of a predefined DDR PHY tuning result is removed for STM32MP1 driver because it is not needed at the supported frequency when built-in calibration is executed. The calibration parameters were provided in the device tree by the optional node "st,phy-cal", activated in ddr helper file by the compilation flag DDR_PHY_CAL_SKIP and filled with values generated by the CubeMX DDR utilities. This patch - updates the binding file to remove "st,phy-cal" support - updates the device trees and remove the associated defines - simplifies the STM32MP1 DDR driver and remove the support of the optional parameter "st,phy-cal" After this patch, the built-in calibration is always executed and the calibration registers are moved in the phy dynamic part; that allows manual tests. Signed-off-by: Patrick Delaunay Reviewed-by: Patrice Chotard --- .../memory-controllers/st,stm32mp1-ddr.txt | 32 ---------------------- 1 file changed, 32 deletions(-) (limited to 'doc') diff --git a/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt b/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt index ac6a7df4327..926e3e83b3f 100644 --- a/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt +++ b/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt @@ -128,23 +128,6 @@ phyc attributes: MR2 MR3 -- st,phy-cal : phy cal depending of calibration or tuning of DDR - This parameter is optional; when it is absent the built-in PHY - calibration is done. - for STM32MP15x: 12 values are requested in this order - DX0DLLCR - DX0DQTR - DX0DQSTR - DX1DLLCR - DX1DQTR - DX1DQSTR - DX2DLLCR - DX2DQTR - DX2DQSTR - DX3DLLCR - DX3DQTR - DX3DQSTR - Example: / { @@ -280,21 +263,6 @@ Example: 0x00000000 /*MR3*/ >; - st,phy-cal = < - 0x40000000 /*DX0DLLCR*/ - 0xFFFFFFFF /*DX0DQTR*/ - 0x3DB02000 /*DX0DQSTR*/ - 0x40000000 /*DX1DLLCR*/ - 0xFFFFFFFF /*DX1DQTR*/ - 0x3DB02000 /*DX1DQSTR*/ - 0x40000000 /*DX2DLLCR*/ - 0xFFFFFFFF /*DX2DQTR*/ - 0x3DB02000 /*DX2DQSTR*/ - 0x40000000 /*DX3DLLCR*/ - 0xFFFFFFFF /*DX3DQTR*/ - 0x3DB02000 /*DX3DQSTR*/ - >; - status = "okay"; }; }; -- cgit From c7c06fa776b3a553df922259908fad12cfa0e1e8 Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Thu, 25 Nov 2021 11:54:53 +0100 Subject: board: stm32mp1: add support of nor1 device in dfu command Add support of mtd backend for nor1 when this device is present on the board, on STM32MP157C-EV1 for example, as the support of several MTD spi-nor instance are now supported with commit b7f060565e31 ("mtd: spi-nor: allow registering multiple MTDs when DM is enabled"). Signed-off-by: Patrick Delaunay Reviewed-by: Patrice Chotard --- doc/board/st/stm32mp1.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/board/st/stm32mp1.rst b/doc/board/st/stm32mp1.rst index 42bb94148d9..0c5d3a90f04 100644 --- a/doc/board/st/stm32mp1.rst +++ b/doc/board/st/stm32mp1.rst @@ -645,16 +645,18 @@ On EV1 board, booting from SD card, without OP-TEE_:: dev: eMMC alt: 15 name: mmc1_rootfs layout: RAW_ADDR dev: eMMC alt: 16 name: mmc1_userfs layout: RAW_ADDR dev: MTD alt: 17 name: nor0 layout: RAW_ADDR - dev: MTD alt: 18 name: nand0 layout: RAW_ADDR - dev: VIRT alt: 19 name: OTP layout: RAW_ADDR - dev: VIRT alt: 20 name: PMIC layout: RAW_ADDR + dev: MTD alt: 18 name: nor1 layout: RAW_ADDR + dev: MTD alt: 19 name: nand0 layout: RAW_ADDR + dev: VIRT alt: 20 name: OTP layout: RAW_ADDR + dev: VIRT alt: 21 name: PMIC layout: RAW_ADDR All the supported device are exported for dfu-util tool:: $> dfu-util -l - Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=20, name="PMIC", serial="002700333338511934383330" - Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=19, name="OTP", serial="002700333338511934383330" - Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=18, name="nand0", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=21, name="PMIC", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=20, name="OTP", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=19, name="nand0", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=18, name="nor1", serial="002700333338511934383330" Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=17, name="nor0", serial="002700333338511934383330" Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=16, name="mmc1_userfs", serial="002700333338511934383330" Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=15, name="mmc1_rootfs", serial="002700333338511934383330" @@ -705,12 +707,12 @@ You can update the boot device: When the board is booting for nor0 or nand0, only the MTD partition on the boot devices are available, for example: -- NOR (nor0 = alt 20) & NAND (nand0 = alt 26) :: +- NOR (nor0 = alt 20, nor1 = alt 26) & NAND (nand0 = alt 27) : $> dfu-util -d 0483:5720 -a 21 -D tf-a-stm32mp157c-ev1.stm32 $> dfu-util -d 0483:5720 -a 22 -D tf-a-stm32mp157c-ev1.stm32 $> dfu-util -d 0483:5720 -a 23 -D fip-stm32mp157c-ev1.bin - $> dfu-util -d 0483:5720 -a 27 -D st-image-weston-openstlinux-weston-stm32mp1_nand_4_256_multivolume.ubi + $> dfu-util -d 0483:5720 -a 28 -D st-image-weston-openstlinux-weston-stm32mp1_nand_4_256_multivolume.ubi - NAND (nand0 = alt 21):: -- cgit 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') 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 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') 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 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') 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 From b4a0b76585cdba396c6d7fd2e3858821a3355f34 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 21 Dec 2021 09:00:44 +0100 Subject: doc: remove duplicate page inclusion doc/usage/index.rst in branch origin/next includes usage/environment twice. Remove the duplicate entry. Signed-off-by: Heinrich Schuchardt --- doc/usage/index.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'doc') diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 3905540735c..33761af96af 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -11,7 +11,6 @@ Use U-Boot netconsole partitions cmdline - environment Shell commands -------------- -- cgit From 6d7636c946b85390a984402c0422f6270a45befd Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 16 Dec 2021 20:59:08 -0700 Subject: arm: qemu: Mention -nographic in the docs Without this option QEMU appears to hang. Add it to avoid confusion. Signed-off-by: Simon Glass Reviewed-by: Heinrich Schuchardt --- doc/board/emulation/qemu-arm.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst index 7c24e294100..23abe0964d2 100644 --- a/doc/board/emulation/qemu-arm.rst +++ b/doc/board/emulation/qemu-arm.rst @@ -41,14 +41,15 @@ The minimal QEMU command line to get U-Boot up and running is: - For ARM:: - qemu-system-arm -machine virt -bios u-boot.bin + qemu-system-arm -machine virt -nographic -bios u-boot.bin - For AArch64:: - qemu-system-aarch64 -machine virt -cpu cortex-a57 -bios u-boot.bin + qemu-system-aarch64 -machine virt -nographic -cpu cortex-a57 -bios u-boot.bin Note that for some odd reason qemu-system-aarch64 needs to be explicitly -told to use a 64-bit CPU or it will boot in 32-bit mode. +told to use a 64-bit CPU or it will boot in 32-bit mode. The -nographic argument +ensures that output appears on the terminal. Use Ctrl-A X to quit. Additional persistent U-boot environment support can be added as follows: -- cgit 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/board/emulation/qemu-arm.rst | 3 +++ doc/board/emulation/qemu-riscv.rst | 3 +++ doc/develop/devicetree/dt_qemu.rst | 48 ++++++++++++++++++++++++++++++++++++++ doc/develop/devicetree/index.rst | 1 + 4 files changed, 55 insertions(+) create mode 100644 doc/develop/devicetree/dt_qemu.rst (limited to 'doc') diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst index 23abe0964d2..16f66388eb1 100644 --- a/doc/board/emulation/qemu-arm.rst +++ b/doc/board/emulation/qemu-arm.rst @@ -21,6 +21,9 @@ The 'virt' platform provides the following as the basic functionality: Additionally, a number of optional peripherals can be added to the PCI bus. +See :doc:`../../develop/devicetree/dt_qemu` for information on how to see +the devicetree actually generated by QEMU. + Building U-Boot --------------- Set the CROSS_COMPILE environment variable as usual, and run: diff --git a/doc/board/emulation/qemu-riscv.rst b/doc/board/emulation/qemu-riscv.rst index 4b8e104a215..3409fff8117 100644 --- a/doc/board/emulation/qemu-riscv.rst +++ b/doc/board/emulation/qemu-riscv.rst @@ -13,6 +13,9 @@ The QEMU virt machine models a generic RISC-V virtual machine with support for the VirtIO standard networking and block storage devices. It has CLINT, PLIC, 16550A UART devices in addition to VirtIO and it also uses device-tree to pass configuration information to guest software. It implements RISC-V privileged + +See :doc:`../../develop/devicetree/dt_qemu` for information on how to see +the devicetree actually generated by QEMU. architecture spec v1.10. Building U-Boot 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 From ada261f19a7f034109f6f45ff43f9c76c4dbe208 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Sun, 12 Dec 2021 22:12:34 -0500 Subject: Finish converting CONFIG_SYS_FSL_CLK to Kconfig This converts the following to Kconfig: CONFIG_SYS_FSL_CLK We move the exiting option to common/Kconfig near the other options to control the contents of board_init_f() and note that this is a legacy option. We further restrict this to where the call is going to be non-empty, for the SoCs that had only been using this for some MMC-related clocks. Signed-off-by: Tom Rini --- doc/README.fsl-clk | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 doc/README.fsl-clk (limited to 'doc') diff --git a/doc/README.fsl-clk b/doc/README.fsl-clk deleted file mode 100644 index 3a9927f0793..00000000000 --- a/doc/README.fsl-clk +++ /dev/null @@ -1,5 +0,0 @@ -Freescale system clock options - - - CONFIG_SYS_FSL_CLK - Enable to call get_clocks() in board_init_f() for - non-PPC platforms. -- cgit From eaaa5fbbe421c75dbf2319615f95e0484b330b87 Mon Sep 17 00:00:00 2001 From: Andre Przywara Date: Mon, 27 Dec 2021 15:07:36 +0000 Subject: sunxi: add board documentation Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards. This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting. Signed-off-by: Andre Przywara Reviewed-by: Heinrich Schuchardt --- doc/board/allwinner/index.rst | 9 ++ doc/board/allwinner/sunxi.rst | 319 ++++++++++++++++++++++++++++++++++++++++++ doc/board/index.rst | 1 + 3 files changed, 329 insertions(+) create mode 100644 doc/board/allwinner/index.rst create mode 100644 doc/board/allwinner/sunxi.rst (limited to 'doc') diff --git a/doc/board/allwinner/index.rst b/doc/board/allwinner/index.rst new file mode 100644 index 00000000000..7352ccd5c0a --- /dev/null +++ b/doc/board/allwinner/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Allwinner (sunxi) boards +======================== + +.. toctree:: + :maxdepth: 2 + + sunxi diff --git a/doc/board/allwinner/sunxi.rst b/doc/board/allwinner/sunxi.rst new file mode 100644 index 00000000000..797222d8d34 --- /dev/null +++ b/doc/board/allwinner/sunxi.rst @@ -0,0 +1,319 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2021 Arm Ltd. + +Allwinner SoC based boards +========================== +For boards using an Allwinner ARM based SoC ("sunxi"), the U-Boot build +system generates a single integrated image file: ``u-boot-sunxi-with-spl.bin.`` +This file can be used on SD cards, eMMC devices, SPI flash and for the +USB-OTG based boot method (FEL). To build this file: + +* For 64-bit SoCs, build Trusted Firmware (TF-A, formerly known as ATF) first, + you will need its ``bl31.bin``. See below for more details. +* Optionally on 64-bit SoCs, build the `crust`_ management processor firmware, + you will need its ``scp.bin``. See below for more details. +* Build U-Boot:: + + $ export BL31=/path/to/bl31.bin # required for 64-bit SoCs + $ export SCP=/path/to/scp.bin # optional for some 64-bit SoCs + $ make _defconfig + $ make +* Transfer to an (micro)SD card (see below for more details):: + + $ sudo dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=8k seek=1 +* Boot and enjoy! + +.. note:: + The traditional SD card location the Allwinner BootROM loads from is 8KB + (sector 16). This works fine with the old MBR partitioning scheme, which most + SD cards come formatted with. However this is in the middle of a potential + GPT partition table, which will become invalid in this step. Newer SoCs + (starting with the H3 from late 2014) also support booting from 128KB, which + is beyond even a GPT and thus a safer location. + +For more details, and alternative boot locations or installations, see below. + +Building Arm Trusted Firmware (TF-A) +------------------------------------ +Boards using a 64-bit Soc (A64, H5, H6, H616, R329) require the BL31 stage of +the `Arm Trusted Firmware-A`_ firmware. This provides the reference +implementation of secure software for Armv8-A, offering PSCI and SMCCC +services. Allwinner support is fully mainlined. To build bl31.bin:: + + $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + $ cd trusted-firmware-a + $ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_a64 DEBUG=1 + $ export BL31=$(pwd)/build/sun50i_a64/debug/bl31.bin + +The target platform (``PLAT=``) for A64 and H5 SoCs is sun50i_a64, for the H6 +sun50i_h6, for the H616 sun50i_h616, and for the R329 sun50i_r329. Use:: + + $ find plat/allwinner -name platform.mk + +to find all supported platforms. TF-A's `docs/plat/allwinner.rst`_ contains +more information and lists some build options. + +Building the Crust management processor firmware +------------------------------------------------ +For some SoCs and boards, the integrated OpenRISC management controller can +be used to provide power management services, foremost suspend to RAM. +There is a community supported Open Source implementation called `crust`_, +which runs on most SoCs featuring a management controller. + +This firmware part is optional, setting the SCP environment variable to +/dev/null avoids the warning message when building without one. + +To build crust's scp.bin, you need an OpenRISC (or1k) cross compiler, then:: + + $ git clone https://github.com/crust-firmware/crust.git + $ cd crust + $ make _defconfig + $ make CROSS_COMPILE=or1k-none-elf- scp + $ export SCP=$(pwd)/build/scp/scp.bin + +Find a list of supported board configurations in the `configs/`_ directory. +The `crust README`_ has more information about the building process, including +information about where to get OpenRISC cross compilers. + +Building the U-Boot image +------------------------- +Find the U-Boot defconfig file for your board first. Those files live in +the ``configs/`` directory; you can grep for the stub name of the devicetree +file, if you know that, or for the SoC name to find the right version:: + + $ git grep -l MACH_SUN8I_H3 configs + $ git grep -l sun50i-h6-orangepi-3 configs + +The `linux-sunxi`_ wiki also lists the name of the defconfig file in the +respective board page. Then use this defconfig file to create the .config +file, and build the image:: + + $ make _defconfig + $ make + +For 64-bit boards, this requires either the BL31 environment variable to be +set (as shown above in the TF-A build example), or it to be supplied on the +build command line:: + + $ make BL31=/src/tf-a.git/build/sun50i_h616/debug/bl31.bin + +The same applies to the (optional) SCP firmware. + +The file containing everything you need is called ``u-boot-sunxi-with-spl.bin``, +you will find it in the root folder of your U-Boot (build) tree. Except for +raw NAND flash devices this very same file can be used for any boot source. +It will contain the SPL image, fitted with the proper signature recognised by +the BROM, and the required checksum. Also it will contain at least U-Boot +proper, either wrapped in the legacy U-Boot image format, or in a FIT image. +The board's devicetree is also included, either appended to the U-Boot proper +image, or contained in the FIT image. If required by the SoC, this FIT file will +also include the other firmware images. + +Installing U-Boot +----------------- + +Installing on a (micro-) SD card +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +All Allwinner SoCs will try to find a boot image at sector 16 (8KB) of +an SD card, connected to the first MMC controller. To transfer the generated +image to an SD card, from any Linux device (including the board itself) with +an (micro-)SD card reader, type:: + + $ sudo dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=1k seek=8 + +``/dev/sdx`` needs to be replaced with the block device name of the SD card +reader. On some machines this could be ``/dev/mmcblkX``. +Newer SoCs (starting from the H3 from 2014, and including all ARM64 SoCs), +also look at sector 256 (128KB) for the signature (after having checked the +8KB location). Installing the firmware there has the advantage of not +overlapping with a GPT partition table. Simply replace the "``seek=8``" above +with "``seek=128``". + +You can also use an existing (mainline) U-Boot to write to the SD card. Load +the generated U-Boot image somewhere into DRAM (via ``ext4load``, ``fatload``, +or ``tftpboot``), then write to MMC device 0:: + + => fatload mmc 0:1 $kernel_addr_r u-boot-sunxi-with-spl.bin + => mmc dev 0 + => mmc write $kernel_addr_r 0x10 0x7f0 + +To use the alternative boot location on newer SoCs:: + + => mmc write $kernel_addr_r 0x100 0x700 + +Installing on eMMC (on-board flash memory) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Some boards have a soldered eMMC chip, some other boards have an eMMC socket +to receive an optional eMMC module. U-Boot can be installed to those chips, +to boot without an SD card inserted. The Boot-ROM can boot either from the +regular user data partition, or from one of the separate eMMC boot partitions. +U-Boot can be installed either from a running Linux instance on the device, +from a running (mainline) U-Boot, or via an adapter for the (removable) +eMMC module. + +Installing on an eMMC user data partition from Linux +```````````````````````````````````````````````````` +If you have a running Linux instance on the device, and have somehow copied +over the image file to that device, you can write the image directly into the +eMMC device from there. +Find the name of the block device file first, it is one of the +``/dev/mmcblk`` devices. eMMC devices typically also list a +``/dev/mmcblkboot0`` partition (see below), this helps you to tell it apart +from the SD card device. +To install onto the user data partition:: + + $ sudo dd if=u-boot-sunxi-with-spl.bin of=/dev/dev/mmcblkX bs=1k seek=8 + +Similar to SD cards, the BROM in newer SoCs (H3 and above) also checks +sector 256 of an eMMC, so you can use "``seek=128``" as well. Having a GPT +on an eMMC device is much more likely than on an SD card, so you should +probably stick to the alternative location, or use one of the boot partitions. + +Installing on an eMMC boot partition from Linux +``````````````````````````````````````````````` +In the following examples, ``/dev/mmcblkX`` needs to be replaced with the block +device name of the eMMC device. The eMMC device can be recognised by also +listing the boot partitions (``/dev/mmcblkXboot0``) in ``/proc/partitions``. + +To allow booting from one of the eMMC boot partitions, this one needs to be +enabled first. This only needs to be done once, as this setting is +persistent, even though the boot partition can be disabled or changed again +any time later:: + + # apt-get install mmc-utils + # mmc bootbus set single_hs x1 x4 /dev/mmcblkX + # mmc bootpart enable 1 1 /dev/mmcblkX + +The first "1" in the last command points to the boot partition number to be +used, typically devices offer two boot partitions. + +By default Linux disables write access to the boot partitions, to prevent +accidental overwrites. You need to disable the write protection (until the +next reboot), then can write the U-Boot image to the *first* sector of the +selected boot partition:: + + # echo 0 > /sys/block/mmcblkXboot0/force_ro + # dd if=u-boot-sunxi-with-spl.bin of=/dev/mmcblkXboot0 bs=1k + +Installing on an eMMC user data partition from U-Boot +````````````````````````````````````````````````````` +You can also write the generated image file to an SD card, boot the device +from there, and burn the very same image to the eMMC device from U-Boot. +The following commands copy the image from the SD card to the eMMC device:: + + => mmc dev 0 + => mmc read $kernel_addr_r 0x10 0x7f0 + => mmc dev 1 + => mmc write $kernel_addr_r 0x10 0x7f0 + +You can also copy an image from the 8K offset of an SD card to the 128K +offset of the eMMC (or any combination), just change the "``0x10 0x7f0``" above +to "``0x100 0x700``", respectively. Of course the image file can be loaded via +any other loading method, including ``fatload``, ``ext4load``, ``tftpboot``. + +Installing on an eMMC boot partition from U-Boot +```````````````````````````````````````````````` +The selected eMMC boot partition needs to be initially enabled first (same +as in Linux above), you can do this from U-Boot with:: + + => mmc dev 1 + => mmc bootbus 1 1 0 0 + => mmc partconf 1 1 1 1 + +The first "1" in both commands denotes the MMC device number. The second "1" +in the partconf command sets the required ``BOOT_ACK`` option, the last two "1"s +selects the active boot partition and the target for the next data access, +respectively. So for the next "``mmc write``" command to address one of the boot +partitions, the last number must either be "1" or "2", "0" would switch (back) +to the normal user data partition. + +Then load the ``u-boot-sunxi-with-spl.bin`` image file into DRAM, either by +reading directly from an SD card or eMMC user data partition, or from a +file system or TFTP (see above), and transfer it to the boot partition:: + + => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin + => mmc write $kernel_addr_r 0 0x7f0 + +After that the device should boot from the selected boot partition, which takes +precedence over booting from the user data partition. + +Installing on SPI flash +^^^^^^^^^^^^^^^^^^^^^^^ +Some devices have a SPI NOR flash chip soldered on the board. If it is +connected to the SPI0 pins on PortC, the BROM can also boot from there. +Typically the SPI flash has the lowest boot priority, so SD card and eMMC +devices will be considered first. + +Installing on SPI flash from Linux +`````````````````````````````````` +If the devicetree enables and describes the SPI flash device, you can access +the SPI flash content from Linux, using the `MTD utils`_:: + + # apt-get install mtd-utils + # mtdinfo + # mtd_debug erase /dev/mtdX 0 0xf0000 + # mtd_debug write /dev/mtdX 0 0xf0000 u-boot-sunxi-with-spl.bin + +``/dev/mtdX`` needs to be replaced with the respective device name, as listed +in the output of ``mtdinfo``. + +Installing on SPI flash from U-Boot +``````````````````````````````````` +If SPI flash driver and command support (``CONFIG_CMD_SF``) is enabled in the +U-Boot configuration, the image file can be installed via U-Boot as well:: + + => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin + => sf probe + => sf erase 0 +0xf0000 + => sf write $kernel_addr_r 0 $filesize + +Installing on SPI flash via USB in FEL mode +``````````````````````````````````````````` +If the device is in FEL mode (see below), the SPI flash can also be written to +with the sunxi-fel utility, via an USB(-OTG) cable from any USB host machine:: + + $ sunxi-fel spiflash-write 0 u-boot-sunxi-with-spl.bin + +Booting via the USB(-OTG) FEL mode +---------------------------------- +If none of the boot locations checked by the BROM contains a medium or valid +signature, the BROM will enter the so-called FEL mode, in which it will +listen to commands from a host on the SoC's USB-OTG interface. Those commands +allow to read from and write to arbitrary memory locations, also to start +execution at any address, which allows to bootstrap a board solely via an +USB cable. Some boards feature a "FEL" or "U-Boot" button, which forces +FEL mode despite a valid boot location being present. The same can be achieved +via a `magic binary`_ on an SD card, which allows to enter FEL mode on any +board. + +To use FEL booting, let the board enter FEL mode, via any of the mentioned +methods (no boot media, FEL button, SD card with FEL binary), then connect +a USB cable to the board's USB OTG port. Some boards (Pine64, TV boxes) don't +have a separate OTG port. In this case mostly one of the USB-A ports is +connected to USB0, and can be used via a non-standard USB-A to USB-A cable. + +Typically there is no on-board indication of FEL mode, other than a new USB +device appearing on the connected host computer. The USB vendor/device ID +is 1f3a:efe8. Mostly this will identify as "sunxi SoC OTG connector in +FEL/flashing mode", but older distributions might still report "Onda +(unverified) V972 tablet in flashing mode". + +The `sunxi_fel`_ tool implements the proprietary BROM protocol, and allows to +bootstrap U-Boot by just providing our venerable u-boot-sunxi-with-spl.bin:: + + $ sudo apt-get install sunxi-tools + $ sunxi-fel uboot u-boot-sunxi-with-spl.bin + +Additional binaries like a kernel, an initial ramdisk or a boot script, can +also be uploaded via FEL, check the Wiki's `FEL page`_ for more details. + +.. _`Arm Trusted Firmware-A`: https://www.trustedfirmware.org/projects/tf-a/ +.. _`docs/plat/allwinner.rst`: https://trustedfirmware-a.readthedocs.io/en/latest/plat/allwinner.html +.. _`crust`: https://github.com/crust-firmware/crust +.. _`configs/`: https://github.com/crust-firmware/crust/tree/master/configs +.. _`crust README`: https://github.com/crust-firmware/crust/blob/master/README.md#building-the-firmware +.. _`linux-sunxi`: https://linux-sunxi.org +.. _`MTD utils`: http://www.linux-mtd.infradead.org/ +.. _`magic binary`: https://github.com/linux-sunxi/sunxi-tools/raw/master/bin/fel-sdboot.sunxi +.. _`sunxi_fel`: https://github.com/linux-sunxi/sunxi-tools +.. _`FEL page`: https://linux-sunxi.org/FEL/USBBoot diff --git a/doc/board/index.rst b/doc/board/index.rst index 13f4db848e7..0a02fec485b 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -9,6 +9,7 @@ Board-specific doc actions/index advantech/index AndesTech/index + allwinner/index amlogic/index apple/index atmel/index -- cgit 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') 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 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') 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 From 6c2f16b3c95a0bb7f5d6f65512dceb0dc75ac00a Mon Sep 17 00:00:00 2001 From: Peter Hoyes Date: Thu, 11 Nov 2021 09:25:59 +0000 Subject: doc: Add documentation for the Arm VExpress64 board configs Create a new documentation section for Arm Ltd boards with a sub-page for the VExpress64 boards (FVP-A and Juno). Signed-off-by: Peter Hoyes Reviewed-by: Andre Przywara --- doc/board/armltd/index.rst | 9 ++++++++ doc/board/armltd/vexpress64.rst | 51 +++++++++++++++++++++++++++++++++++++++++ doc/board/index.rst | 1 + 3 files changed, 61 insertions(+) create mode 100644 doc/board/armltd/index.rst create mode 100644 doc/board/armltd/vexpress64.rst (limited to 'doc') diff --git a/doc/board/armltd/index.rst b/doc/board/armltd/index.rst new file mode 100644 index 00000000000..c20d8a0a26b --- /dev/null +++ b/doc/board/armltd/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Arm Ltd +============= + +.. toctree:: + :maxdepth: 2 + + vexpress64.rst diff --git a/doc/board/armltd/vexpress64.rst b/doc/board/armltd/vexpress64.rst new file mode 100644 index 00000000000..d87b1c38f5b --- /dev/null +++ b/doc/board/armltd/vexpress64.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Arm Versatile Express +===================== + +The vexpress_* board configuration supports the following platforms: + + * FVP_Base_RevC-2xAEMvA + * Juno development board + +Fixed Virtual Platforms +----------------------- + +The Fixed Virtual Platforms (FVP) are complete simulations of an Arm system, +including processor, memory and peripherals. They are set out in a "programmer's +view", which gives a comprehensive model on which to build and test software. + +The supported FVPs are available free of charge and can be downloaded from the +Arm developer site [1]_ (user registration might be required). + +Supported features: + + * GICv3 + * Generic timer + * PL011 UART + +The default configuration assumes that U-Boot is bootstrapped using a suitable +bootloader, such as Trusted Firmware-A [4]_. The u-boot binary can be passed +into the TF-A build: ``make PLAT= all fip BL33=u-boot.bin`` + +The FVPs can be debugged using Arm Development Studio [2]_. + +Juno +---- + +Juno is an Arm development board with the following features: + + * Arm Cortex-A72/A57 and Arm Cortex-A53 in a "big.LITTLE" configuration + * A PCIe Gen2.0 bus with 4 lanes + * 8GB of DRAM + * GICv2 + +More details can be found in the board documentation [3]_. + +References +---------- + +.. [1] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms +.. [2] https://developer.arm.com/tools-and-software/embedded/arm-development-studio +.. [3] https://developer.arm.com/tools-and-software/development-boards/juno-development-board +.. [4] https://trustedfirmware-a.readthedocs.io/ \ No newline at end of file diff --git a/doc/board/index.rst b/doc/board/index.rst index 0a02fec485b..5607e1f9463 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -12,6 +12,7 @@ Board-specific doc allwinner/index amlogic/index apple/index + armltd/index atmel/index congatec/index coreboot/index -- cgit From 17fe55fd6fe9d32270380f574b33ff0bc15bb47e Mon Sep 17 00:00:00 2001 From: Peter Hoyes Date: Thu, 11 Nov 2021 09:26:00 +0000 Subject: vexpress64: Refactor header file to make it easier to add new FVPs Rename from vexpress_aemv8a.h -> vepxress_aemv8.h as new FVPs may not be v8-A. No change in behavior. This is towards future work to enable support for the FVP_BaseR. Signed-off-by: Peter Hoyes Reviewed-by: Andre Przywara --- doc/README.semihosting | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/README.semihosting b/doc/README.semihosting index c019999bedd..f382d0131eb 100644 --- a/doc/README.semihosting +++ b/doc/README.semihosting @@ -25,7 +25,7 @@ or turning on CONFIG_BASE_FVP for the more full featured model. Rather than create a new armv8 board similar to armltd/vexpress64, add semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING and CONFIG_BASE_FVP both set. Also reuse the existing board config file -vexpress_aemv8a.h but differentiate the two models by the presence or +vexpress_aemv8.h but differentiate the two models by the presence or absence of CONFIG_BASE_FVP. This change is tested and works on both the Foundation and Base fastmodel simulators. -- cgit