From 611e7f860a0fb5c7fe9bad5502a6b01118bfca8b Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 16 Feb 2021 18:20:54 +0100 Subject: doc: Add reference to U-Boot project in conf.py With the last update of conf.py the references to U-Boot where replaced by references to Linux. Fix the project references in the generated documentation. Reported-by: Simon Glass Reported-by: Bin Meng Fixes: 98f01cf7a22e ("doc: update Kernel documentation build system") Signed-off-by: Heinrich Schuchardt --- doc/conf.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'doc') diff --git a/doc/conf.py b/doc/conf.py index 3f456a18f5..eb74b86aef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -147,9 +147,9 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'The Linux Kernel' -copyright = 'The kernel development community' -author = 'The kernel development community' +project = 'Das U-Boot' +copyright = 'The U-Boot development community' +author = 'The U-Boot development community' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -260,7 +260,7 @@ except ImportError: # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +html_logo = '../tools/logos/u-boot_logo.svg' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -340,7 +340,7 @@ html_use_smartypants = False #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'TheLinuxKerneldoc' +htmlhelp_basename = 'TheUBootdoc' # -- Options for LaTeX output --------------------------------------------- @@ -470,6 +470,8 @@ if major == 1 and minor < 6: # author, documentclass [howto, manual, or own class]). # Sorted in alphabetical order latex_documents = [ + ('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual', + 'The U-Boot development community', 'manual'), ] # Add all other index files from Documentation/ subdirectories @@ -483,8 +485,8 @@ for fn in os.listdir('.'): break if not has: latex_documents.append((doc, fn + '.tex', - 'Linux %s Documentation' % fn.capitalize(), - 'The kernel development community', + 'U-Boot %s Documentation' % fn.capitalize(), + 'The U-Boot development community', 'manual')) # The name of an image file (relative to this directory) to place at the top of @@ -513,7 +515,7 @@ for fn in os.listdir('.'): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', + (master_doc, 'dasuboot', 'The U-Boot Documentation', [author], 1) ] @@ -527,8 +529,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', - author, 'TheLinuxKernel', 'One line description of project.', + (master_doc, 'DasUBoot', 'The U-Boot Documentation', + author, 'DasUBoot', 'One line description of project.', 'Miscellaneous'), ] @@ -626,7 +628,7 @@ epub_exclude_files = ['search.html'] # multiple PDF files here actually tries to get the cross-referencing right # *between* PDF files. pdf_documents = [ - ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), + ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'), ] # kernel-doc extension configuration for running Sphinx directly (e.g. by Read -- cgit From 3af8d1c44cc292854c2b87379a4837b86f94744b Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Wed, 17 Feb 2021 08:06:05 +0100 Subject: doc/README.distro: kernel_comp_addr_r Add missing articles and preposition. Signed-off-by: Heinrich Schuchardt --- doc/README.distro | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/README.distro b/doc/README.distro index cc1c41ecb3..c4f041ca71 100644 --- a/doc/README.distro +++ b/doc/README.distro @@ -259,10 +259,10 @@ kernel_addr_r: kernel_comp_addr_r: Optional. This is only required if user wants to boot Linux from a compressed - Image(.gz, .bz2, .lzma, .lzo) using booti command. It represents the location - in RAM where the compressed Image will be decompressed temporarily. Once the - decompression is complete, decompressed data will be moved kernel_addr_r for - booting. + Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the + location in RAM where the compressed Image will be decompressed temporarily. + Once the decompression is complete, the decompressed data will be moved to + kernel_addr_r for booting. kernel_comp_size: Optional. This is only required if user wants to boot Linux from a compressed -- cgit From f2280492974311ba0f1ed14398b57a8db67e3022 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Wed, 17 Feb 2021 12:19:35 +0100 Subject: doc: booti man-page Provide a man-page for the booti command. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/usage/booti.rst | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 115 insertions(+) create mode 100644 doc/usage/booti.rst (limited to 'doc') diff --git a/doc/usage/booti.rst b/doc/usage/booti.rst new file mode 100644 index 0000000000..d631fb571d --- /dev/null +++ b/doc/usage/booti.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +booti command +============= + +Synopsis +-------- + +:: + + booti [ [[:]] []] + +Description +----------- + +The booti command is used to boot a Linux kernel in flat or compressed +'Image' format. Which compressed formats are supported is configurable. + +addr + address of kernel image, defaults to CONFIG_SYS_LOAD_ADDR. + +initrd + address of the initial RAM disk. Use '-' to boot a kernel with a device + tree but without an initial RAM disk. + +size + size of the initial RAM disk. This parameter must be specified for raw + initial RAM disks. + +fdt + address of the device tree. + +To support compressed Image files the following environment variables must be +set: + +kernel_comp_addr_r + start of memory area used for decompression + +kernel_comp_size + size of the compressed file. The value has to be at least the size of + loaded image for decompression to succeed. For the booti command the + maximum decompressed size is 10 times this value. + +Example +------- + +This is the boot log of an Odroid C2 board: + +:: + + => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64 + 27530 bytes read in 7 ms (3.7 MiB/s) + => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64 + 26990448 bytes read in 1175 ms (21.9 MiB/s) + => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64 + 27421776 bytes read in 1209 ms (21.6 MiB/s) + => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Moving Image from 0x8080000 to 0x8200000, end=9c60000 + ## Flattened Device Tree blob at 08008000 + Booting using the fdt blob at 0x8008000 + Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK + Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK + + Starting kernel ... + +The kernel can be compressed with gzip: + +.. code-block:: bash + + cd /boot + gzip -k vmlinuz-5.10.0-3-arm64 + +Here is the boot log for the compressed kernel: + +:: + + => setenv kernel_comp_addr_r 0x50000000 + => setenv kernel_comp_size 0x04000000 + => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64 + 27530 bytes read in 6 ms (4.4 MiB/s) + => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64.gz + 9267730 bytes read in 402 ms (22 MiB/s) + => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64 + 27421776 bytes read in 1181 ms (22.1 MiB/s) + => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Uncompressing Kernel Image + Moving Image from 0x8080000 to 0x8200000, end=9c60000 + ## Flattened Device Tree blob at 08008000 + Booting using the fdt blob at 0x8008000 + Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK + Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK + + Starting kernel ... + +Configuration +------------- + +The booti command is only available if CONFIG_CMD_BOOTI=y. + +Which compression types are supported depends on: + +* CONFIG_BZIP2 +* CONFIG_GZIP +* CONFIG_LZ4 +* CONFIG_LZMA +* CONFIG_LZO +* CONFIG_ZSTD + +Return value +------------ + +Normally this command does not return. If an error occurs, the return value $? +is set to 1 (false). If the operating system returns to U-Boot, the system is +reset. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 5754958d7e..7dca91309b 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -15,6 +15,7 @@ Shell commands base bootefi + booti bootmenu button conitrace -- cgit From d46bee8c2d2494e5cff95d865845d497b4897787 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 20 Feb 2021 10:00:19 +0100 Subject: doc: qfw man-page Provide a man-page for the qfw command. Signed-off-by: Heinrich Schuchardt --- doc/usage/index.rst | 1 + doc/usage/qfw.rst | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 doc/usage/qfw.rst (limited to 'doc') diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 7dca91309b..a8842bf9fb 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -28,5 +28,6 @@ Shell commands loady mbr pstore + qfw sbi true diff --git a/doc/usage/qfw.rst b/doc/usage/qfw.rst new file mode 100644 index 0000000000..87463e1e5b --- /dev/null +++ b/doc/usage/qfw.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +qfw command +=========== + +Synopsis +-------- + +:: + + qfw list + qfw cpus + qfw load [kernel_addr [initrd_addr]] + +Description +----------- + +The *qfw* command is used to retrieve information form the QEMU firmware. + +The *qfw list* sub-command displays the QEMU firmware files. + +The *qfw cpus* sub-command displays the available CPUs. + +The *qfw load* command is used to load a kernel and an initial RAM disk. + +kernel_addr + address to which the file specified by the -kernel parameter of QEMU shall + be loaded. Defaults to environment variable *loadaddr* and further to + the value of *CONFIG_LOADADDR*. + +initrd_addr + address to which the file specified by the -initrd parameter of QEMU shall + be loaded. Defaults to environment variable *ramdiskaddr* and further to + the value of *CONFIG_RAMDISK_ADDR*. + +Examples +-------- + +QEMU firmware files are listed via the *qfw list* command: + +:: + + => qfw list + etc/boot-fail-wait + etc/smbios/smbios-tables + etc/smbios/smbios-anchor + etc/e820 + genroms/kvmvapic.bin + genroms/linuxboot.bin + etc/system-states + etc/acpi/tables + etc/table-loader + etc/tpm/log + etc/acpi/rsdp + bootorder + +The available CPUs can be shown via the *qfw cpus* command: + +:: + + => qfw cpu + 2 cpu(s) online + +The *-kernel* and *-initrd* parameters allow to specify a kernel and an +initial RAM disk for QEMU: + +.. code-block:: bash + + $ qemu-system-x86_64 -machine pc-i440fx-2.5 -bios u-boot.rom -m 1G \ + -nographic -kernel vmlinuz -initrd initrd + +Now the kernel and the initial RAM disk can be loaded to the U-Boot memory via +the *qfw load* command and booted thereafter. + +:: + + => qfw load ${kernel_addr_r} ${ramdisk_addr_r} + loading kernel to address 0000000001000000 size 5048f0 initrd 0000000004000000 size 3c94891 + => zboot 1000000 5048f0 4000000 3c94891 + Valid Boot Flag + Magic signature found + Linux kernel version 4.19.0-14-amd64 (debian-kernel@lists.debian.org) #1 SMP Debian 4.19.171-2 (2021-01-30) + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5260160 bytes) + +Configuration +------------- + +The qfw command is only available if CONFIG_CMD_QFW=y. -- cgit