[RFC PATCH 16/16] binman: doc: Update binman_tests.rst for subdirectory layout

[Quentin Schulz]

Hi Simon,

On 2/27/26 12:47 AM, Simon Glass wrote:
> From: Simon Glass <simon.glass at canonical.com>
> 
> Update the documentation to reflect the new test file organisation:
> replace references to numbered test files with their new subdirectory
> paths, and update the guidance for adding new tests to describe the
> subdirectory structure instead of the old numbering scheme. Also fix
> a stale comment in ftest.py.
> 
> Signed-off-by: Simon Glass <simon.glass at canonical.com>
> ---
> 
>   doc/develop/binman_tests.rst | 11 ++++++-----
>   tools/binman/ftest.py        |  2 +-
>   2 files changed, 7 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/develop/binman_tests.rst b/doc/develop/binman_tests.rst
> index 78b02e6f435..e0baec05125 100644
> --- a/doc/develop/binman_tests.rst
> +++ b/doc/develop/binman_tests.rst
> @@ -453,9 +453,10 @@ help with this, but your code will be different.
>   
>   Generally you are adding a test because you are adding a new entry type
>   ('etype'). So start by creating the shortest and simplest image-description you
> -can, which contains the new etype. Put it in a numbered file in
> -``tool/binman/test`` so that it comes last. All the numbers are unique and there
> -are no gaps.
> +can, which contains the new etype. Put it in the appropriate subdirectory
> +under ``tools/binman/test`` with a descriptive filename (e.g. ``fit/`` for
> +FIT image tests, ``vendor/`` for vendor-specific tests, ``entry/`` for
> +general entry types).
>   

This is an awkward wording, the content in the parentheses seem to apply 
to "descriptive filename" but it only explains the "appropriate 
subdirectory" part.

What about:

Put it under ``tools/binman/test`` in the appropriate subdirectory (e.g. 
``fit/`` for FIT image tests, ``vendor/`` for vendor-specific tests, 
``entry/`` for general entry types) with a descriptive filename.

?

>   Example from ``tools/binman/test/vendor/nxp_imx8.dts``:
>   
> @@ -610,7 +611,7 @@ In the above example, here are some possible steps:
>   
>           Entry_section.SetImagePos(self, image_pos)
>   
> -   The solution is to add an entry, e.g. in ``340_nxp_imx8_non_empty.dts``:
> +   The solution is to add an entry, e.g. in ``vendor/nxp_imx8_non_empty.dts``:
>   

This should be with the patch changing the filename + path.

>      .. code-block:: devicetree
>   
> @@ -641,7 +642,7 @@ In the above example, here are some possible steps:
>   
>          def testNxpImx8ImageNonEmpty(self):
>              """Test that binman can produce an iMX8 image with something in it"""
> -            data = self._DoReadFile('340_nxp_imx8_non_empty.dts')
> +            data = self._DoReadFile('vendor/nxp_imx8_non_empty.dts')

Ditto.

>               # check data here
>   
>      With that, the second red bit goes away, because the for() loop is now used.
> diff --git a/tools/binman/ftest.py b/tools/binman/ftest.py
> index 0f1a799821d..2434e912d51 100644
> --- a/tools/binman/ftest.py
> +++ b/tools/binman/ftest.py
> @@ -2130,7 +2130,7 @@ class TestFunctional(unittest.TestCase):
>   
>               # Unfortunately, compiling a source file always results in a file
>               # called source.dtb (see fdt_util.EnsureCompiled()). The test
> -            # source file (e.g. test/075_fdt_update_all.dts) thus does not enter
> +            # source file (e.g. test/fdt/fdt_update_all.dts) thus does not enter

Ditto.

Cheers,
Quentin