From 4834bf1bc80a52421d4eff48dd5b7f89faf2d098 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 13 Jun 2023 21:02:01 +0200 Subject: doc: man-page for imxtract Provide a man-page for the imxtract command. Signed-off-by: Heinrich Schuchardt --- doc/usage/cmd/imxtract.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 doc/usage/cmd/imxtract.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/imxtract.rst b/doc/usage/cmd/imxtract.rst new file mode 100644 index 00000000000..eb64b1cefab --- /dev/null +++ b/doc/usage/cmd/imxtract.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +imxtract command +================ + +Synopsis +-------- + +:: + + imxtract addr part [dest] + imxtract addr uname [dest] + +Description +----------- + +The imxtract command is used to extract a part of a multi-image file. + +Two different file formats are supported: + +* FIT images +* legacy U-Boot images + +addr + Address of the multi-image file from which a part shall be extracted + +part + Index (hexadecimal) of the part of a legacy U-Boot image to be extracted + +uname + Name of the part of a FIT image to be extracted + +dest + Destination address (defaults to 0x0) + +The value of environment variable *verify* controls if the hashes and +signatures of FIT images or the check sums of legacy U-Boot images are checked. +To enable checking set *verify* to one of the values *1*, *yes*, *true*. +(Actually only the first letter is checked disregarding the case.) + +To list the parts of an image the *iminfo* command can be used. + +Examples +-------- + +With verify=no incorrect hashes, signatures, or check sums don't stop the +extraction. But correct hashes are still indicated in the output +(here: md5, sha1). + +.. code-block:: console + + => setenv verify no + => imxtract $loadaddr kernel-1 $kernel_addr_r + ## Copying 'kernel-1' subimage from FIT image at 40200000 ... + md5+ sha1+ Loading part 0 ... OK + => + +With verify=yes incorrect hashes, signatures, or check sums stop the extraction. + +.. code-block:: console + + => setenv verify yes + => imxtract $loadaddr kernel-1 $kernel_addr_r + ## Copying 'kernel-1' subimage from FIT image at 40200000 ... + md5 error! + Bad hash value for 'hash-1' hash node in 'kernel-1' image node + Bad Data Hash + => + +Configuration +------------- + +The imxtract command is only available if CONFIG_CMD_XIMG=y. Support for FIT +images requires CONFIG_FIT=y. Support for legacy U-Boot images requires +CONFIG_LEGACY_IMAGE_FORMAT=y. + +Return value +------------ + +On success the return value $? of the command is 0 (true). On failure the +return value is 1 (false). -- cgit v1.2.3 From ed875bdd1b93eb5b65d63fbd6c2bbdd898b8c385 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 16 Jun 2023 17:11:49 +0200 Subject: doc: unbind man-page Provide a man-page for the unbind command. Signed-off-by: Heinrich Schuchardt --- doc/usage/cmd/unbind.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 doc/usage/cmd/unbind.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/unbind.rst b/doc/usage/cmd/unbind.rst new file mode 100644 index 00000000000..594e4f06892 --- /dev/null +++ b/doc/usage/cmd/unbind.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +unbind command +============== + +Synopsis +-------- + +:: + + unbind + unbind + unbind + +Description +----------- + +The unbind command is used to unbind a device from a driver. This makes the +device unavailable in U-Boot. + +node path + path of the device's device-tree node + +class + device class name + +index + index of the device in the device class + +driver + device driver name + +Example +------- + +Given a system with a real time clock device with device path */pl031@9010000* +and using driver rtc-pl031 unbinding and binding of the device is demonstrated +using the three alternative unbind syntaxes. + +.. code-block:: + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + ... + => fdt addr $fdtcontroladdr + Working FDT set to 7ed7fdb0 + => fdt print + / { + interrupt-parent = <0x00008003>; + model = "linux,dummy-virt"; + #size-cells = <0x00000002>; + #address-cells = <0x00000002>; + compatible = "linux,dummy-virt"; + ... + pl031@9010000 { + clock-names = "apb_pclk"; + clocks = <0x00008000>; + interrupts = <0x00000000 0x00000002 0x00000004>; + reg = <0x00000000 0x09010000 0x00000000 0x00001000>; + compatible = "arm,pl031", "arm,primecell"; + }; + ... + } + => unbind /pl031@9010000 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + => unbind /pl031@9010000 + Cannot find a device with path /pl031@9010000 + => bind /pl031@9010000 rtc-pl031 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + => unbind rtc 0 + => bind /pl031@9010000 rtc-pl031 + => unbind rtc 0 rtc-pl031 + +Configuration +------------- + +The unbind command is only available if CONFIG_CMD_BIND=y. + +Return code +----------- + +The return code $? is 0 (true) on success and 1 (false) on failure. -- cgit v1.2.3 From 63e23f239dafc7421d6ea63b16c031b9078db58b Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Wed, 21 Jun 2023 21:24:55 +0200 Subject: doc: bind man-page provide a man-page for the bind command Signed-off-by: Heinrich Schuchardt --- doc/usage/cmd/bind.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 doc/usage/cmd/bind.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/bind.rst b/doc/usage/cmd/bind.rst new file mode 100644 index 00000000000..1a5cffcb723 --- /dev/null +++ b/doc/usage/cmd/bind.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +bind command +============ + +Synopsis +-------- + +:: + + bind + bind + +Description +----------- + +The bind command is used to bind a device to a driver. This makes the +device available in U-Boot. + +While binding to a *node path* typically provides a working device +binding by parent node and driver may lead to a device that is only +partially initialized. + +node path + path of the device's device-tree node + +class + device class name + +index + index of the parent device in the device class + +driver + device driver name + +Example +------- + +Given a system with a real time clock device with device path */pl031@9010000* +and using driver rtc-pl031 unbinding and binding of the device is demonstrated +using the two alternative bind syntaxes. + +.. code-block:: + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + ... + => fdt addr $fdtcontroladdr + Working FDT set to 7ed7fdb0 + => fdt print + / { + interrupt-parent = <0x00008003>; + model = "linux,dummy-virt"; + #size-cells = <0x00000002>; + #address-cells = <0x00000002>; + compatible = "linux,dummy-virt"; + ... + pl031@9010000 { + clock-names = "apb_pclk"; + clocks = <0x00008000>; + interrupts = <0x00000000 0x00000002 0x00000004>; + reg = <0x00000000 0x09010000 0x00000000 0x00001000>; + compatible = "arm,pl031", "arm,primecell"; + }; + ... + } + => unbind /pl031@9010000 + => date + Cannot find RTC: err=-19 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + => bind /pl031@9010000 rtc-pl031 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + => date + Date: 2023-06-22 (Thursday) Time: 15:14:51 + => unbind rtc 0 rtc-pl031 + => bind root 0 rtc-pl031 + => date + Date: 1980-08-19 (Tuesday) Time: 14:45:30 + +Obviously the device is not initialized correctly by the last bind command. + +Configuration +------------- + +The bind command is only available if CONFIG_CMD_BIND=y. + +Return code +----------- + +The return code $? is 0 (true) on success and 1 (false) on failure. -- cgit v1.2.3 From ad29e08b79fd779a758b24106c8148a9c140f025 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 23 Jun 2023 13:22:06 +0100 Subject: doc: Bring in FIT signature files Bring these files into the documentation. Fix 'wtih' and 'it' typos and repeated 'could' while we are here. Signed-off-by: Simon Glass --- doc/usage/cmd/source.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst index 61a45059096..6f5fa285134 100644 --- a/doc/usage/cmd/source.rst +++ b/doc/usage/cmd/source.rst @@ -22,7 +22,7 @@ Two formats for script files exist: * Flat Image Tree (FIT) The benefit of the FIT images is that they can be signed and verifed as -decribed in :download:`signature.txt <../../uImage.FIT/signature.txt>`. +described in :doc:`../fit/signature`. Both formats can be created with the mkimage tool. -- cgit v1.2.3 From d1b6b114432800a83aa12a2ff81d16e0d7a49e6f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 23 Jun 2023 13:22:13 +0100 Subject: doc: Bring in the command-syntax extensions Bring this file into the documentation. For now it is not in the correct format for a command, but it is valid rST. Futher work will improve this. Signed-off-by: Simon Glass --- doc/usage/cmd/bootm.rst | 227 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 doc/usage/cmd/bootm.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/bootm.rst b/doc/usage/cmd/bootm.rst new file mode 100644 index 00000000000..65b7891c8a6 --- /dev/null +++ b/doc/usage/cmd/bootm.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Command syntax extensions for the new uImage format +=================================================== + +Author: Bartlomiej Sieka + +With the introduction of the new uImage format, bootm command (and other +commands as well) have to understand new syntax of the arguments. This is +necessary in order to specify objects contained in the new uImage, on which +bootm has to operate. This note attempts to first summarize bootm usage +scenarios, and then introduces new argument syntax. + + +bootm usage scenarios +--------------------- + +Below is a summary of bootm usage scenarios, focused on booting a PowerPC +Linux kernel. The purpose of the following list is to document a complete list +of supported bootm usages. + +Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way, +i.e., without passing the Flattened Device Tree (FDT), and new way, where the +kernel is passed a pointer to the FDT. The boot method is indicated for each +scenario:: + + 1. bootm boot image at the current address, equivalent to 2,3,8 + +Old uImage:: + + 2. bootm /* single image at */ + 3. bootm /* multi-image at */ + 4. bootm - /* multi-image at */ + 5. bootm /* single image at */ + 6. bootm /* single image at */ + 7. bootm - /* single image at */ + +New uImage:: + + 8. bootm + 9. bootm []: + 10. bootm []#[#]: []: + 12. bootm []: []: []: + 13. bootm []: []: + 14. bootm []: - []: + 15. bootm []: - + +Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at +the current image address. + +- boot method: see cases 2,3,8 + +Ad. 2. Boot kernel image located at . + +- boot method: non-FDT + +Ad. 3. First and second components of the image at are assumed to be a +kernel and a ramdisk, respectively. The kernel is booted with initrd loaded +with the ramdisk from the image. + +- boot method: depends on the number of components at , and on whether + U-Boot is compiled with OF support:: + + ====================================================================== + | 2 components | 3 components| + | (kernel, initrd) | (kernel, initrd, fdt) | + ====================================================================== + #ifdef CONFIG_OF_* | non-FDT | FDT | + #ifndef CONFIG_OF_* | non-FDT | non-FDT | + ====================================================================== + +Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second +component of the multi-image is irrelevant (it can be a dummy, 1-byte file). + +- boot method: see case 3 + +Ad. 5. Boot kernel image located at with initrd loaded with ramdisk +from the image at . + +- boot method: non-FDT + +Ad. 6. is the address of a kernel image, is the address of a +ramdisk image, and is the address of a FDT binary blob. Kernel is +booted with initrd loaded with ramdisk from the image at . + +- boot method: FDT + +Ad. 7. is the address of a kernel image and is the address of +a FDT binary blob. Kernel is booted without initrd. + +- boot method: FDT + +Ad. 8. Image at is assumed to contain a default configuration, which +is booted. + +- boot method: FDT or non-FDT, depending on whether the default configuration + defines FDT + +Ad. 9. Similar to case 2: boot kernel stored in from the image at +address . + +- boot method: non-FDT + +Ad. 10. Boot configuration from the image at . + +- boot method: FDT or non-FDT, depending on whether the configuration given + defines FDT + +Ad. 11. Equivalent to case 5: boot kernel stored in from the image +at with initrd loaded with ramdisk from the image at +. + +- boot method: non-FDT + +Ad. 12. Equivalent to case 6: boot kernel stored in from the image +at with initrd loaded with ramdisk from the image at +, and pass FDT blob from the image at . + +- boot method: FDT + +Ad. 13. Similar to case 12, the difference being that is the address +of FDT binary blob that is to be passed to the kernel. + +- boot method: FDT + +Ad. 14. Equivalent to case 7: boot kernel stored in from the image +at , without initrd, and pass FDT blob from the image at +. + +- boot method: FDT + +Ad. 15. Similar to case 14, the difference being that is the address +of the FDT binary blob that is to be passed to the kernel. + +- boot method: FDT + + +New uImage argument syntax +-------------------------- + +New uImage support introduces two new forms for bootm arguments, with the +following syntax: + +new uImage sub-image specification + : + +new uImage configuration specification + # + +new uImage configuration specification with extra configuration components + #[#[#..]] + +The extra configuration currently is supported only for additional device tree +overlays to apply on the base device tree supplied by the first configuration +unit. + +Examples: + +boot kernel "kernel-1" stored in a new uImage located at 200000:: + + bootm 200000:kernel-1 + +boot configuration "cfg-1" from a new uImage located at 200000:: + + bootm 200000#cfg-1 + +boot configuration "cfg-1" with extra "cfg-2" from a new uImage located +at 200000:: + + bootm 200000#cfg-1#cfg-2 + +boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in +some other new uImage stored at address 800000:: + + bootm 200000:kernel-1 800000:ramdisk-2 + +boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT +"fdt-1", both stored in some other new uImage located at 800000:: + + bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1 + +boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage +at address 200000, with a raw FDT blob stored at address 600000:: + + bootm 200000:kernel-2 200000:ramdisk-2 600000 + +boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the +same new uImage:: + + bootm 200000:kernel-2 - 200000:fdt-1 + + +Note on current image address +----------------------------- + +When bootm is called without arguments, the image at current image address is +booted. The current image address is the address set most recently by a load +command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider +the following commands:: + + tftp 200000 /tftpboot/kernel + bootm + Last command is equivalent to: + bootm 200000 + +In case of the new uImage argument syntax, the address portion of any argument +can be omitted. If is omitted, then it is assumed that image at + should be used. Similarly, when is omitted, it is assumed that +image at should be used. If is omitted, it is assumed that the +current image address is to be used. For example, consider the following +commands:: + + tftp 200000 /tftpboot/uImage + bootm :kernel-1 + Last command is equivalent to: + bootm 200000:kernel-1 + + tftp 200000 /tftpboot/uImage + bootm 400000:kernel-1 :ramdisk-1 + Last command is equivalent to: + bootm 400000:kernel-1 400000:ramdisk-1 + + tftp 200000 /tftpboot/uImage + bootm :kernel-1 400000:ramdisk-1 :fdt-1 + Last command is equivalent to: + bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1 -- cgit v1.2.3 From 35ed599f430bcba2fd2bc14e52e6cb450cd9a10c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 23 Jun 2023 13:22:14 +0100 Subject: doc: Improve documentation for the bootm command Reformat and rewrite the documentation for this command. This is a complicated command, so further improvements are welcome. Signed-off-by: Simon Glass --- doc/usage/cmd/bootm.rst | 327 +++++++++++++++++++++++++++++------------------- 1 file changed, 200 insertions(+), 127 deletions(-) (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/bootm.rst b/doc/usage/cmd/bootm.rst index 65b7891c8a6..a7e5f6ce69a 100644 --- a/doc/usage/cmd/bootm.rst +++ b/doc/usage/cmd/bootm.rst @@ -1,161 +1,267 @@ .. SPDX-License-Identifier: GPL-2.0+ -Command syntax extensions for the new uImage format -=================================================== +bootm command +============= -Author: Bartlomiej Sieka +Synopsis +-------- -With the introduction of the new uImage format, bootm command (and other -commands as well) have to understand new syntax of the arguments. This is -necessary in order to specify objects contained in the new uImage, on which -bootm has to operate. This note attempts to first summarize bootm usage -scenarios, and then introduces new argument syntax. +:: + bootm [fit_addr]#[#extra-conf] + bootm [[fit_addr]:] [[]:] [[]:] -bootm usage scenarios ---------------------- + bootm [[ []] # Legacy boot -Below is a summary of bootm usage scenarios, focused on booting a PowerPC -Linux kernel. The purpose of the following list is to document a complete list -of supported bootm usages. +Description +----------- -Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way, -i.e., without passing the Flattened Device Tree (FDT), and new way, where the -kernel is passed a pointer to the FDT. The boot method is indicated for each -scenario:: +The *bootm* command is used to boot an Operating System. It has a large number +of options depending on what needs to be booted. - 1. bootm boot image at the current address, equivalent to 2,3,8 +Note that the second form supports the first and/or second arguments to be +omitted by using a hyphen '-' instead. -Old uImage:: +fit_addr / fit_addr2 / fit_addr3 + address of FIT to boot, defaults to CONFIG_SYS_LOAD_ADDR. See notes below. - 2. bootm /* single image at */ - 3. bootm /* multi-image at */ - 4. bootm - /* multi-image at */ - 5. bootm /* single image at */ - 6. bootm /* single image at */ - 7. bootm - /* single image at */ +conf + configuration unit to boot (must be preceded by hash '#') -New uImage:: +extra-conf + extra configuration to boot. This is supported only for additional + devicetree overlays to apply on the base device tree supplied by the first + configuration unit. - 8. bootm - 9. bootm []: - 10. bootm []#[#]: []: - 12. bootm []: []: []: - 13. bootm []: []: - 14. bootm []: - []: - 15. bootm []: - +os_subimg + OS sub-image to boot (must be preceded by colon ':') + +rd_subimg + ramdisk sub-image to boot. Use a hyphen '-' if there is no ramdisk but an + FDT is needed. + +fdt_subimg + FDT sub-image to boot + +See below for legacy boot. Booting using :doc:`../fit/index` is recommended. + +Note on current image address +----------------------------- + +When bootm is called without arguments, the image at current image address is +booted. The current image address is the address set most recently by a load +command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, +consider the following commands:: + + tftp 200000 /tftpboot/kernel + bootm + # Last command is equivalent to: + # bootm 200000 + +As shown above, with FIT the address portion of any argument +can be omitted. If is omitted, then it is assumed that image at + should be used. Similarly, when is omitted, it is assumed that +image at should be used. If is omitted, it is assumed that the +current image address is to be used. For example, consider the following +commands:: + + tftp 200000 /tftpboot/uImage + bootm :kernel-1 + # Last command is equivalent to: + # bootm 200000:kernel-1 + + tftp 200000 /tftpboot/uImage + bootm 400000:kernel-1 :ramdisk-1 + # Last command is equivalent to: + # bootm 400000:kernel-1 400000:ramdisk-1 + + tftp 200000 /tftpboot/uImage + bootm :kernel-1 400000:ramdisk-1 :fdt-1 + # Last command is equivalent to: + # bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1 + + +Legacy boot +----------- + +U-Boot supports a legacy image format, enabled by `CONFIG_LEGACY_IMAGE_FORMAT`. +This is not recommended as it is quite limited and insecure. Use +:doc:`../fit/index` instead. It is documented here for old boards which still +use it. + +Arguments are: + +addr1 + address of legacy image to boot. If the image includes a second component + (ramdisk) it is used as well, unless the second parameter is hyphen '-'. + +addr2 + address of legacy image to use as ramdisk -Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at +addr3 + address of legacy image to use as FDT + + +Example syntax +-------------- + +This section provides various examples of possible usage:: + + 1. bootm /* boot image at the current address, equivalent to 2,3,8 */ + +This is equivalent to cases 2, 3 or 8, depending on the type of image at the current image address. -- boot method: see cases 2,3,8 +Boot method: see cases 2,3,8 + +Legacy uImage syntax +~~~~~~~~~~~~~~~~~~~~ -Ad. 2. Boot kernel image located at . +:: + + 2. bootm /* single image at */ -- boot method: non-FDT +Boot kernel image located at . -Ad. 3. First and second components of the image at are assumed to be a +Boot method: non-FDT + +:: + + 3. bootm /* multi-image at */ + +First and second components of the image at are assumed to be a kernel and a ramdisk, respectively. The kernel is booted with initrd loaded with the ramdisk from the image. -- boot method: depends on the number of components at , and on whether - U-Boot is compiled with OF support:: +Boot method: depends on the number of components at , and on whether +U-Boot is compiled with OF support, which it should be. - ====================================================================== - | 2 components | 3 components| - | (kernel, initrd) | (kernel, initrd, fdt) | - ====================================================================== - #ifdef CONFIG_OF_* | non-FDT | FDT | - #ifndef CONFIG_OF_* | non-FDT | non-FDT | - ====================================================================== + ==================== ======================== ======================== + Configuration 2 components 3 components + (kernel, initrd) (kernel, initrd, fdt) + ==================== ======================== ======================== + #ifdef CONFIG_OF_* non-FDT FDT + #ifndef CONFIG_OF_* non-FDT non-FDT + ==================== ======================== ======================== + +:: + + 4. bootm - /* multi-image at */ -Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second +Similar to case 3, but the kernel is booted without initrd. Second component of the multi-image is irrelevant (it can be a dummy, 1-byte file). -- boot method: see case 3 +Boot method: see case 3 -Ad. 5. Boot kernel image located at with initrd loaded with ramdisk +:: + + 5. bootm /* single image at */ + +Boot kernel image located at with initrd loaded with ramdisk from the image at . -- boot method: non-FDT +Boot method: non-FDT + +:: -Ad. 6. is the address of a kernel image, is the address of a + 6. bootm /* single image at */ + + is the address of a kernel image, is the address of a ramdisk image, and is the address of a FDT binary blob. Kernel is booted with initrd loaded with ramdisk from the image at . -- boot method: FDT +Boot method: FDT + +:: + + 7. bootm - /* single image at */ -Ad. 7. is the address of a kernel image and is the address of + is the address of a kernel image and is the address of a FDT binary blob. Kernel is booted without initrd. -- boot method: FDT +Boot method: FDT + +FIT syntax +~~~~~~~~~~ + +:: + + 8. bootm -Ad. 8. Image at is assumed to contain a default configuration, which +Image at is assumed to contain a default configuration, which is booted. -- boot method: FDT or non-FDT, depending on whether the default configuration - defines FDT +Boot method: FDT or non-FDT, depending on whether the default configuration +defines FDT + +:: + + 9. bootm []: -Ad. 9. Similar to case 2: boot kernel stored in from the image at +Similar to case 2: boot kernel stored in from the image at address . -- boot method: non-FDT +Boot method: non-FDT -Ad. 10. Boot configuration from the image at . +:: -- boot method: FDT or non-FDT, depending on whether the configuration given - defines FDT + 10. bootm []#[# from the image at . + +Boot method: FDT or non-FDT, depending on whether the configuration given +defines FDT + +:: -Ad. 11. Equivalent to case 5: boot kernel stored in from the image + 11. bootm []: []: + +Equivalent to case 5: boot kernel stored in from the image at with initrd loaded with ramdisk from the image at . -- boot method: non-FDT +Boot method: non-FDT -Ad. 12. Equivalent to case 6: boot kernel stored in from the image +:: + + 12. bootm []: []: []: + +Equivalent to case 6: boot kernel stored in from the image at with initrd loaded with ramdisk from the image at , and pass FDT blob from the image at . -- boot method: FDT +Boot method: FDT -Ad. 13. Similar to case 12, the difference being that is the address -of FDT binary blob that is to be passed to the kernel. +:: -- boot method: FDT + 13. bootm []: []: -Ad. 14. Equivalent to case 7: boot kernel stored in from the image -at , without initrd, and pass FDT blob from the image at -. +Similar to case 12, the difference being that is the address +of FDT binary blob that is to be passed to the kernel. -- boot method: FDT +Boot method: FDT -Ad. 15. Similar to case 14, the difference being that is the address -of the FDT binary blob that is to be passed to the kernel. +:: -- boot method: FDT + 14. bootm []: - []: +Equivalent to case 7: boot kernel stored in from the image +at , without initrd, and pass FDT blob from the image at +. -New uImage argument syntax --------------------------- +Boot method: FDT -New uImage support introduces two new forms for bootm arguments, with the -following syntax: + 15. bootm []: - -new uImage sub-image specification - : +Similar to case 14, the difference being that is the address +of the FDT binary blob that is to be passed to the kernel. -new uImage configuration specification - # +Boot method: FDT -new uImage configuration specification with extra configuration components - #[#[#..]] -The extra configuration currently is supported only for additional device tree -overlays to apply on the base device tree supplied by the first configuration -unit. -Examples: +Example +------- boot kernel "kernel-1" stored in a new uImage located at 200000:: @@ -190,38 +296,5 @@ same new uImage:: bootm 200000:kernel-2 - 200000:fdt-1 - -Note on current image address ------------------------------ - -When bootm is called without arguments, the image at current image address is -booted. The current image address is the address set most recently by a load -command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider -the following commands:: - - tftp 200000 /tftpboot/kernel - bootm - Last command is equivalent to: - bootm 200000 - -In case of the new uImage argument syntax, the address portion of any argument -can be omitted. If is omitted, then it is assumed that image at - should be used. Similarly, when is omitted, it is assumed that -image at should be used. If is omitted, it is assumed that the -current image address is to be used. For example, consider the following -commands:: - - tftp 200000 /tftpboot/uImage - bootm :kernel-1 - Last command is equivalent to: - bootm 200000:kernel-1 - - tftp 200000 /tftpboot/uImage - bootm 400000:kernel-1 :ramdisk-1 - Last command is equivalent to: - bootm 400000:kernel-1 400000:ramdisk-1 - - tftp 200000 /tftpboot/uImage - bootm :kernel-1 400000:ramdisk-1 :fdt-1 - Last command is equivalent to: - bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1 +.. sectionauthor:: Bartlomiej Sieka +.. sectionauthor:: Simon Glass -- cgit v1.2.3 From 117bcc268317c12261c271b841676a38d28e65c2 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 25 Jun 2023 13:40:23 +0200 Subject: doc: loads man-page Provide a man-page for the loads command. Signed-off-by: Heinrich Schuchardt --- doc/usage/cmd/loads.rst | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 doc/usage/cmd/loads.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/loads.rst b/doc/usage/cmd/loads.rst new file mode 100644 index 00000000000..e4cb063df6d --- /dev/null +++ b/doc/usage/cmd/loads.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +loads command +============= + +Synopsis +-------- + +:: + + loads [offset [baud]] + +Description +----------- + +The loads command is used to transfer a file to the device via the serial line +using the Motorola S-record file format. + +offset + offset added to the addresses in the S-record file + +baud + baud rate to use for download. This parameter is only available if + CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Example +------- + +As example file to be transferred we use a script printing 'hello s-record'. +Here are the commands to create the S-record file: + +.. code-block:: bash + + $ echo 'echo hello s-record' > script.txt + $ mkimage -T script -d script.txt script.scr + Image Name: + Created: Sun Jun 25 10:35:02 2023 + Image Type: PowerPC Linux Script (gzip compressed) + Data Size: 28 Bytes = 0.03 KiB = 0.00 MiB + Load Address: 00000000 + Entry Point: 00000000 + Contents: + Image 0: 20 Bytes = 0.02 KiB = 0.00 MiB + $ srec_cat script.scr -binary -CRLF -Output script.srec + $ echo -e "S9030000FC\r" >> script.srec + $ cat script.srec + S0220000687474703A2F2F737265636F72642E736F75726365666F7267652E6E65742F1D + S1230000270519566D773EB6649815E30000001700000000000000003DE3D97005070601E2 + S12300200000000000000000000000000000000000000000000000000000000000000000BC + S11A00400000000F0000000068656C6C6F20732D7265636F72640A39 + S5030003F9 + S9030000FC + $ + +The load address in the first S1 record is 0x0000. + +The terminal emulation program picocom is invoked with *cat* as the send +command to transfer the file. + +.. code-block:: + + picocom --send-cmd 'cat' --baud 115200 /dev/ttyUSB0 + +After entering the *loads* command the key sequence is used to +let picocom prompt for the file name. Picocom invokes the program *cat* for the +file transfer. The loaded script is executed using the *source* command. + +.. code-block:: + + => loads $scriptaddr + ## Ready for S-Record download ... + + *** file: script.srec + $ cat script.srec + + *** exit status: 0 *** + + ## First Load Addr = 0x4FC00000 + ## Last Load Addr = 0x4FC0005B + ## Total Size = 0x0000005C = 92 Bytes + ## Start Addr = 0x00000000 + => source $scriptaddr + ## Executing script at 4fc00000 + hello s-record + => + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADS=y. The parameter to set the +baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. -- cgit v1.2.3 From cf376808f127272de58ae776d92a6bbb6e8593ce Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 25 Jun 2023 15:14:03 +0200 Subject: doc: saves man-page Provide a man-page for the saves command. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/usage/cmd/saves.rst | 88 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 doc/usage/cmd/saves.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/saves.rst b/doc/usage/cmd/saves.rst new file mode 100644 index 00000000000..5823f883790 --- /dev/null +++ b/doc/usage/cmd/saves.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +saves command +============= + +Synopsis +-------- + +:: + + saves [offset [size [baud]]] + +Description +----------- + +The *saves* command is used to transfer a file from the device via the serial +line using the Motorola S-record file format. + +offset + start address of memory area to save, defaults to 0x0 + +size + size of memory area to save, defaults to 0x0 + +baud + baud rate to use for upload. This parameter is only available if + CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Example +------- + +In the example the *screen* command is used to connect to the U-Boot serial +console. + +In a first screen session a file is loaded from the SD-card and the *saves* +command is invoked. is used to kill the screen session. + +A new screen session is started which logs the output to a file and the + key is hit to start the file output. is issued to kill the +screen session. + +The log file is converted to a binary file using the *srec_cat* command. +A negative offset of -1337982976 (= -0x4c000000) is applied to compensate for +the offset used in the *saves* command. + +.. code-block:: + + $ screen /dev/ttyUSB0 115200 + => echo $scriptaddr + 0x4FC00000 + => load mmc 0:1 $scriptaddr boot.txt + 124 bytes read in 1 ms (121.1 KiB/s) + => saves $scriptaddr $filesize + ## Ready for S-Record upload, press ENTER to proceed ... + Really kill this window [y/n] + $ screen -Logfile out.srec -L /dev/ttyUSB0 115200 + S0030000FC + S3154FC00000736574656E76206175746F6C6F616420AD + S3154FC000106E6F0A646863700A6C6F6164206D6D633E + S3154FC0002020303A3120246664745F616464725F72B3 + S3154FC00030206474620A6C6F6164206D6D6320303AC0 + S3154FC000403120246B65726E656C5F616464725F72DA + S3154FC0005020736E702E6566690A626F6F74656669C6 + S3154FC0006020246B65726E656C5F616464725F7220CB + S3114FC00070246664745F616464725F720A38 + S70500000000FA + ## S-Record upload complete + => + Really kill this window [y/n] + $ srec_cat out.srec -offset -1337982976 -Output out.txt -binary 2>/dev/null + $ cat out.txt + setenv autoload no + dhcp + load mmc 0:1 $fdt_addr_r dtb + load mmc 0:1 $kernel_addr_r snp.efi + bootefi $kernel_addr_r $fdt_addr_r + $ + +Configuration +------------- + +The command is only available if CONFIG_CMD_SAVES=y. The parameter to set the +baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. -- cgit v1.2.3 From 62ac1277fe89ec94ce97a2202f1e3fd708e42474 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 25 Jun 2023 23:22:44 +0200 Subject: doc: fix typo loady in loadb man-page %s/loady/loadb/ Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/usage/cmd/loadb.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/loadb.rst b/doc/usage/cmd/loadb.rst index b37d1d7b596..0464b1f41ce 100644 --- a/doc/usage/cmd/loadb.rst +++ b/doc/usage/cmd/loadb.rst @@ -13,7 +13,7 @@ Synopsis Description ----------- -The loady command is used to transfer a file to the device via the serial line +The loadb command is used to transfer a file to the device via the serial line using the Kermit protocol. The number of transferred bytes is saved in environment variable filesize. -- cgit v1.2.3