Re: [PATCH v9 04/20] gpio: uapi: define uAPI v2

[Andy Shevchenko]

On Tue, Sep 22, 2020 at 5:34 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> Add a new version of the uAPI to address existing 32/64-bit alignment
> issues, add support for debounce and event sequence numbers, allow
> requested lines with different configurations, and provide some future
> proofing by adding padding reserved for future use.
>
> The alignment issue relates to the gpioevent_data, which packs to different
> sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
> running on 64-bit kernels.  uAPI v2 addresses that particular issue, and
> the problem more generally, by adding pad fields that explicitly pad
> structs out to 64-bit boundaries, so they will pack to the same size now,
> and even if some of the reserved padding is used for __u64 fields in the
> future.
>
> The new structs have been analysed with pahole to ensure that they
> are sized as expected and contain no implicit padding.
>
> The lack of future proofing in v1 makes it impossible to, for example,
> add the debounce feature that is included in v2.
> The future proofing is addressed by providing configurable attributes in
> line config and reserved padding in all structs for future features.
> Specifically, the line request, config, info, info_changed and event
> structs receive updated versions and new ioctls.
>
> As the majority of the structs and ioctls were being replaced, it is
> opportune to rework some of the other aspects of the uAPI:
>
> v1 has three different flags fields, each with their own separate
> bit definitions.  In v2 that is collapsed to one - gpio_v2_line_flag.
>
> The handle and event requests are merged into a single request, the line
> request, as the two requests were mostly the same other than the edge
> detection provided by event requests.  As a byproduct, the v2 uAPI allows
> for multiple lines producing edge events on the same line handle.
> This is a new capability as v1 only supports a single line in an event
> request.
>
> As a consequence, there are now only two types of file handle to be
> concerned with, the chip and the line, and it is clearer which ioctls
> apply to which type of handle.
>
> There is also some minor renaming of fields for consistency compared to
> their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
> and consumer rather than consumer_label.
>
> Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
> clarity, and the gpiohandle_data __u8 array becomes a bitmap in
> gpio_v2_line_values.
>
> The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
> code, particularly libgpiod, should readily port to it.

...

> +struct gpio_v2_line_config {
> +       __aligned_u64 flags;
> +       __u32 num_attrs;

> +       /* Pad to fill implicit padding and reserve space for future use. */
> +       __u32 padding[5];

Probably I somehow missed the answer, but why do we need 5 here and not 1?

> +       struct gpio_v2_line_config_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];
> +};

...

> +struct gpio_v2_line_request {
> +       __u32 offsets[GPIO_V2_LINES_MAX];
> +       char consumer[GPIO_MAX_NAME_SIZE];
> +       struct gpio_v2_line_config config;
> +       __u32 num_lines;
> +       __u32 event_buffer_size;

> +       /* Pad to fill implicit padding and reserve space for future use. */
> +       __u32 padding[5];

Ditto.

> +       __s32 fd;
> +};

...

> +struct gpio_v2_line_info {
> +       char name[GPIO_MAX_NAME_SIZE];
> +       char consumer[GPIO_MAX_NAME_SIZE];
> +       __u32 offset;
> +       __u32 num_attrs;
> +       __aligned_u64 flags;
> +       struct gpio_v2_line_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];

> +       /* Space reserved for future use. */
> +       __u32 padding[4];

Here two comments as in previous patches, why this went after
attribute structures and why 2 is not enough?

> +};

...

> +struct gpio_v2_line_info_changed {
> +       struct gpio_v2_line_info info;
> +       __aligned_u64 timestamp_ns;
> +       __u32 event_type;
> +       /* Pad struct to 64-bit boundary and reserve space for future use. */
> +       __u32 padding[5];

Again, why 5 and not 1?

> +};

...

> +struct gpio_v2_line_event {
> +       __aligned_u64 timestamp_ns;
> +       __u32 id;
> +       __u32 offset;
> +       __u32 seqno;
> +       __u32 line_seqno;

> +       /* Space reserved for future use. */
> +       __u32 padding[6];

Why 6 and not 2?

And here actually sizeof() can be a version.
So, I still see possible versioning issues with ABI.

> +};

-- 
With Best Regards,
Andy Shevchenko