Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <3c6d7ab9-dac5-6950-db8d-3119e4529eb7@infradead.org>
Date:   Thu, 1 Jun 2023 09:28:39 -0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.11.0
Subject: Re: [PATCH v3] Documentation: subsystem-apis: Categorize remaining
 subsystems
Content-Language: en-US
To:     Costa Shulyupin <costa.shul@redhat.com>,
        Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org,
        Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     open list <linux-kernel@vger.kernel.org>,
        "open list:BPF [MISC]" <bpf@vger.kernel.org>
References: <ZHgM0qKWP3OusjUW@debian.me>
 <20230601145556.3927838-1-costa.shul@redhat.com>
From:   Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <20230601145556.3927838-1-costa.shul@redhat.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

Hi--

On 6/1/23 07:55, Costa Shulyupin wrote:
> From: Bagas Sanjaya <bagasdotme@gmail.com>
> 
> Add classes:
> * Core subsystems
> * Storage
> * Networking
> * Peripherals and devices
> * Embedded systems
> * Integrity
> * Virtualization
> * Miscellaneous
> 
> There is a FIXME that says to organize subsystems listed in
> subsystem-apis.rst. Fulfill it by categorize remaining subsytems
> by purpose/themes, while sorting entries in each category.
> 
> HID devices are already categorized in 3c591cc954d56e ("docs:
> consolidate human interface subsystems").
> 
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

This is a worthy goal, I am sure, but I am also sure that there is
a lot of bikeshedding that can go on here.
(examples below)

> 
> ---
> 
> Changes:
> v3: add Integrity, Virtualization and Miscellaneous per Bagas Sanjaya
> v2: add Core subsystems, Networking, Peripherals and Embedded
> v1: add Storgre category

          Storage

> ---
>  Documentation/subsystem-apis.rst | 119 ++++++++++++++++++++++---------
>  1 file changed, 86 insertions(+), 33 deletions(-)
> 
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index 55c90d5383ef..2c0b18a66e4e 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -10,58 +10,111 @@ is taken directly from the kernel source, with supplemental material added
>  as needed (or at least as we managed to add it — probably *not* all that is
>  needed).
>  
> +Core subsystems
> +---------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   core-api/index
> +   cpu-freq/index
> +   driver-api/index
> +   locking/index
> +   mm/index
> +   power/index
> +   scheduler/index
> +   timers/index
> +   wmi/index
> +
>  Human interfaces
>  ----------------
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   input/index
> +   fb/index
> +   gpu/index
>     hid/index
> +   input/index
>     sound/index
> -   gpu/index
> -   fb/index
>  
> -**Fixme**: much more organizational work is needed here.
> +Storage
> +-------
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   driver-api/index
> -   core-api/index
> -   locking/index
> -   accounting/index
>     block/index
>     cdrom/index
> -   cpu-freq/index
> -   fpga/index
> -   i2c/index
> -   iio/index
> -   isdn/index
> +   filesystems/index
> +   pcmcia/index

Why is pcmcia in the storage category?
It's just an interface (or a bus).

> +   scsi/index

SCSI is also just a bus, but most (all?) of our drivers
are for storage controllers AFAIK, although I have seen
SCSI printer drivers, maybe even a SCSI toaster driver. :)

> +   target/index
> +
> +
> +Networking
> +----------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   bpf/index
>     infiniband/index
> -   leds/index
> +   isdn/index
> +   mhi/index
>     netlabel/index
>     networking/index
> -   pcmcia/index
> -   power/index
> -   target/index
> -   timers/index
> +
> +
> +Peripherals and devices
> +-----------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   PCI/index
> +   hwmon/index
> +   leds/index
> +   misc-devices/index
> +   usb/index
> +
> +
> +Embedded systems
> +----------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   fpga/index
> +   i2c/index

I2C is just a bus IMO.
Same with SPI and W1.
Should we have a "Bus Interfaces" category?

> +   iio/index
> +   peci/index
>     spi/index
>     w1/index
> -   watchdog/index
> +
> +Integrity
> +---------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   crypto/index
> +   security/index
> +
> +Virtualization
> +--------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
>     virt/index
> -   hwmon/index
> +
> +Miscellaneous
> +-------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
>     accel/index
> -   security/index
> -   crypto/index
> -   filesystems/index
> -   mm/index
> -   bpf/index
> -   usb/index
> -   PCI/index
> -   scsi/index
> -   misc-devices/index
> -   scheduler/index
> -   mhi/index
> -   peci/index
> -   wmi/index
> +   accounting/index
> +   watchdog/index

Thanks.
-- 
~Randy