Documentation: gpio: clarify that line values are logical
Subsystems (3)
Kent Gibson
reviewercover Documentation: gpio: clarify that line values are logical
The line values passed by the GPIO uAPI are logical values, and the edges returned are based on changes to logical line values. While the documentation consistently uses active/inactive terminology to identify the values as logical, this is never explicitly spelt out. This series clarifies those points, with paricular emphasis on the effect the active low flag has on values and edge polarity.
Patch 1 provides clarification for ioctls passing line values.
Patch 2 provides clarification for functions returning edge events.
Cheers,
Kent.
Kent Gibson (2):
Documentation: gpio: Clarify effect of active low flag on line values
Documentation: gpio: Clarify effect of active low flag on line edges
.../gpio/gpio-handle-get-line-values-ioctl.rst | 7 +++++++ .../gpio/gpio-handle-set-line-values-ioctl.rst | 7 +++++++ .../userspace-api/gpio/gpio-lineevent-data-read.rst | 5 +++++ .../userspace-api/gpio/gpio-v2-line-event-read.rst | 5 +++++ .../userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst | 7 +++++++ .../userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst | 7 +++++++ 6 files changed, 38 insertions(+)
--
2.39.2
Kent Gibson
reviewerPATCH 1/2 Documentation: gpio: Clarify effect of active low flag on line values
The documentation does not make sufficiently clear that the uAPI deals with logical line values, nor does it describe the influence of the active low flag on the mapping between physical and logical line values.
Clarify the relationship between physical and logical line values and the effect of the active low flag for ioctls passing line values.
--- .../gpio/gpio-handle-get-line-values-ioctl.rst | 7 +++++++ .../gpio/gpio-handle-set-line-values-ioctl.rst | 7 +++++++ .../userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst | 7 +++++++ .../userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst | 7 +++++++ 4 files changed, 28 insertions(+)
Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst +7 -0
@@ -36,6 +36,13 @@ Description Get the values of all requested lines. +The values returned are logical, indicating if the line is active or inactive. +The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between physical +values (high/low) and logical values (active/inactive). +If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then high is active and +low is inactive. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then low is active +and high is inactive. + The values of both input and output lines may be read. For output lines, the value returned is driver and configuration dependent and
Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst +7 -0
@@ -36,6 +36,13 @@ Description Set the values of all requested output lines. +The values set are logical, indicating if the line is to be active or inactive. +The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between logical +values (active/inactive) and physical values (high/low). +If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then active is high and +inactive is low. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then active is low +and inactive is high. + Only the values of output lines may be set. Attempting to set the value of input lines is an error (**EPERM**).
Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst +7 -0
@@ -34,6 +34,13 @@ Description Get the values of requested lines. +The values returned are logical, indicating if the line is active or inactive. +The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between physical +values (high/low) and logical values (active/inactive). +If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then high is active and low is +inactive. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then low is active and +high is inactive. + The values of both input and output lines may be read. For output lines, the value returned is driver and configuration dependent and
Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst +7 -0
@@ -35,6 +35,13 @@ Description Set the values of requested output lines. +The values set are logical, indicating if the line is to be active or inactive. +The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between logical +values (active/inactive) and physical values (high/low). +If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then active is high and inactive +is low. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then active is low and +inactive is high. + Only the values of output lines may be set. Attempting to set the value of an input line is an error (**EPERM**).
Signature · 1 line
2.39.2
Kent Gibson
reviewerPATCH 2/2 Documentation: gpio: Clarify effect of active low flag on line edges
In reply to Kent GibsonThe documentation does not make sufficiently clear that edge polarity is based on changes to the logical line values, and that the physical polarity of edges is dependent on the active low flag.
Clarify the relationship between the active low flag and edge polarity for the functions that read edge events.
--- .../userspace-api/gpio/gpio-lineevent-data-read.rst | 5 +++++ Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst | 5 +++++ 2 files changed, 10 insertions(+)
Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst +5 -0
@@ -44,6 +44,11 @@ Edge detection must be enabled for the input line using either both. Edge events are then generated whenever edge interrupts are detected on the input line. +Edges are defined in terms of changes to the logical line value, so an inactive +to active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is +set then logical polarity is the opposite of physical polarity, and +``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical edge. + The kernel captures and timestamps edge events as close as possible to their occurrence and stores them in a buffer from where they can be read by userspace at its convenience using `read()`.
Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst +5 -0
@@ -40,6 +40,11 @@ Edge detection must be enabled for the input line using either both. Edge events are then generated whenever edge interrupts are detected on the input line. +Edges are defined in terms of changes to the logical line value, so an inactive +to active transition is a rising edge. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is +set then logical polarity is the opposite of physical polarity, and +``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresponds to a falling physical edge. + The kernel captures and timestamps edge events as close as possible to their occurrence and stores them in a buffer from where they can be read by userspace at its convenience using `read()`.
Signature · 1 line
2.39.2
Bartosz Golaszewski
AppliedFrom: Bartosz Golaszewski <[email protected]>
Quoted 8 lines · Kent Gibson
The line values passed by the GPIO uAPI are logical values, and the edges returned are based on changes to logical line values. While the documentation consistently uses active/inactive terminology to identify the values as logical, this is never explicitly spelt out. This series clarifies those points, with paricular emphasis on the effect the active low flag has on values and edge polarity.
[...]
Applied, thanks!
[1/2] Documentation: gpio: Clarify effect of active low flag on line values
commit: 5ca84d416e1ca82ca068906fc1386f61a57b17f2
[2/2] Documentation: gpio: Clarify effect of active low flag on line edges
commit: 08d94c7428680715527757585a6c4575fcf571b9Best regards,
Signature · 1 line
Bartosz Golaszewski <[email protected]>