Merge tag 'efi-2023-07-rc2' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request efi-2023-07-rc2

Documentation:

* treat documentation warnings as errors in CI
* adjust StarFive VisionFive 2 and SiFive Unmatched documentation
* man-page for cp
* correct description of uclass_get_device_by_of_path
* correct proftool usage

UEFI

* Fix documentation of EFI Python tests
* Rename efi_selftest Python test

.azure-pipelines.yml

@@ -89,7 +89,7 @@ stages:
           virtualenv -p /usr/bin/python3 /tmp/venvhtml
           . /tmp/venvhtml/bin/activate
           pip install -r doc/sphinx/requirements.txt
-          make htmldocs
+          make htmldocs KDOC_WERROR=1
           make infodocs
 
   - job: todo

.gitlab-ci.yml

@@ -171,7 +171,7 @@ docs:
     - virtualenv -p /usr/bin/python3 /tmp/venvhtml
     - . /tmp/venvhtml/bin/activate
     - pip install -r doc/sphinx/requirements.txt
-    - make htmldocs
+    - make htmldocs KDOC_WERROR=1
     - make infodocs
 
 # some statistics about the code base

doc/board/sifive/unmatched.rst

@@ -56,8 +56,10 @@ Flashing
 ZSBL loads the U-Boot SPL (u-boot-spl.bin) from a partition with GUID type
 5B193300-FC78-40CD-8002-E86C45580B47
 
-U-Boot SPL expects u-boot.itb from a partition with GUID
-type 2E54B353-1271-4842-806F-E436D6AF6985
+With the default configuration U-Boot SPL expects u-boot.itb starting at sector
+2082 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR=0x822). It is recommended to use a
+partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985 for storing
+main U-Boot.
 
 u-boot.itb is a combination of fw_dynamic.bin, u-boot-nodtb.bin and
 device tree blob (hifive-unmatched-a00.dtb)

doc/board/starfive/visionfive2.rst

@@ -51,6 +51,8 @@ cloned and built for JH7110 as below:
 	cd opensbi
 	make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
 
+The VisionFive 2 support for OpenSBI was introduced after the v1.2 release.
+
 More detailed description of steps required to build FW_DYNAMIC firmware
 is beyond the scope of this document. Please refer OpenSBI documenation.
 (Note: OpenSBI git repo is at https://github.com/riscv/opensbi.git)
@@ -79,14 +81,19 @@ This will generate u-boot-spl.bin.normal.out file.
 Flashing
 ~~~~~~~~
 
-SPL loads the U-Boot SPL (u-boot-spl.bin.normal.out) from a partition with GUID type
-2E54B353-1271-4842-806F-E436D6AF6985
+The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
+partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
+to choose any partition number.
 
-U-Boot SPL expects a U-Boot FIT image (u-boot.itb) from a partition with GUID
-type BC13C2FF-59E6-4262-A352-B275FD6F7172
+With the default configuration U-Boot SPL loads the U-Boot FIT image
+(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
+When formatting it is recommended to use GUID
+BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
 
-FIT image (u-boot.itb) is a combination of fw_dynamic.bin, u-boot-nodtb.bin and
-device tree blob (jh7110-starfive-visionfive-2-v1.3b.dtb/jh7110-starfive-visionfive-2-v1.2a.dtb)
+The FIT image (u-boot.itb) is a combination of OpenSBI's fw_dynamic.bin,
+u-boot-nodtb.bin and the device tree blob
+(jh7110-starfive-visionfive-2-v1.3b.dtb or
+jh7110-starfive-visionfive-2-v1.2a.dtb).
 
 Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch)
 
@@ -117,7 +124,9 @@ Program the SD card
 Booting
 ~~~~~~~
 
-Change DIP switches MSEL[1:0] are set to 10, select the boot mode to SD.
+The board provides the DIP switches MSEL[1:0] to select the boot device.
+To select booting from SD-card set the DIP switches MSEL[1:0] to 10.
+
 Once you plugin the sdcard and power up, you should see the U-Boot prompt.
 
 Sample boot log from StarFive VisionFive2 board

doc/develop/trace.rst

@@ -100,7 +100,7 @@ Then run proftool to convert the trace information to ftrace format
 
 .. code-block:: console
 
-    $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-ftrace >trace.dat
+    $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-ftrace -o trace.dat
 
 Finally run kernelshark to display it (note it only works with `.dat` files!):
 

doc/usage/cmd/cp.rst

@@ -0,0 +1,83 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+cp command
+==========
+
+Synopsis
+--------
+
+::
+
+    cp source target count
+    cp.b source target count
+    cp.w source target count
+    cp.l source target count
+    cp.q source target count
+
+Description
+-----------
+
+The cp command is used to copy *count* chunks of memory from the *source*
+address to the *target* address. If the *target* address points to NOR flash,
+the flash is programmed.
+
+The number bytes in one chunk is defined by the suffix defaulting to 4 bytes:
+
+====== ==========
+suffix chunk size
+====== ==========
+.b     1 byte
+.w     2 bytes
+.l     4 bytes
+.q     8 bytes
+<none> 4 bytes
+====== ==========
+
+source
+        source address, hexadecimal
+
+target
+        target address, hexadecimal
+
+count
+        number of words to be copied, hexadecimal
+
+Examples
+--------
+
+The example device has a NOR flash where the lower part of the flash is
+protected. We first copy to RAM, then to unprotected flash. Last we try to
+write to protectd flash.
+
+::
+
+    => mtd list
+    List of MTD devices:
+    * nor0
+      - device: flash@0
+      - parent: root_driver
+      - driver: cfi_flash
+      - path: /flash@0
+      - type: NOR flash
+      - block size: 0x20000 bytes
+      - min I/O: 0x1 bytes
+      - 0x000000000000-0x000002000000 : "nor0"
+    => cp.b 4020000 5000000 200000
+    => cp.b 4020000 1e00000 20000
+    Copy to Flash... done
+    => cp.b 4020000 0 20000
+    Copy to Flash... Can't write to protected Flash sectors
+    =>
+
+Configuration
+-------------
+
+The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words
+(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on
+CONFIG_MTD_NOR_FLASH=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the command was successfully,
+1 (false) otherwise.

doc/usage/cmd/mmc.rst

@@ -213,10 +213,10 @@ The 'mmc info' command displays device's capabilities:
 The raw data can be read/written via 'mmc read/write' command:
 ::
 
-    => mmc read 0x40000000 0x5000 0x100
+    => mmc read 40000000 5000 100
     MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK
 
-    => mmc write 0x40000000 0x5000 0x10
+    => mmc write 40000000 5000 100
     MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK
 
 The partition list can be shown via 'mmc part' command:

doc/usage/index.rst

@@ -41,6 +41,7 @@ Shell commands
    cmd/cmp
    cmd/coninfo
    cmd/conitrace
+   cmd/cp
    cmd/cyclic
    cmd/dm
    cmd/ebtupdate

include/dm/uclass.h

@@ -274,7 +274,7 @@ int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
  * The device is probed to activate it ready for use.
  *
  * @id: ID to look up
- * @node: Device tree path to search for (if no such path then -ENODEV is returned)
+ * @path: Device tree path to search for (if no such path then -ENODEV is returned)
  * @devp: Returns pointer to device (there is only one for each node)
  * Return: 0 if OK, -ve on error
  */

test/py/tests/test_efi_bootmgr/conftest.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier:      GPL-2.0+
 
-"""Fixture for UEFI bootmanager test
-"""
+"""Fixture for UEFI bootmanager test."""
 
 import os
 import shutil
@@ -10,8 +9,7 @@ import pytest
 
 @pytest.fixture(scope='session')
 def efi_bootmgr_data(u_boot_config):
-    """Set up a file system to be used in UEFI bootmanager
-       tests
+    """Set up a file system to be used in UEFI bootmanager tests.
 
     Args:
         u_boot_config -- U-boot configuration.

test/py/tests/test_efi_capsule/capsule_defs.py

@@ -1,5 +1,7 @@
 # SPDX-License-Identifier:      GPL-2.0+
 
+"""Directoreis used for authentication and capsule tests."""
+
 # Directories
 CAPSULE_DATA_DIR = '/EFI/CapsuleTestData'
 CAPSULE_INSTALL_DIR = '/EFI/UpdateCapsule'

test/py/tests/test_efi_capsule/conftest.py

@@ -2,8 +2,7 @@
 # Copyright (c) 2020, Linaro Limited
 # Author: AKASHI Takahiro <takahiro.akashi@linaro.org>
 
-"""Fixture for UEFI capsule test
-"""
+"""Fixture for UEFI capsule test."""
 
 from subprocess import call, check_call, CalledProcessError
 import pytest
@@ -11,13 +10,15 @@ from capsule_defs import CAPSULE_DATA_DIR, CAPSULE_INSTALL_DIR, EFITOOLS_PATH
 
 @pytest.fixture(scope='session')
 def efi_capsule_data(request, u_boot_config):
-    """Set up a file system to be used in UEFI capsule and authentication test
-    and return a ath to disk image to be used for testing
+    """Set up a file system and return path to image.
+
+    The function sets up a file system to be used in UEFI capsule and
+    authentication test and returns a path to disk image to be used
+    for testing.
 
     request -- Pytest request object.
     u_boot_config -- U-boot configuration.
     """
-
     mnt_point = u_boot_config.persistent_data_dir + '/test_efi_capsule'
     data_dir = mnt_point + CAPSULE_DATA_DIR
     install_dir = mnt_point + CAPSULE_INSTALL_DIR

test/py/tests/test_efi_secboot/conftest.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2019, Linaro Limited
 # Author: AKASHI Takahiro <takahiro.akashi@linaro.org>
 
-""" Fixture for UEFI secure boot test """
+"""Fixture for UEFI secure boot test."""
 
 from subprocess import call, check_call, CalledProcessError
 import pytest
@@ -132,7 +132,9 @@ def efi_boot_env(request, u_boot_config):
 
 @pytest.fixture(scope='session')
 def efi_boot_env_intca(request, u_boot_config):
-    """Set up a file system to be used in UEFI secure boot test
+    """Set up file system for secure boot test.
+
+    Set up a file system to be used in UEFI secure boot test
     of intermediate certificates.
 
     Args:

test/py/tests/test_efi_secboot/defs.py

@@ -1,5 +1,7 @@
 # SPDX-License-Identifier:      GPL-2.0+
 
+"""Constants used for secure boot test."""
+
 # Owner guid
 GUID = '11111111-2222-3333-4444-123456789abc'
 

test/py/tests/test_efi_selftest.py

@@ -7,7 +7,7 @@
 import pytest
 
 @pytest.mark.buildconfigspec('cmd_bootefi_selftest')
-def test_efi_selftest(u_boot_console):
+def test_efi_selftest_base(u_boot_console):
     """Run UEFI unit tests
 
     u_boot_console -- U-Boot console

tools/dtoc/test_fdt.py

@@ -784,8 +784,8 @@ class TestFdtUtil(unittest.TestCase):
 
     def test_ensure_compiled_tmpdir(self):
         """Test providing a temporary directory"""
+        old_outdir = tools.outdir
         try:
-            old_outdir = tools.outdir
             tools.outdir= None
             tmpdir = tempfile.mkdtemp(prefix='test_fdt.')
             dtb = fdt_util.EnsureCompiled(find_dtb_file('dtoc_test_simple.dts'),
@@ -793,7 +793,7 @@ class TestFdtUtil(unittest.TestCase):
             self.assertEqual(tmpdir, os.path.dirname(dtb))
             shutil.rmtree(tmpdir)
         finally:
-            tools.outdir= old_outdir
+            tools.outdir = old_outdir
 
     def test_get_phandle_name_offset(self):
         val = fdt_util.GetPhandleNameOffset(self.node, 'missing')