From c8fe916c91a125492244f9d9126bc05efaa2320b Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Thu, 18 Jul 2019 00:33:46 -0700 Subject: doc: Move existing rst files into api sub-directory Currently the Sphinx doc only contains API descriptions of several U-Boot subsystems. For future extension, group these existing docs into an API sub-directory. Signed-off-by: Bin Meng Reviewed-by: Heinrich Schuchardt --- doc/api/efi.rst | 105 +++++++++++++++++++++++++++++++++++++++++++++++ doc/api/index.rst | 11 +++++ doc/api/linker_lists.rst | 100 ++++++++++++++++++++++++++++++++++++++++++++ doc/api/serial.rst | 7 ++++ doc/efi.rst | 105 ----------------------------------------------- doc/index.rst | 14 +++++-- doc/linker_lists.rst | 100 -------------------------------------------- doc/serial.rst | 7 ---- 8 files changed, 234 insertions(+), 215 deletions(-) create mode 100644 doc/api/efi.rst create mode 100644 doc/api/index.rst create mode 100644 doc/api/linker_lists.rst create mode 100644 doc/api/serial.rst delete mode 100644 doc/efi.rst delete mode 100644 doc/linker_lists.rst delete mode 100644 doc/serial.rst (limited to 'doc') diff --git a/doc/api/efi.rst b/doc/api/efi.rst new file mode 100644 index 0000000..39e2dba --- /dev/null +++ b/doc/api/efi.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +UEFI subsystem +============== + +Lauching UEFI images +-------------------- + +Bootefi command +~~~~~~~~~~~~~~~ + +The bootefi command is used to start UEFI applications or to install UEFI +drivers. It takes two parameters + + bootefi [fdt address] + +* image address - the memory address of the UEFI binary +* fdt address - the memory address of the flattened device tree + +The environment variable 'bootargs' is passed as load options in the UEFI system +table. The Linux kernel EFI stub uses the load options as command line +arguments. + +.. kernel-doc:: cmd/bootefi.c + :internal: + +Boot manager +~~~~~~~~~~~~ + +The UEFI specification foresees to define boot entries and boot sequence via UEFI +variables. Booting according to these variables is possible via + + bootefi bootmgr [fdt address] + +* fdt address - the memory address of the flattened device tree + +The relevant variables are: + +* Boot0000-BootFFFF define boot entries +* BootNext specifies next boot option to be booted +* BootOrder specifies in which sequence the boot options shall be tried if + BootNext is not defined or booting via BootNext fails + +.. kernel-doc:: lib/efi_loader/efi_bootmgr.c + :internal: + +Efidebug command +~~~~~~~~~~~~~~~~ + +The efidebug command is used to set and display boot options as well as to +display information about internal data of the UEFI subsystem (devices, +drivers, handles, loaded images, and the memory map). + +.. kernel-doc:: cmd/efidebug.c + :internal: + +Initialization of the UEFI sub-system +------------------------------------- + +.. kernel-doc:: lib/efi_loader/efi_setup.c + :internal: + +Boot services +------------- + +.. kernel-doc:: lib/efi_loader/efi_boottime.c + :internal: + +Image relocation +~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_image_loader.c + :internal: + +Memory services +~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_memory.c + :internal: + +Runtime services +---------------- + +.. kernel-doc:: lib/efi_loader/efi_runtime.c + :internal: + +Variable services +~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_variable.c + :internal: + +UEFI drivers +------------ + +UEFI driver uclass +~~~~~~~~~~~~~~~~~~ +.. kernel-doc:: lib/efi_driver/efi_uclass.c + :internal: + +Block device driver +~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_driver/efi_block_device.c + :internal: diff --git a/doc/api/index.rst b/doc/api/index.rst new file mode 100644 index 0000000..d484c06 --- /dev/null +++ b/doc/api/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot API documentation +======================== + +.. toctree:: + :maxdepth: 2 + + efi + linker_lists + serial diff --git a/doc/api/linker_lists.rst b/doc/api/linker_lists.rst new file mode 100644 index 0000000..72f514e --- /dev/null +++ b/doc/api/linker_lists.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Linker-Generated Arrays +======================= + +A linker list is constructed by grouping together linker input +sections, each containing one entry of the list. Each input section +contains a constant initialized variable which holds the entry's +content. Linker list input sections are constructed from the list +and entry names, plus a prefix which allows grouping all lists +together. Assuming _list and _entry are the list and entry names, +then the corresponding input section name is + +:: + + .u_boot_list_ + 2_ + @_list + _2_ + @_entry + +and the C variable name is + +:: + + _u_boot_list + _2_ + @_list + _2_ + @_entry + +This ensures uniqueness for both input section and C variable name. + +Note that the names differ only in the first character, "." for the +section and "_" for the variable, so that the linker cannot confuse +section and symbol names. From now on, both names will be referred +to as + +:: + + %u_boot_list_ + 2_ + @_list + _2_ + @_entry + +Entry variables need never be referred to directly. + +The naming scheme for input sections allows grouping all linker lists +into a single linker output section and grouping all entries for a +single list. + +Note the two '_2_' constant components in the names: their presence +allows putting a start and end symbols around a list, by mapping +these symbols to sections names with components "1" (before) and +"3" (after) instead of "2" (within). +Start and end symbols for a list can generally be defined as + +:: + + %u_boot_list_2_ + @_list + _1_... + %u_boot_list_2_ + @_list + _3_... + +Start and end symbols for the whole of the linker lists area can be +defined as + +:: + + %u_boot_list_1_... + %u_boot_list_3_... + +Here is an example of the sorted sections which result from a list +"array" made up of three entries : "first", "second" and "third", +iterated at least once. + +:: + + .u_boot_list_2_array_1 + .u_boot_list_2_array_2_first + .u_boot_list_2_array_2_second + .u_boot_list_2_array_2_third + .u_boot_list_2_array_3 + +If lists must be divided into sublists (e.g. for iterating only on +part of a list), one can simply give the list a name of the form +'outer_2_inner', where 'outer' is the global list name and 'inner' +is the sub-list name. Iterators for the whole list should use the +global list name ("outer"); iterators for only a sub-list should use +the full sub-list name ("outer_2_inner"). + +Here is an example of the sections generated from a global list +named "drivers", two sub-lists named "i2c" and "pci", and iterators +defined for the whole list and each sub-list: + +:: + + %u_boot_list_2_drivers_1 + %u_boot_list_2_drivers_2_i2c_1 + %u_boot_list_2_drivers_2_i2c_2_first + %u_boot_list_2_drivers_2_i2c_2_first + %u_boot_list_2_drivers_2_i2c_2_second + %u_boot_list_2_drivers_2_i2c_2_third + %u_boot_list_2_drivers_2_i2c_3 + %u_boot_list_2_drivers_2_pci_1 + %u_boot_list_2_drivers_2_pci_2_first + %u_boot_list_2_drivers_2_pci_2_second + %u_boot_list_2_drivers_2_pci_2_third + %u_boot_list_2_drivers_2_pci_3 + %u_boot_list_2_drivers_3 + +.. kernel-doc:: include/linker_lists.h + :internal: diff --git a/doc/api/serial.rst b/doc/api/serial.rst new file mode 100644 index 0000000..ed34e59 --- /dev/null +++ b/doc/api/serial.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Serial system +============= + +.. kernel-doc:: drivers/serial/serial.c + :internal: diff --git a/doc/efi.rst b/doc/efi.rst deleted file mode 100644 index 39e2dba..0000000 --- a/doc/efi.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -UEFI subsystem -============== - -Lauching UEFI images --------------------- - -Bootefi command -~~~~~~~~~~~~~~~ - -The bootefi command is used to start UEFI applications or to install UEFI -drivers. It takes two parameters - - bootefi [fdt address] - -* image address - the memory address of the UEFI binary -* fdt address - the memory address of the flattened device tree - -The environment variable 'bootargs' is passed as load options in the UEFI system -table. The Linux kernel EFI stub uses the load options as command line -arguments. - -.. kernel-doc:: cmd/bootefi.c - :internal: - -Boot manager -~~~~~~~~~~~~ - -The UEFI specification foresees to define boot entries and boot sequence via UEFI -variables. Booting according to these variables is possible via - - bootefi bootmgr [fdt address] - -* fdt address - the memory address of the flattened device tree - -The relevant variables are: - -* Boot0000-BootFFFF define boot entries -* BootNext specifies next boot option to be booted -* BootOrder specifies in which sequence the boot options shall be tried if - BootNext is not defined or booting via BootNext fails - -.. kernel-doc:: lib/efi_loader/efi_bootmgr.c - :internal: - -Efidebug command -~~~~~~~~~~~~~~~~ - -The efidebug command is used to set and display boot options as well as to -display information about internal data of the UEFI subsystem (devices, -drivers, handles, loaded images, and the memory map). - -.. kernel-doc:: cmd/efidebug.c - :internal: - -Initialization of the UEFI sub-system -------------------------------------- - -.. kernel-doc:: lib/efi_loader/efi_setup.c - :internal: - -Boot services -------------- - -.. kernel-doc:: lib/efi_loader/efi_boottime.c - :internal: - -Image relocation -~~~~~~~~~~~~~~~~ - -.. kernel-doc:: lib/efi_loader/efi_image_loader.c - :internal: - -Memory services -~~~~~~~~~~~~~~~ - -.. kernel-doc:: lib/efi_loader/efi_memory.c - :internal: - -Runtime services ----------------- - -.. kernel-doc:: lib/efi_loader/efi_runtime.c - :internal: - -Variable services -~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: lib/efi_loader/efi_variable.c - :internal: - -UEFI drivers ------------- - -UEFI driver uclass -~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: lib/efi_driver/efi_uclass.c - :internal: - -Block device driver -~~~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: lib/efi_driver/efi_block_device.c - :internal: diff --git a/doc/index.rst b/doc/index.rst index 0353c10..1946d09 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,8 +4,16 @@ U-Boot Developer Manual ####################### +U-Boot API documentation +------------------------ + +These books get into the details of how specific U-Boot subsystems work +from the point of view of a U-Boot developer. Much of the information here +is taken directly from the U-Boot source, with supplemental material added +as needed (or at least as we managed to add it - probably *not* all that is +needed). + .. toctree:: + :maxdepth: 2 - efi - linker_lists - serial + api/index diff --git a/doc/linker_lists.rst b/doc/linker_lists.rst deleted file mode 100644 index 72f514e..0000000 --- a/doc/linker_lists.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -Linker-Generated Arrays -======================= - -A linker list is constructed by grouping together linker input -sections, each containing one entry of the list. Each input section -contains a constant initialized variable which holds the entry's -content. Linker list input sections are constructed from the list -and entry names, plus a prefix which allows grouping all lists -together. Assuming _list and _entry are the list and entry names, -then the corresponding input section name is - -:: - - .u_boot_list_ + 2_ + @_list + _2_ + @_entry - -and the C variable name is - -:: - - _u_boot_list + _2_ + @_list + _2_ + @_entry - -This ensures uniqueness for both input section and C variable name. - -Note that the names differ only in the first character, "." for the -section and "_" for the variable, so that the linker cannot confuse -section and symbol names. From now on, both names will be referred -to as - -:: - - %u_boot_list_ + 2_ + @_list + _2_ + @_entry - -Entry variables need never be referred to directly. - -The naming scheme for input sections allows grouping all linker lists -into a single linker output section and grouping all entries for a -single list. - -Note the two '_2_' constant components in the names: their presence -allows putting a start and end symbols around a list, by mapping -these symbols to sections names with components "1" (before) and -"3" (after) instead of "2" (within). -Start and end symbols for a list can generally be defined as - -:: - - %u_boot_list_2_ + @_list + _1_... - %u_boot_list_2_ + @_list + _3_... - -Start and end symbols for the whole of the linker lists area can be -defined as - -:: - - %u_boot_list_1_... - %u_boot_list_3_... - -Here is an example of the sorted sections which result from a list -"array" made up of three entries : "first", "second" and "third", -iterated at least once. - -:: - - .u_boot_list_2_array_1 - .u_boot_list_2_array_2_first - .u_boot_list_2_array_2_second - .u_boot_list_2_array_2_third - .u_boot_list_2_array_3 - -If lists must be divided into sublists (e.g. for iterating only on -part of a list), one can simply give the list a name of the form -'outer_2_inner', where 'outer' is the global list name and 'inner' -is the sub-list name. Iterators for the whole list should use the -global list name ("outer"); iterators for only a sub-list should use -the full sub-list name ("outer_2_inner"). - -Here is an example of the sections generated from a global list -named "drivers", two sub-lists named "i2c" and "pci", and iterators -defined for the whole list and each sub-list: - -:: - - %u_boot_list_2_drivers_1 - %u_boot_list_2_drivers_2_i2c_1 - %u_boot_list_2_drivers_2_i2c_2_first - %u_boot_list_2_drivers_2_i2c_2_first - %u_boot_list_2_drivers_2_i2c_2_second - %u_boot_list_2_drivers_2_i2c_2_third - %u_boot_list_2_drivers_2_i2c_3 - %u_boot_list_2_drivers_2_pci_1 - %u_boot_list_2_drivers_2_pci_2_first - %u_boot_list_2_drivers_2_pci_2_second - %u_boot_list_2_drivers_2_pci_2_third - %u_boot_list_2_drivers_2_pci_3 - %u_boot_list_2_drivers_3 - -.. kernel-doc:: include/linker_lists.h - :internal: diff --git a/doc/serial.rst b/doc/serial.rst deleted file mode 100644 index ed34e59..0000000 --- a/doc/serial.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -Serial system -============= - -.. kernel-doc:: drivers/serial/serial.c - :internal: -- cgit v1.1