diff mbox series

[v9,13/20] gpio: uapi: document uAPI v1 as deprecated

Message ID 20200922023151.387447-14-warthog618@gmail.com
State Superseded
Headers show
Series gpio: cdev: add uAPI v2 | expand

Commit Message

Kent Gibson Sept. 22, 2020, 2:31 a.m. UTC
Update uAPI documentation to deprecate v1 structs and ioctls.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 include/uapi/linux/gpio.h | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

Comments

Arnd Bergmann Sept. 22, 2020, 7:49 a.m. UTC | #1
On Tue, Sep 22, 2020 at 4:36 AM Kent Gibson <warthog618@gmail.com> wrote:
>  /*

>   *  ABI v1

> + *

> + * This version of the ABI is deprecated and will be removed in the future.

> + * Use the latest version of the ABI, defined above, instead.

>   */


How intentional is the wording here? It seems unrealistic that the v1 ABI
would be removed any time soon if there are existing users and applications
cannot yet rely on v2 to be present in all kernels, so it sounds like a hollow
threat.

At the same time I can see that telling users it will be removed can lead to
them moving on to the new version more quickly, so maybe a hollow threat
is in fact appropriate here ;-)

      Arnd
Andy Shevchenko Sept. 22, 2020, 8:11 a.m. UTC | #2
On Tue, Sep 22, 2020 at 10:49 AM Arnd Bergmann <arnd@arndb.de> wrote:
> On Tue, Sep 22, 2020 at 4:36 AM Kent Gibson <warthog618@gmail.com> wrote:

> >  /*

> >   *  ABI v1

> > + *

> > + * This version of the ABI is deprecated and will be removed in the future.

> > + * Use the latest version of the ABI, defined above, instead.

> >   */

>

> How intentional is the wording here? It seems unrealistic that the v1 ABI

> would be removed any time soon if there are existing users and applications

> cannot yet rely on v2 to be present in all kernels, so it sounds like a hollow

> threat.


I have similar thoughts when commenting on previous versions of this piece.

> At the same time I can see that telling users it will be removed can lead to

> them moving on to the new version more quickly, so maybe a hollow threat

> is in fact appropriate here ;-)


Users all know that if something will be broken, they may escalate to
Linus T. and get things reverted. So, above depends on the user's
knowledge about the process.

-- 
With Best Regards,
Andy Shevchenko
Kent Gibson Sept. 22, 2020, 9:05 a.m. UTC | #3
On Tue, Sep 22, 2020 at 09:49:11AM +0200, Arnd Bergmann wrote:
> On Tue, Sep 22, 2020 at 4:36 AM Kent Gibson <warthog618@gmail.com> wrote:
> >  /*
> >   *  ABI v1
> > + *
> > + * This version of the ABI is deprecated and will be removed in the future.
> > + * Use the latest version of the ABI, defined above, instead.
> >   */
> 
> How intentional is the wording here? It seems unrealistic that the v1 ABI
> would be removed any time soon if there are existing users and applications
> cannot yet rely on v2 to be present in all kernels, so it sounds like a hollow
> threat.
> 

Andy had a similar comment regarding the build option, which I updated,
but missed updating it here.  The updated sentence ends at deprecated.
I will update these to match in the next rev.

> At the same time I can see that telling users it will be removed can lead to
> them moving on to the new version more quickly, so maybe a hollow threat
> is in fact appropriate here ;-)
> 

That was the idea - though even the sysfs interface is still there
and doesn't seem to be going anywhere in a hurry.

Cheers,
Kent.
diff mbox series

Patch

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index 5904f49399de..98d5aa88870b 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -292,6 +292,9 @@  struct gpio_v2_line_event {
 
 /*
  *  ABI v1
+ *
+ * This version of the ABI is deprecated and will be removed in the future.
+ * Use the latest version of the ABI, defined above, instead.
  */
 
 /* Informational flags */
@@ -315,6 +318,9 @@  struct gpio_v2_line_event {
  * @consumer: a functional name for the consumer of this GPIO line as set by
  * whatever is using it, will be empty if there is no current user but may
  * also be empty if the consumer doesn't set this up
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_info instead.
  */
 struct gpioline_info {
 	__u32 line_offset;
@@ -346,6 +352,9 @@  enum {
  * guarantee there are no implicit holes between it and subsequent members.
  * The 20-byte padding at the end makes sure we don't add any implicit padding
  * at the end of the structure on 64-bit architectures.
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_info_changed instead.
  */
 struct gpioline_info_changed {
 	struct gpioline_info info;
@@ -385,6 +394,9 @@  struct gpioline_info_changed {
  * @fd: if successful this field will contain a valid anonymous file handle
  * after a GPIO_GET_LINEHANDLE_IOCTL operation, zero or negative value
  * means error
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_request instead.
  */
 struct gpiohandle_request {
 	__u32 lineoffsets[GPIOHANDLES_MAX];
@@ -404,6 +416,9 @@  struct gpiohandle_request {
  * this specifies the default output value, should be 0 (low) or
  * 1 (high), anything else than 0 or 1 will be interpreted as 1 (high)
  * @padding: reserved for future use and should be zero filled
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_config instead.
  */
 struct gpiohandle_config {
 	__u32 flags;
@@ -416,6 +431,9 @@  struct gpiohandle_config {
  * @values: when getting the state of lines this contains the current
  * state of a line, when setting the state of lines these should contain
  * the desired target state
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_values instead.
  */
 struct gpiohandle_data {
 	__u8 values[GPIOHANDLES_MAX];
@@ -439,6 +457,9 @@  struct gpiohandle_data {
  * @fd: if successful this field will contain a valid anonymous file handle
  * after a GPIO_GET_LINEEVENT_IOCTL operation, zero or negative value
  * means error
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_request instead.
  */
 struct gpioevent_request {
 	__u32 lineoffset;
@@ -458,6 +479,9 @@  struct gpioevent_request {
  * struct gpioevent_data - The actual event being pushed to userspace
  * @timestamp: best estimate of time of event occurrence, in nanoseconds
  * @id: event identifier
+ *
+ * This struct is part of ABI v1 and is deprecated.
+ * Use struct gpio_v2_line_event instead.
  */
 struct gpioevent_data {
 	__u64 timestamp;
@@ -482,6 +506,8 @@  struct gpioevent_data {
 
 /*
  * v1 ioctl()s
+ *
+ * These ioctl()s are deprecated.  Use the v2 equivalent instead.
  */
 #define GPIO_GET_LINEINFO_IOCTL _IOWR(0xB4, 0x02, struct gpioline_info)
 #define GPIO_GET_LINEHANDLE_IOCTL _IOWR(0xB4, 0x03, struct gpiohandle_request)