| Message ID | 20240109140221.77725-1-warthog618@gmail.com |
|---|---|
| Headers | show |
| Series | gpio: uapi: documentation improvements | expand |
On Tue, Jan 09, 2024 at 10:02:16PM +0800, Kent Gibson wrote: > This is a series of minor clarifications and formatting tidy ups for > the GPIO uAPI kernel doc. > > The series is intended as a companion to my character device > uAPI documentation series, but makes sense on its own too. > > The patches are self contained and trivial so not much to add here. Reviewed-by: Andy Shevchenko <andy@kernel.org> for patches starting from the second one. The first one I personally don't understand why, but I'm not a native speaker! I believe, it's correct, although the original version seems okay to me.
On Sun, Jan 14, 2024 at 04:10:54PM +0200, Andy Shevchenko wrote: > On Tue, Jan 09, 2024 at 10:02:16PM +0800, Kent Gibson wrote: > > This is a series of minor clarifications and formatting tidy ups for > > the GPIO uAPI kernel doc. > > > > The series is intended as a companion to my character device > > uAPI documentation series, but makes sense on its own too. > > > > The patches are self contained and trivial so not much to add here. > > Reviewed-by: Andy Shevchenko <andy@kernel.org> > > for patches starting from the second one. > > The first one I personally don't understand why, but I'm not a native speaker! > I believe, it's correct, although the original version seems okay to me. > The problem isn't the language, unless you mean I'm explaining poorly, it is the logic. The original says "zero or negative value means error", but in case of an error the kernel does not actually set the fd. So if the user sends a request containing a positive fd they might incorrectly infer that the positive fd being returned implies success. The new wording is that the returned fd is only valid on success. And thanks for the review. Cheers, Kent.
On Sun, Jan 14, 2024 at 4:20 PM Kent Gibson <warthog618@gmail.com> wrote: > On Sun, Jan 14, 2024 at 04:10:54PM +0200, Andy Shevchenko wrote: > > On Tue, Jan 09, 2024 at 10:02:16PM +0800, Kent Gibson wrote: > > > This is a series of minor clarifications and formatting tidy ups for > > > the GPIO uAPI kernel doc. > > > > > > The series is intended as a companion to my character device > > > uAPI documentation series, but makes sense on its own too. > > > > > > The patches are self contained and trivial so not much to add here. > > > > Reviewed-by: Andy Shevchenko <andy@kernel.org> > > > > for patches starting from the second one. > > > > The first one I personally don't understand why, but I'm not a native speaker! > > I believe, it's correct, although the original version seems okay to me. > > The problem isn't the language, unless you mean I'm explaining poorly, it > is the logic. The original says "zero or negative value means error", but > in case of an error the kernel does not actually set the fd. So if the > user sends a request containing a positive fd they might incorrectly infer > that the positive fd being returned implies success. > > The new wording is that the returned fd is only valid on success. Ah, thanks for elaboration, now I understand the issue. Okay, feel free to extend the Rb to the first patch.
On Tue, Jan 9, 2024 at 3:02 PM Kent Gibson <warthog618@gmail.com> wrote: > > This is a series of minor clarifications and formatting tidy ups for > the GPIO uAPI kernel doc. > > The series is intended as a companion to my character device > uAPI documentation series, but makes sense on its own too. > > The patches are self contained and trivial so not much to add here. > > Cheers, > Kent. > > Kent Gibson (5): > gpio: uapi: improve description of fd fields > gpio: uapi: clarify hte references > gpio: uapi: drop trailing period from one sentence descriptions > gpio: uapi: document possible values of gpioevent_data.id > gpio: uapi: clarify using v2 rather than v1 > > include/uapi/linux/gpio.h | 52 ++++++++++++++++++++------------------- > 1 file changed, 27 insertions(+), 25 deletions(-) > > -- > 2.39.2 > Series applied, thanks! Bart