Re: [PATCH] Documentation: Add category of subsystem-apis
From: Randy Dunlap
Date: Tue Nov 10 2026 - 18:40:33 EST
On 11/6/26 3:52 AM, Manuel Ebner wrote:
> Hi Randy,
>
> On Thu, 2026-11-05 at 14:01 -0800, Randy Dunlap wrote:
>> On 11/5/26 10:15 AM, Manuel Ebner wrote:
>>> Add Bus and Communication category to reduce number of items in
>>> 'Other subsystems'.
>>>
>>> Signed-off-by: Manuel Ebner <manuelebnerli@xxxxxxxxxxx>
>> driver-api/index.html
>> This LGTM but at first I was wondering why I2C is listed here but I3C
>> is not. I3C is listed under driver-api/index.html. So are some other
>> buses.
>
> I think the actual reason is: There is Documentation/i2c/
> but no Documentation/i3c/ . subsystem-apis.rst links to Documentation/<name>/index.rst ,
> core-api/index.rst links to Documentation/core-api/<name>.rst .
>
> however there is driver-api/i2c.rst and driver-api/i3c/index.rst.
> Thats why Documentation/driver-api/index.rst has this:
>> Bus-level documentation
>> ...
>> I3C subsystem
>> ...
>> Subsystem-specific APIs
>> ...
>> I2C and SMBus Subsystem
>
> The structure is weird.
>
> driver-api/index's justification is clearly stated, subsystem-apis's isn't.
> What is it?
"... how specific kernel subsystems work from the point of view of a kernel developer."
so it seems to be kernel internals and maybe some "theory of operation" type
documentation.
>
>> That is a little confusing to me. ISTM that we need so *not* have
>> 2 places listing bus documentation...
>
> I'm not sure about that. If the files serve to different people/roles both
> should be kept, adapted and refined.
>
>> Anyway, this is a good start on that. It could be merged as is.
>>
>> Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
>> Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
>
> Thanks
> Manuel
>
>>
>>> ---
>>> Documentation/subsystem-apis.rst | 21 ++++++++++++++-------
>>> 1 file changed, 14 insertions(+), 7 deletions(-)
>>>
>>> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
>>> index b1ad48bb40..4e886897d3 100644
>>> --- a/Documentation/subsystem-apis.rst
>>> +++ b/Documentation/subsystem-apis.rst
>>> @@ -24,6 +24,20 @@ Core subsystems
>>> timers/index
>>> locking/index
>>>
>>> +Bus and Communication interfaces
>>> +--------------------------------
>>> +
>>> +.. toctree::
>>> + :maxdepth: 1
>>> +
>>> + i2c/index
>>> + pcmcia/index
>>> + spi/index
>>> + w1/index
>>> + usb/index
>>> + PCI/index
>>> + peci/index
>>> +
>>> Human interfaces
>>> ----------------
>>>
>>> @@ -72,11 +86,7 @@ Other subsystems
>>> cpu-freq/index
>>> edac/index
>>> fpga/index
>>> - i2c/index
>>> iio/index
>>> - pcmcia/index
>>> - spi/index
>>> - w1/index
>>> watchdog/index
>>> virt/index
>>> hwmon/index
>>> @@ -84,9 +94,6 @@ Other subsystems
>>> security/index
>>> crypto/index
>>> bpf/index
>>> - usb/index
>>> - PCI/index
>>> misc-devices/index
>>> - peci/index
>>> wmi/index
>>> tee/index
--
~Randy