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
The documentation contains notes like
This struct is part of ABI v1 and is deprecated.
Use struct gpio_v2_line_info instead.
This could be interpreted to mean the structs can be directly
substituted in v1 calls. Clarify that the user should use the
corresponding v2 ioctl() and structs.
Signed-off-by: Kent Gibson <[email protected]>
---
include/uapi/linux/gpio.h | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index e68a56969f36..103cd3c6c81e 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -333,7 +333,7 @@ struct gpio_v2_line_event {
* also be empty if the consumer doesn't set this up
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_info instead.
+ * Use ABI v2 and &struct gpio_v2_line_info instead.
*/
struct gpioline_info {
__u32 line_offset;
@@ -368,7 +368,7 @@ enum {
* at the end of the structure on 64-bit architectures.
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_info_changed instead.
+ * Use ABI v2 and &struct gpio_v2_line_info_changed instead.
*/
struct gpioline_info_changed {
struct gpioline_info info;
@@ -409,7 +409,7 @@ struct gpioline_info_changed {
* a valid anonymous file descriptor representing the request
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_request instead.
+ * Use ABI v2 and &struct gpio_v2_line_request instead.
*/
struct gpiohandle_request {
__u32 lineoffsets[GPIOHANDLES_MAX];
@@ -431,7 +431,7 @@ struct gpiohandle_request {
* @padding: reserved for future use and should be zero filled
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_config instead.
+ * Use ABI v2 and &struct gpio_v2_line_config instead.
*/
struct gpiohandle_config {
__u32 flags;
@@ -446,7 +446,7 @@ struct gpiohandle_config {
* the desired target state
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_values instead.
+ * Use ABI v2 and &struct gpio_v2_line_values instead.
*/
struct gpiohandle_data {
__u8 values[GPIOHANDLES_MAX];
@@ -471,7 +471,7 @@ struct gpiohandle_data {
* valid anonymous file descriptor representing the request
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_request instead.
+ * Use ABI v2 and &struct gpio_v2_line_request instead.
*/
struct gpioevent_request {
__u32 lineoffset;
@@ -494,7 +494,7 @@ struct gpioevent_request {
* %GPIOEVENT_EVENT_FALLING_EDGE
*
* Note: This struct is part of ABI v1 and is deprecated.
- * Use &struct gpio_v2_line_event instead.
+ * Use ABI v2 and &struct gpio_v2_line_event instead.
*/
struct gpioevent_data {
__u64 timestamp;
--
2.39.2
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 <[email protected]>
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.
--
With Best Regards,
Andy Shevchenko
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 <[email protected]>
>
> 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 <[email protected]> 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 <[email protected]>
> >
> > 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.
--
With Best Regards,
Andy Shevchenko
On Tue, Jan 9, 2024 at 3:02 PM Kent Gibson <[email protected]> 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