[PATCH] Documentation: Add category of subsystem-apis

[PATCH] Documentation: Add category of subsystem-apis

[Manuel Ebner]

Add Bus and Communication category to reduce number of items in
'Other subsystems'.

Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
---
 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
-- 
2.55.0

Re: [PATCH] Documentation: Add category of subsystem-apis

[Randy Dunlap]

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@mailbox.org>

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.

That is a little confusing to me. ISTM that we need so *not* have
2 places listing bus documentation...

Anyway, this is a good start on that. It could be merged as is.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>


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

Re: [PATCH] Documentation: Add category of subsystem-apis

[Manuel Ebner]

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@mailbox.org>
> 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?


> 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@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

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

Re: [PATCH] Documentation: Add category of subsystem-apis

[Randy Dunlap]

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@mailbox.org>
>> 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@infradead.org>
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> 
> 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

Re: [PATCH] Documentation: Add category of subsystem-apis

[Jonathan Corbet]

Manuel Ebner <manuelebnerli@mailbox.org> writes:

> Add Bus and Communication category to reduce number of items in
> 'Other subsystems'.
>
> Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> ---
>  Documentation/subsystem-apis.rst | 21 ++++++++++++++-------
>  1 file changed, 14 insertions(+), 7 deletions(-)

Applied, thanks.

jon