Merge tag 'efi-2023-01-rc5-3' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for efi-2023-01-rc5-3

Documentation:

* Describe building documentation

UEFI:

* Add .data section to aarch64 EFI binaries and correct section flags
* Correct sorting of capsules when updating
* Populate console handles in system table

Other:

* Fix description of eth_env_[gs]et_enetaddr() return value
* Avoid endless loop in sound play command

2 files changed, 91 insertions, 0 deletions

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
new file mode 100644
index 00000000000..896264dd7c1
--- /dev/null
+++ b/doc/build/documentation.rst
@@ -0,0 +1,90 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Building documentation
+======================
+
+The U-Boot documentation is based on the Sphinx documentation generator.
+
+HTML documentation
+------------------
+
+The *htmldocs* target is used to build the HTML documentation. It uses the
+`Read the Docs Sphinx theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_.
+
+.. code-block:: bash
+
+    # Create Python environment 'myenv'
+    python3 -m venv myenv
+    # Activate the Python environment
+    . myenv/bin/activate
+    # Install build requirements
+    python3 -m pip install -r doc/sphinx/requirements.txt
+    # Build the documentation
+    make htmldocs
+    # Deactivate the Python environment
+    deactivate
+    # Display the documentation in a graphical web browser
+    x-www-browser doc/output/index.html
+
+Infodoc documentation
+---------------------
+
+The *infodocs* target builds both a texinfo and an info file:
+
+.. code-block:: bash
+
+    # Create Python environment 'myenv'
+    python3 -m venv myenv
+    # Activate the Python environment
+    . myenv/bin/activate
+    # Install build requirements
+    python3 -m pip install -r doc/sphinx/requirements.txt
+    # Build the documentation
+    make infodocs
+    # Deactivate the Python environment
+    deactivate
+    # Display the documentation
+    info doc/output/texinfo/u-boot.info
+
+PDF documentation
+-----------------
+
+The *pdfdocs* target is meant to be used to build PDF documenation.
+As v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
+
+We can use texi2pdf instead:
+
+.. code-block:: bash
+
+    # Create Python environment 'myenv'
+    python3 -m venv myenv
+    # Activate the Python environment
+    . myenv/bin/activate
+    # Install build requirements
+    python3 -m pip install -r doc/sphinx/requirements.txt
+    # Build the documentation
+    make texinfodocs
+    # Deactivate the Python environment
+    deactivate
+    # Convert to PDF
+    texi2pdf doc/output/texinfo/u-boot.texi
+
+Texinfo documentation
+---------------------
+
+To build only the texinfo documentation the *texinfodocs* target is used:
+
+.. code-block:: bash
+
+    # Create Python environment 'myenv'
+    python3 -m venv myenv
+    # Activate the Python environment
+    . myenv/bin/activate
+    # Install build requirements
+    python3 -m pip install -r doc/sphinx/requirements.txt
+    # Build the documentation
+    make texinfodocs
+    # Deactivate the Python environment
+    deactivate
+
+The output is in file *doc/output/texinfo/u-boot.texi*.
diff --git a/doc/build/index.rst b/doc/build/index.rst
index 9a8105db21d..dc9cde40014 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -12,3 +12,4 @@ Build U-Boot
    docker
    tools
    buildman
+   documentation