Re: [RFC PATCH 6/9] linker_lists.rst: update documentation

[Rasmus Villemoes <ravi@prevas.dk>]

On Mon, May 25 2026, Simon Glass <sjg@chromium.org> wrote:

>>
>> -  __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.

Good catch, I hadn't noticed the inconsistency in how the existing
section versus symbol names were documented.

>> 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.

Ah, yes, that does require rewording to make sense.

>> 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.
>

Will do.

Thanks,
Rasmus