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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <20190403133613.13f3fd75@lwn.net>
Date:   Wed, 3 Apr 2019 13:36:13 -0600
From:   Jonathan Corbet <corbet@....net>
To:     "Rafael J. Wysocki" <rafael@...nel.org>
Cc:     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 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
	acpi-lid
	aml-debugger (or maybe driver api?)
	debug (ditto)
	DSD-properties-rules
	gpio-properties
	i2c-muxes

Admin guide
	cppc_sysfs
	initrd_table_override

Driver-API
	enumeration
	scan_handlers

other:
	dsdt-override: find another home for those five lines

...and so on.  I've probably gotten at least one of those wrong, but that's
the idea.

Of course, then it would be nice to better integrate those documents so
that they fit into a single coherent whole...a guy can dream...:)

Thanks,

jon