Re: [PATCH v2] Documentation: gpiolib: document new interface

From: Rob Landley
Date: Sat Nov 23 2013 - 22:41:50 EST

On 11/18/2013 03:34:20 AM, Linus Walleij wrote:
On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot <acourbot@xxxxxxxxxx> wrote:

> The first version received zero feedback, hopefully this one will get more
> attention. :) Not much changes, just some more proofreading and the fixes
> and improvements that came from it. It looks ok as far as I am concerned.

Sorry I was swamped with other stuff...

I'm 8 gazillion messages behind myself.

Also Balsa's threading mode is broken so I tend to flag users when I'm in a hurry (alphabetical sort works) and when they change names midconversation I tend not to notice they've posted more on a topic. (Switching email clients is on my todo list.)

> Linus, I hope this can be merged during the -rc cycle of 3.13, since the
> gpiod_ interface is going to be introduced there. It would not make much
> sense for it to come without its documentation.

You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)

Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)

A 00-INDEX file wouldn't hurt, but it can always be added later. No reason to hold up the series for that. (I was using them to generate html indexes for kernel.org/doc but after the breakin they eliminated all non-git functionality so I haven't been able to update it since. They replaced kernel.org/doc/Documentation with a raw git checkout, and I expect them to replace kernel.org/doc/menuconfig with a raw git checkout any day now.)

That said, a 00-INDEX file would let you know where to start reading to find the file with the intro paragraph at the start of the old file, the bit explaining what GPIO is. Here the first file alphabetically is "board.txt", and I have no idea why it's named that, given how it starts. (I was sort of hoping that somebody who already knows the subsystem would comment before I do. I have no way of knowing if this documentation is _right_.)

Aforementioned first paragraph:

+This document explains how GPIOs can be assigned to given devices and functions.

+Note that it only applies to the new descriptor-based interface. For a
+description of the deprecated integer-based GPIO interface please refer to
+gpio-legacy.txt (actually, there is no real mapping possible with the old
+interface; you just fetch an integer from somewhere and request the
+corresponding GPIO.

Here's how I'd rewrite that:

"This document explains how to assign GPIOs to devices and functions using the descriptor-based GPIO interface. (For a description of the deprecated integer-based interface see gpio-legacy.txt.)"

Some reasons:

1) The word "given" made me think "assigned to" and "given" were alternate ways of saying the same thing. I know what you mean, but had to read it twice to follow, and I don't think "given" adds anything here but potential confusion.

2) Describing an interface as "new" is problematic; it will stop being new long before the documentation is updated to stop calling it that. Either say which kernel version it was introduced in or don't.

3) Does the kernel still use the old one? Is it scheduled to be removed? Why was it deprecated? Should software that uses it be rewritten to use the new one? What kind of timetable are we talking about? If you're not going to answer obvious questions, don't open the can of worms of comparing them (at least not here).

4) Warnings against the old interface belong in the document describing the old interface. (The sentence fragment and unbalanced parentheses was just gravy.)

But I really don't have time to go through every paragraph like that, and was hoping the gpio guys would (or just sign off on it so I don't have to)...

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