diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.fdt-overlays | 114 | ||||
| -rw-r--r-- | doc/board/freescale/b4860qds.rst | 4 | ||||
| -rw-r--r-- | doc/board/sifive/fu540.rst | 19 | ||||
| -rw-r--r-- | doc/usage/base.rst | 23 | ||||
| -rw-r--r-- | doc/usage/fdt_overlays.rst | 134 | ||||
| -rw-r--r-- | doc/usage/index.rst | 3 | ||||
| -rw-r--r-- | doc/usage/pstore.rst | 11 |
7 files changed, 183 insertions, 125 deletions
diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays deleted file mode 100644 index 39139cb850..0000000000 --- a/doc/README.fdt-overlays +++ /dev/null @@ -1,114 +0,0 @@ -U-Boot FDT Overlay usage -============================================= - -Overlays Syntax ---------------- - -Overlays require slightly different syntax compared to traditional overlays. -Please refer to dt-object-internal.txt in the dtc sources for information -regarding the internal format of overlays: -https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt - -Building Overlays ------------------ - -In a nutshell overlays provides a means to manipulate a symbol a previous dtb -or overlay has defined. It requires both the base and all the overlays -to be compiled with the -@ command line switch so that symbol information is -included. - -Note support for -@ option can only be found in dtc version 1.4.4 or newer. -Only version 4.14 or higher of the Linux kernel includes a built in version -of dtc that meets this requirement. - -Building an overlay follows the same process as building a traditional dtb. - -For example: - -base.dts --------- - - /dts-v1/; - / { - foo: foonode { - foo-property; - }; - }; - - $ dtc -@ -I dts -O dtb -o base.dtb base.dts - -bar.dts -------- - - /dts-v1/; - /plugin/; - / { - fragment@1 { - target = <&foo>; - __overlay__ { - overlay-1-property; - bar: barnode { - bar-property; - }; - }; - }; - }; - - $ dtc -@ -I dts -O dtb -o bar.dtb bar.dts - -Ways to Utilize Overlays in U-boot ----------------------------------- - -There are two ways to apply overlays in U-boot. -1. Include and define overlays within a FIT image and have overlays - automatically applied. - -2. Manually load and apply overlays - -The remainder of this document will discuss using overlays via the manual -approach. For information on using overlays as part of a FIT image please see: -doc/uImage.FIT/overlay-fdt-boot.txt - -Manually Loading and Applying Overlays --------------------------------------- - -1. Figure out where to place both the base device tree blob and the -overlay. Make sure you have enough space to grow the base tree without -overlapping anything. - -=> setenv fdtaddr 0x87f00000 -=> setenv fdtovaddr 0x87fc0000 - -2. Load the base blob and overlay blobs - -=> load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb -=> load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtb - -3. Set it as the working fdt tree. - -=> fdtaddr $fdtaddr - -4. Grow it enough so it can 'fit' all the applied overlays - -=> fdt resize 8192 - -5. You are now ready to apply the overlay. - -=> fdt apply $fdtovaddr - -6. Boot system like you would do with a traditional dtb. - -For bootm: - -=> bootm ${kerneladdr} - ${fdtaddr} - -For bootz: - -=> bootz ${kerneladdr} - ${fdtaddr} - -Please note that in case of an error, both the base and overlays are going -to be invalidated, so keep copies to avoid reloading. - -Pantelis Antoniou -pantelis.antoniou@konsulko.com -11/7/2017 diff --git a/doc/board/freescale/b4860qds.rst b/doc/board/freescale/b4860qds.rst index 37d7d08b09..de14d857b9 100644 --- a/doc/board/freescale/b4860qds.rst +++ b/doc/board/freescale/b4860qds.rst @@ -134,7 +134,7 @@ B4860QDS Default Settings ------------------------- Switch Settings ---------------- +^^^^^^^^^^^^^^^ .. code-block:: none @@ -167,7 +167,7 @@ B4420QDS Default Settings ------------------------- Switch Settings ---------------- +^^^^^^^^^^^^^^^ .. code-block:: none diff --git a/doc/board/sifive/fu540.rst b/doc/board/sifive/fu540.rst index 1ce9ab14f5..4e4c852ff3 100644 --- a/doc/board/sifive/fu540.rst +++ b/doc/board/sifive/fu540.rst @@ -12,6 +12,7 @@ of running Linux. Mainline support ---------------- + The support for following drivers are already enabled: 1. SiFive UART Driver. @@ -24,7 +25,7 @@ Booting from MMC using FSBL --------------------------- Building --------- +~~~~~~~~ 1. Add the RISC-V toolchain to your PATH. 2. Setup ARCH & cross compilation environment variable: @@ -37,7 +38,7 @@ Building 4. make Flashing --------- +~~~~~~~~ The current U-Boot port is supported in S-mode only and loaded from DRAM. @@ -63,11 +64,12 @@ copied to the first partition of the sdcard. sudo dd if=<prior_stage_firmware_binary> of=/dev/disk2s1 bs=1024 Booting -------- +~~~~~~~ + Once you plugin the sdcard and power up, you should see the U-Boot prompt. Sample boot log from HiFive Unleashed board -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: none @@ -417,7 +419,7 @@ Booting from MMC using U-Boot SPL --------------------------------- Building --------- +~~~~~~~~ Before building U-Boot SPL, OpenSBI must be built first. OpenSBI can be cloned and built for FU540 as below: @@ -441,7 +443,7 @@ This will generate spl/u-boot-spl.bin and FIT image (u-boot.itb) Flashing --------- +~~~~~~~~ ZSBL loads the U-Boot SPL (u-boot-spl.bin) from a partition with GUID type 5B193300-FC78-40CD-8002-E86C45580B47 @@ -471,11 +473,12 @@ Program the SD card sudo dd if=u-boot.itb of=/dev/sda seek=2082 Booting -------- +~~~~~~~ + Once you plugin the sdcard and power up, you should see the U-Boot prompt. Sample boot log from HiFive Unleashed board -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: none diff --git a/doc/usage/base.rst b/doc/usage/base.rst new file mode 100644 index 0000000000..db9cd4d978 --- /dev/null +++ b/doc/usage/base.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +base command +============ + +Synopsis +-------- + +:: + + base [address] + +Description +----------- + +The *base* command sets or displays the address offset used by the memory +commands *cmp, cp, md, mdc, mm, ms, mw, mwc*. + +All other commands ignore the address defined by *base*. + +address + new base address as hexadecimal number. If no value is provided, the current + value is displayed. diff --git a/doc/usage/fdt_overlays.rst b/doc/usage/fdt_overlays.rst new file mode 100644 index 0000000000..ea39713434 --- /dev/null +++ b/doc/usage/fdt_overlays.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com> + +Device Tree Overlays +==================== + +Overlay Syntax +-------------- + +Device-tree overlays require a slightly different syntax compared to traditional +device-trees. Please refer to dt-object-internal.txt in the device-tree compiler +sources for information regarding the internal format of overlays: +https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt + +Building Overlays +----------------- + +In a nutshell overlays provides a means to manipulate a symbol a previous +device-tree or device-tree overlay has defined. It requires both the base +device-tree and all the overlays to be compiled with the *-@* command line +switch of the device-tree compiler so that symbol information is included. + +Note + Support for *-@* option can only be found in dtc version 1.4.4 or newer. + Only version 4.14 or higher of the Linux kernel includes a built in version + of dtc that meets this requirement. + +Building a binary device-tree overlay follows the same process as building a +traditional binary device-tree. For example: + +**base.dts** + +:: + + /dts-v1/; + / { + foo: foonode { + foo-property; + }; + }; + +.. code-block:: console + + $ dtc -@ -I dts -O dtb -o base.dtb base.dts + +**overlay.dts** + +:: + + /dts-v1/; + /plugin/; + / { + fragment@1 { + target = <&foo>; + __overlay__ { + overlay-1-property; + bar: barnode { + bar-property; + }; + }; + }; + }; + +.. code-block:: console + + $ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts + +Ways to Utilize Overlays in U-Boot +---------------------------------- + +There are two ways to apply overlays in U-Boot. + +* Include and define overlays within a FIT image and have overlays + automatically applied. + +* Manually load and apply overlays + +The remainder of this document will discuss using overlays via the manual +approach. For information on using overlays as part of a FIT image please see: +doc/uImage.FIT/overlay-fdt-boot.txt + +Manually Loading and Applying Overlays +-------------------------------------- + +1. Figure out where to place both the base device tree blob and the + overlay. Make sure you have enough space to grow the base tree without + overlapping anything. + +:: + + => setenv fdtaddr 0x87f00000 + => setenv fdtovaddr 0x87fc0000 + +2. Load the base binary device-tree and the binary device-tree overlay. + +:: + + => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb + => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo + +3. Set the base binary device-tree as the working fdt tree. + +:: + + => fdtaddr $fdtaddr + +4. Grow it enough so it can encompass all applied overlays + +:: + + => fdt resize 8192 + +5. You are now ready to apply the overlay. + +:: + + => fdt apply $fdtovaddr + +6. Boot system like you would do with a traditional dtb. + +For bootm: + +:: + + => bootm ${kerneladdr} - ${fdtaddr} + +For bootz: + +:: + + => bootz ${kerneladdr} - ${fdtaddr} + +Please note that in case of an error, both the base and overlays are going +to be invalidated, so keep copies to avoid reloading. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 5869fba189..6def250766 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -2,7 +2,9 @@ Use U-Boot ========== .. toctree:: + :maxdepth: 1 + fdt_overlays netconsole Shell commands @@ -11,6 +13,7 @@ Shell commands .. toctree:: :maxdepth: 1 + base bootefi bootmenu button diff --git a/doc/usage/pstore.rst b/doc/usage/pstore.rst index 8c4e5274aa..1c8374513a 100644 --- a/doc/usage/pstore.rst +++ b/doc/usage/pstore.rst @@ -1,8 +1,17 @@ .. SPDX-License-Identifier: GPL-2.0+ -PStore command +pstore command ============== +Synopsis +-------- + +:: + + pstore set <addr> <len> [record-size] [console-size] [ftrace-size] [pmsg_size] [ecc-size] + pstore display [record-type] [nb] + pstore save <interface> <dev[:part]> <directory-path> + Design ------ |