Hi Rasmus,
On 2026-05-22T21:27:48, Rasmus Villemoes <[email protected]> wrote:
> linker_lists.rst: update documentation
>
> Remove the initial _2 component in the examples in order to match what
> linker_lists.h now does. This also makes the
>
> Note the two '_2_' constant components in the names
>
> easier to grok, as there is now only one such component.
>
> Remove the whole "Start and end symbols for the whole of the linker
> lists area can be defined as" paragraph, since that can no longer be
> done like that, and the (never used) macros doing it were removed in
> e2138cf1e60 ("linker_lists.h: drop never used ll_start, ll_end
> macros").
>
> Leave the occurrences in the "Alignment issues" subsection alone for
> now. They are verbatim copies from a u-boot.map file, and it would not
> be right to edit that long after the fact, when we cannot easily
> reproduce a u-boot.map exhibiting this phenomenon.
>
> [...]
>
> doc/api/linker_lists.rst | 54 +++++++++++++++++++++---------------------------
> 1 file changed, 23 insertions(+), 31 deletions(-)
> diff --git a/doc/api/linker_lists.rst b/doc/api/linker_lists.rst
> @@ -13,13 +13,13 @@ then the corresponding input section name is
>
> ::
>
> - __u_boot_list_ + 2_ + @_list + _2_ + @_entry
> + __u_boot_list_ + @_list + _2_ + @_entry
>
> and the C variable name is
>
> ::
>
> - _u_boot_list + _2_ + @_list + _2_ + @_entry
> + _u_boot_list + @_list + _2_ + @_entry
Not quite - the actual symbol is _u_boot_list_##_list##_2_##_name
(note the trailing underscore on the prefix), so for list 'drivers'
and entry 'first' the name expands to _u_boot_list_drivers_2_first
As written here, the components concatenate to
_u_boot_listdrivers_2_first - please change to:
_u_boot_list_ + @_list + _2_ + @_entry
to match the section line above and the unified '%u_boot_list_ + ...'
form a few lines later.
> diff --git a/doc/api/linker_lists.rst b/doc/api/linker_lists.rst
> @@ -46,16 +46,8 @@ 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_...
> + %u_boot_list_ + @_list + _1_...
> + %u_boot_list_ + @_list + _3_...
The commit message says the surrounding 'Note the two _2_ constant
components' paragraph is now easier to grok because only one such
component remains, but the paragraph itself still says 'two' in the
patched file. Please update it to say 'one' and adjust the rest of the
sentence, since the start/end mapping is now relative to the single
_2_ separator between list and entry.
> diff --git a/doc/api/linker_lists.rst b/doc/api/linker_lists.rst
> @@ -82,19 +74,19 @@ defined for the whole list and each sub-list:
> - %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_drivers_2_i2c_1
> + %u_boot_list_drivers_2_i2c_2_first
> + %u_boot_list_drivers_2_i2c_2_first
> + %u_boot_list_drivers_2_i2c_2_second
BTW '...i2c_2_first' is listed twice - please drop the duplicate at
the same time.
Regards,
Simon
