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