Re: [PATCH v4 11/12] doc/man: update description for nr_spis with eSPI

[Leonid Komarianskyi <Leonid_Komarianskyi@xxxxxxxx>]

Hi Volodymyr,

Thank you for your review comment and suggestions.

On 28.08.25 02:20, Volodymyr Babchuk wrote:
> Hi Leonid,
> 
> Leonid Komarianskyi <Leonid_Komarianskyi@xxxxxxxx> writes:
> 
>> Since eSPI support has been introduced, update the documentation with
>> the appropriate description.
>>
>> Signed-off-by: Leonid Komarianskyi <leonid_komarianskyi@xxxxxxxx>
>>
>> ---
>> Changes in V4:
>> - introduced this patch
>> ---
>>   docs/man/xl.cfg.5.pod.in | 13 ++++++++-----
>>   1 file changed, 8 insertions(+), 5 deletions(-)
>>
>> diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in
>> index 5362fb0e9a..292ab10331 100644
>> --- a/docs/man/xl.cfg.5.pod.in
>> +++ b/docs/man/xl.cfg.5.pod.in
>> @@ -3072,11 +3072,14 @@ interval of colors (such as "0-4").
>>   =item B<nr_spis="NR_SPIS">
>>   
>>   An optional integer parameter specifying the number of SPIs (Shared
>> -Peripheral Interrupts) to allocate for the domain. Max is 960 SPIs. If
>> -the `nr_spis` parameter is not specified, the value calculated by the 
>> toolstack
>> -will be used for the domain. Otherwise, the value specified by the `nr_spis`
>> -parameter will be used. The number of SPIs should match the highest 
>> interrupt
>> -ID that will be assigned to the domain.
>> +Peripheral Interrupts) to allocate for the domain. Max is 960 for regular 
>> SPIs
>> +or 5088 for eSPIs (Extended SPIs). The eSPIs includes an additional 1024 
>> SPIs
> 
> Well, this is awkward and confusing now. You can't allocate 5088 SPIs,
> because no GIC does not support this. Number of SPIs is
> 960 (regular SPIs) + 1024 (eSPIs) = 1984.
> 

I agree with this, but even if I were to update the toolstack logic with 
parsing IRQ part of domain config, it would still be confusing and 
awkward. This is because, in that case, we would need to define some 
range for eSPIs, such as a number from 960 to 1984, while in the DTS 
file, we would define the INTID of eSPIs as being from 4064 (0xFE0) to 
5088 (0x13DF). Additionally, the current mainline description:

 > The number of SPIs should match the highest interrupt ID that will be
 > assigned to the domain.

will also be incorrect in this case.

> What you are describing is "max SPI number", but the parameter is called
> "nr_spis". If we want to leave things consistent, we either need to
> deprecate nr_spis in favor of max_spi_nr, or severely rework nr_spi
> logic, so it can have values from 0 to 1984...
> 
> Personally, I'd prefer max_spi_nr approach, because it will be less
> confusing for a user. I am curios what ARM maintainers think about this.
> 

I also agree that nr_spis is not proper naming in the context of eSPIs. 
Introducing max_spi_nr and deprecating nr_spis is a good option, but 
this would require additional updates to the toolstack, documentation, etc..

Thus, I provided additional technical details in the context of eSPIs, 
which will be helpful for users even while using the current nr_spis:

 > The eSPIs includes an additional 1024 SPIs from the eSPI range (4096
 > to 5119) if the hardware supports extended SPIs (GICv3.1+) and
 > CONFIG_GICV3_ESPI is enabled.

This definitely needs to be agreed upon with ARM maintainers.

> 
>> +from the eSPI range (4096 to 5119) if the hardware supports extended SPIs
>> +(GICv3.1+) and CONFIG_GICV3_ESPI is enabled. If the `nr_spis` parameter is 
>> not
>> +specified, the value calculated by the toolstack will be used for the 
>> domain.
>> +Otherwise, the value specified by the `nr_spis` parameter will be used. The
>> +number of SPIs should match the highest interrupt ID that will be assigned 
>> to
>> +the domain.
>>   
>>   =item B<trap_unmapped_accesses=BOOLEAN>
> 

Best regards,
Leonid