linux-kernel - Re: [PATCH v2 2/3] docs: consolidate peripheral interfaces

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <87r0oxb7yx.fsf@meer.lwn.net>
Date:   Mon, 24 Jul 2023 10:16:38 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Costa Shulyupin <costa.shul@...hat.com>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>,
        open list <linux-kernel@...r.kernel.org>
Cc:     Costa Shulyupin <costa.shul@...hat.com>
Subject: Re: [PATCH v2 2/3] docs: consolidate peripheral interfaces

Costa Shulyupin <costa.shul@...hat.com> writes:

> to make page Subsystems APIs more organized as requested
>
> Changes:
> v2: added pcmcia and subtitle
>
> Signed-off-by: Costa Shulyupin <costa.shul@...hat.com>
>
> ---
>
> Alternative consolidation of buses look more challenging.
> Here are too many buses, so them should be split again.
> Many of buses are specific for only x86 or only embedded computers.
> Is SCSI generic bus or storage bus?
> ---
>  Documentation/subsystem-apis.rst | 19 ++++++++++++++-----
>  1 file changed, 14 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index 90a0535a932a..5ace1c434977 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -48,6 +48,20 @@ Networking interfaces
>     isdn/index
>     mhi/index
>  
> +Peripheral interfaces
> +----------------------
> +
> +except specific networking and storage interfaces
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   usb/index
> +   PCI/index
> +   hwmon/index
> +   leds/index
> +   pcmcia/index
> +
>  Storage interfaces
>  ------------------
>  
> @@ -70,19 +84,14 @@ Storage interfaces
>     fpga/index
>     i2c/index
>     iio/index
> -   leds/index
> -   pcmcia/index
>     spi/index
>     w1/index
>     watchdog/index
>     virt/index
> -   hwmon/index
>     accel/index
>     security/index
>     crypto/index
>     bpf/index
> -   usb/index
> -   PCI/index
>     misc-devices/index
>     peci/index
>     wmi/index

I'm sorry, but I feel like you've missed the point here - adding PCMCIA
doesn't really address my concern at all.  What is a "peripheral
interface", and how does USB qualify but, say, SPI does not?  I feel
like we have stopped adding clarity at this point.

A lot of this documentation needs a closer look to think about how it
fits into our model.  As a quick example (and an example only), the LED
documentation would appear to be properly placed in the userspace-api
guide, not in this grab-bag section.  Just shuffling it around in the
file doesn't help address problems like that, unfortunately.

Thanks,

jon