lkml.org 
[lkml]   [2013]   [Nov]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v2] Documentation: gpiolib: document new interface
On 11/18/2013 03:34:20 AM, Linus Walleij wrote:
> On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot
> <acourbot@nvidia.com> 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

\
 
 \ /
  Last update: 2013-11-24 05:01    [W:0.066 / U:3.428 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site