linux-kernel - Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

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: <20060830153242.c5081692.akpm@osdl.org>
Date:	Wed, 30 Aug 2006 15:32:42 -0700
From:	Andrew Morton <akpm@...l.org>
To:	"Randy.Dunlap" <rdunlap@...otime.net>
Cc:	"Rafael J. Wysocki" <rjw@...k.pl>, Greg KH <greg@...ah.com>,
	Pavel Machek <pavel@....cz>,
	LKML <linux-kernel@...r.kernel.org>
Subject: Re: [RFC][PATCH -mm] PM: add /sys/power documentation to
 Documentation/ABI

On Wed, 30 Aug 2006 15:03:58 -0700
"Randy.Dunlap" <rdunlap@...otime.net> wrote:

> On Wed, 30 Aug 2006 14:43:50 -0700 Andrew Morton wrote:
> 
> > On Wed, 30 Aug 2006 23:38:06 +0200
> > "Rafael J. Wysocki" <rjw@...k.pl> wrote:
> > 
> > > Documentation/ABI/testing
> > 
> > psst, Greg, they're still sending too much stuff: need more paperwork!
> > 
> > Some words about this in Documentation/SubmitChecklist would be nice.
> 
> and people actually using it would be nice(r).

c'mon, it must be taped to 1,000 monitors and bathroom doors by now?

> Is this close to what you are looking for?

I guess so, thanks.  Pointing at the README was sneaky.

> 
> From: Randy Dunlap <rdunlap@...otime.net>
> 
> Mention Documenation/ABI/ requirements in Documentation/SubmitChecklist.
> 
> Signed-off-by: Randy Dunlap <rdunlap@...otime.net>
> ---
>  Documentation/SubmitChecklist |    3 +++
>  1 files changed, 3 insertions(+)
> 
> --- linux-2618-rc5all.orig/Documentation/SubmitChecklist
> +++ linux-2618-rc5all/Documentation/SubmitChecklist
> @@ -61,3 +61,6 @@ kernel patches.
>      Documentation/kernel-parameters.txt.
>  
>  18: All new module parameters are documented with MODULE_PARM_DESC()
> +
> +19: All new userspace interfaces are documented in Documentation/ABI/.
> +    See Documentation/ABI/README for more information.

This ABI/ thing rather snuck under my radar (I saw it go past, but a lot of
things go past).

It'll be good if it works, but it is going to take quite a lot of thought,
effort and maintainer vigilance to be successful and to avoid becoming
rotware.

I wonder how hard it would be to write a script which parses a diff, works
out if it touches ABI things, complain if it doesn't alter
Documentation/ABI/*?  Not very - it's just a matter of defining a suitable
regexp.

What _should_ be documented in there, anyway?

- syscalls, obviously.

- /proc?  If so, everything, or are there exceptions?

- /sys?  If so, everything, or are there exceptions?

- ioctl numbers and payloads?

- netlink messages?

- ethtool thingies?  netdev interface names?  /proc/iomem identifiers? 
  module names?  kernel-thread comm[] contents?  The ABI is pretty fat.

scary.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/