12 files changed, 430 insertions, 0 deletions
diff --git a/roms/u-boot/doc/api/dfu.rst b/roms/u-boot/doc/api/dfu.rst
new file mode 100644
index 000000000..5bd9e292a
--- /dev/null
+++ b/roms/u-boot/doc/api/dfu.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Device firmware update
+======================
+
+.. kernel-doc:: include/dfu.h
+   :internal:
diff --git a/roms/u-boot/doc/api/efi.rst b/roms/u-boot/doc/api/efi.rst
new file mode 100644
index 000000000..cb2a1c897
--- /dev/null
+++ b/roms/u-boot/doc/api/efi.rst
@@ -0,0 +1,176 @@
+.. 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 <image address> [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:
+
+SetWatchdogTimer service
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_watchdog.c
+   :internal:
+
+Runtime services
+----------------
+
+.. kernel-doc:: lib/efi_loader/efi_runtime.c
+   :internal:
+
+Variable services
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/efi_variable.h
+   :internal:
+.. 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:
+
+Protocols
+---------
+
+Block IO protocol
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_disk.c
+   :internal:
+
+File protocol
+~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_file.c
+   :internal:
+
+Graphical output protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_gop.c
+   :internal:
+
+Load file 2 protocol
+~~~~~~~~~~~~~~~~~~~~
+
+The load file 2 protocol can be used by the Linux kernel to load the initial
+RAM disk. U-Boot can be configured to provide an implementation.
+
+.. kernel-doc:: lib/efi_loader/efi_load_initrd.c
+   :internal:
+
+Network protocols
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_net.c
+   :internal:
+
+Random number generator protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_rng.c
+   :internal:
+
+Text IO protocols
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_console.c
+   :internal:
+
+Unicode Collation protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_unicode_collation.c
+   :internal:
+
+Unit testing
+------------
+
+The following library functions are provided to support writing UEFI unit tests.
+The should not be used elsewhere.
+
+.. kernel-doc:: include/efi_selftest.h
+   :internal:
diff --git a/roms/u-boot/doc/api/getopt.rst b/roms/u-boot/doc/api/getopt.rst
new file mode 100644
index 000000000..773f79aeb
--- /dev/null
+++ b/roms/u-boot/doc/api/getopt.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
+
+Option Parsing
+==============
+
+.. kernel-doc:: include/getopt.h
+   :internal:
diff --git a/roms/u-boot/doc/api/index.rst b/roms/u-boot/doc/api/index.rst
new file mode 100644
index 000000000..ea02aa571
--- /dev/null
+++ b/roms/u-boot/doc/api/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+U-Boot API documentation
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   dfu
+   efi
+   getopt
+   linker_lists
+   logging
+   pinctrl
+   rng
+   sandbox
+   serial
+   timer
+   unicode
diff --git a/roms/u-boot/doc/api/linker_lists.rst b/roms/u-boot/doc/api/linker_lists.rst
new file mode 100644
index 000000000..7063fdc83
--- /dev/null
+++ b/roms/u-boot/doc/api/linker_lists.rst
@@ -0,0 +1,159 @@
+.. 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
+
+Alignment issues
+----------------
+
+The linker script uses alphabetic sorting to group the different linker
+lists together. Each group has its own struct and potentially its own
+alignment. But when the linker packs the structs together it cannot ensure
+that a linker list starts on the expected alignment boundary.
+
+For example, if the first list has a struct size of 8 and we place 3 of
+them in the image, that means that the next struct will start at offset
+0x18 from the start of the linker_list section. If the next struct has
+a size of 16 then it will start at an 8-byte aligned offset, but not a
+16-byte aligned offset.
+
+With sandbox on x86_64, a reference to a linker list item using
+ll_entry_get() can force alignment of that particular linker_list item,
+if it is in the same file as the linker_list item is declared.
+
+Consider this example, where struct driver is 0x80 bytes::
+
+    ll_entry_declare(struct driver, fred, driver)
+
+    ...
+
+    void *p = ll_entry_get(struct driver, fred, driver)
+
+If these two lines of code are in the same file, then the entry is forced
+to be aligned at the 'struct driver' alignment, which is 16 bytes. If the
+second line of code is in a different file, then no action is taken, since
+the compiler cannot update the alignment of the linker_list item.
+
+In the first case, an 8-byte 'fill' region is added::
+
+   .u_boot_list_2_driver_2_testbus_drv
+               0x0000000000270018       0x80 test/built-in.o
+               0x0000000000270018                _u_boot_list_2_driver_2_testbus_drv
+   .u_boot_list_2_driver_2_testfdt1_drv
+               0x0000000000270098       0x80 test/built-in.o
+               0x0000000000270098                _u_boot_list_2_driver_2_testfdt1_drv
+   *fill*         0x0000000000270118        0x8
+   .u_boot_list_2_driver_2_testfdt_drv
+               0x0000000000270120       0x80 test/built-in.o
+               0x0000000000270120                _u_boot_list_2_driver_2_testfdt_drv
+   .u_boot_list_2_driver_2_testprobe_drv
+               0x00000000002701a0       0x80 test/built-in.o
+               0x00000000002701a0                _u_boot_list_2_driver_2_testprobe_drv
+
+With this, the linker_list no-longer works since items after testfdt1_drv
+are not at the expected address.
+
+Ideally we would have a way to tell gcc not to align structs in this way.
+It is not clear how we could do this, and in any case it would require us
+to adjust every struct used by the linker_list feature.
+
+The simplest fix seems to be to force each separate linker_list to start
+on the largest possible boundary that can be required by the compiler. This
+is the purpose of CONFIG_LINKER_LIST_ALIGN
+
+
+.. kernel-doc:: include/linker_lists.h
+   :internal:
diff --git a/roms/u-boot/doc/api/logging.rst b/roms/u-boot/doc/api/logging.rst
new file mode 100644
index 000000000..1e6cbc493
--- /dev/null
+++ b/roms/u-boot/doc/api/logging.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Logging API
+===========
+
+.. kernel-doc:: include/log.h
diff --git a/roms/u-boot/doc/api/pinctrl.rst b/roms/u-boot/doc/api/pinctrl.rst
new file mode 100644
index 000000000..043bd57ef
--- /dev/null
+++ b/roms/u-boot/doc/api/pinctrl.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Pinctrl and Pinmux
+==================
+
+.. kernel-doc:: include/dm/pinctrl.h
+   :internal:
diff --git a/roms/u-boot/doc/api/rng.rst b/roms/u-boot/doc/api/rng.rst
new file mode 100644
index 000000000..b826d4fd4
--- /dev/null
+++ b/roms/u-boot/doc/api/rng.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2018 Heinrich Schuchardt
+
+Random number generation
+========================
+
+Hardware random number generation
+---------------------------------
+
+.. kernel-doc:: include/rng.h
+   :internal:
+
+Pseudo random number generation
+-------------------------------
+
+.. kernel-doc:: include/rand.h
+   :internal:
diff --git a/roms/u-boot/doc/api/sandbox.rst b/roms/u-boot/doc/api/sandbox.rst
new file mode 100644
index 000000000..724776399
--- /dev/null
+++ b/roms/u-boot/doc/api/sandbox.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Sandbox
+=======
+
+The following API routines are used to implement the U-Boot sandbox.
+
+.. kernel-doc:: include/os.h
+   :internal:
diff --git a/roms/u-boot/doc/api/serial.rst b/roms/u-boot/doc/api/serial.rst
new file mode 100644
index 000000000..ed34e592a
--- /dev/null
+++ b/roms/u-boot/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/roms/u-boot/doc/api/timer.rst b/roms/u-boot/doc/api/timer.rst
new file mode 100644
index 000000000..b0695174d
--- /dev/null
+++ b/roms/u-boot/doc/api/timer.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
+
+Timer Subsystem
+===============
+
+.. kernel-doc:: include/timer.h
+   :internal:
diff --git a/roms/u-boot/doc/api/unicode.rst b/roms/u-boot/doc/api/unicode.rst
new file mode 100644
index 000000000..3fb6745f8
--- /dev/null
+++ b/roms/u-boot/doc/api/unicode.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Unicode support
+===============
+
+.. kernel-doc:: include/charset.h
+   :internal: