linux-kernel - Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAJZ5v0gWmmNwiNW=5XgpO6EJw6cAXpwOOePOtuGmR_JzrC+64g@mail.gmail.com>
Date:   Tue, 9 Apr 2019 18:42:59 +0200
From:   "Rafael J. Wysocki" <rafael@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     "Rafael J. Wysocki" <rafael@...nel.org>,
        Changbin Du <changbin.du@...il.com>,
        "Rafael J. Wysocki" <rjw@...ysocki.net>,
        Len Brown <lenb@...nel.org>,
        ACPI Devel Maling List <linux-acpi@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>
Subject: Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree

On Wed, Apr 3, 2019 at 9:36 PM Jonathan Corbet <corbet@....net> wrote:
>
> On Tue, 2 Apr 2019 10:25:23 +0200
> "Rafael J. Wysocki" <rafael@...nel.org> wrote:
>
> > There are ACPI-related documents currently in Documentation/acpi/ that
> > don't clearly fall under either driver-api or admin-guide.  For
> > example, some of them describe various aspects of the ACPI support
> > subsystem operation and some document expectations with respect to the
> > ACPI tables provided by the firmware etc.
> >
> > Where would you recommend to put them after converting to .rst?
>
> OK, I've done some pondering on this.  Maybe what we need is a new
> top-level "hardware guide" book meant to hold information on how the
> hardware works and what the kernel's expectations are.  Architecture
> information could maybe go there too.  Would this make sense?
>
> If so, I could see a division like this:
>
> Hardware guide

This is more about documenting the expectations regarding the platform
firmware, so what about firmware-guide instead?

>         acpi-lid
>         aml-debugger (or maybe driver api?)
>         debug (ditto)
>         DSD-properties-rules
>         gpio-properties
>         i2c-muxes
>
> Admin guide
>         cppc_sysfs
>         initrd_table_override

And I would add dsdt-override here.

>
> Driver-API
>         enumeration
>         scan_handlers
>

So what about this:

- Create a new firmware-guide under Documentation and add an acpi/
directory to it for starters.  Put the following files into it:

         acpi-lid
         aml-debugger
         debug (ditto)
         DSD-properties-rules
         gpio-properties
         i2c-muxes

- Add an acpi/ subdirectory to Documentation/admin-guide and put the
following files into it:

         cppc_sysfs
         initrd_table_override
         dsdt-override

- Add an acpi/ subdirectory to Documentation/driver-api and put the
following files into it:

         enumeration
         scan_handlers