> -----Original Message-----
> From: Mathieu Poirier <[email protected]>
> Sent: Monday, July 13, 2026 12:17 PM
> To: Shenwei Wang (OSS) <[email protected]>
> Cc: Linus Walleij <[email protected]>; Bartosz Golaszewski <[email protected]>;
> Jonathan Corbet <[email protected]>; Rob Herring <[email protected]>; Krzysztof
> Kozlowski <[email protected]>; Conor Dooley <[email protected]>; Bjorn
> Andersson <[email protected]>; Frank Li <[email protected]>; Sascha Hauer
> <[email protected]>; Shuah Khan <[email protected]>; linux-
> [email protected]; [email protected]; [email protected];
> Pengutronix Kernel Team <[email protected]>; Fabio Estevam
> <[email protected]>; Shenwei Wang <[email protected]>; Peng Fan
> <[email protected]>; [email protected]; linux-
> [email protected]; [email protected]; linux-arm-
> [email protected]; dl-linux-imx <[email protected]>; Arnaud
> POULIQUEN <[email protected]>; [email protected]; Andrew Lunn
> <[email protected]>
> Subject: Re: [PATCH v14 1/5] docs: driver-api: gpio: rpmsg gpio driver over
> rpmsg
> bus
>
> On Thu, Jun 25, 2026 at 10:54:26AM -0500, Shenwei Wang wrote:
> > From: Shenwei Wang <[email protected]>
> >
> > Describes the gpio rpmsg transport protocol over the rpmsg bus between
> > the remote system and Linux.
> >
> > Signed-off-by: Shenwei Wang <[email protected]>
> > ---
> > Documentation/driver-api/gpio/gpio-rpmsg.rst | 271 +++++++++++++++++++
> > Documentation/driver-api/gpio/index.rst | 1 +
> > 2 files changed, 272 insertions(+)
> > create mode 100644 Documentation/driver-api/gpio/gpio-rpmsg.rst
> >
> > diff --git a/Documentation/driver-api/gpio/gpio-rpmsg.rst
> > b/Documentation/driver-api/gpio/gpio-rpmsg.rst
> > new file mode 100644
> > index 000000000000..7d351ff0adb0
> > --- /dev/null
> > +++ b/Documentation/driver-api/gpio/gpio-rpmsg.rst
> > @@ -0,0 +1,271 @@
> > +.. SPDX-License-Identifier: GPL-2.0-or-later
> > +
> > +GPIO RPMSG (Remote Processor Messaging) Protocol
> > +================================================
> > +
> > +The GPIO RPMSG transport protocol is used for communication and
> > +interaction with GPIO controllers on remote processors via the RPMSG bus.
> > +
> > +Message Format
> > +--------------
> > +
> > +The RPMSG message consists of a 8-byte packet with the following layout:
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | cmd | line | value |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +- **cmd**: Command code, used for GPIO_RPMSG_SEND messages.
> > +
> > +- **line**: The GPIO line (pin) index of the port.
>
> Here and throughout, please remove any mention of 'port'. This is handled by
> the
> endpoint device, i.e one GPIO controller (port) per endpoint.
>
> > +
> > +- **value**: See details in the command description below.
> > +
> > +
> > +GPIO Commands
> > +-------------
> > +
> > +Commands are specified in the **Cmd** field.
> > +
> > +The SEND message is always sent from Linux to the remote firmware.
> > +Each SEND corresponds to a single REPLY message. The GPIO driver
> > +should serialize messages and determine whether a REPLY message is
> > +required. If a REPLY message is expected but not received within the
> > +specified timeout period (currently 1 second in the Linux driver),
> > +the driver should return -ETIMEOUT.
> > +
> > +GET_DIRECTION (Cmd=2)
> > +~~~~~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | 2 | line | 0 |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > + +------+--------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 1 | status | value |
> > + +------+--------+--------+
> > +
> > +- **status**:
> > +
> > + - 0: Ok
> > + - 1: Error
> > +
> > +- **value**: Direction.
> > +
> > + - 0: None
> > + - 1: Output
> > + - 2: Input
> > +
> > +
> > +SET_DIRECTION (Cmd=3)
> > +~~~~~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | 3 | line | value |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +- **value**: Direction.
> > +
> > + - 0: None
> > + - 1: Output
> > + - 2: Input
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > + +------+--------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 1 | status | 0 |
> > + +------+--------+--------+
> > +
> > +- **status**:
> > +
> > + - 0: Ok
> > + - 1: Error
> > +
> > +
> > +GET_VALUE (Cmd=4)
> > +~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | 4 | line | 0 |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > + +------+--------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 1 | status | value |
> > + +------+--------+--------+
> > +
> > +- **status**:
> > +
> > + - 0: Ok
> > + - 1: Error
> > +
> > +- **value**: Level.
> > +
> > + - 0: Low
> > + - 1: High
> > +
> > +
> > +SET_VALUE (Cmd=5)
> > +~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | 5 | line | value |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +- **value**: Output level.
> > +
> > + - 0: Low
> > + - 1: High
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > + +------+--------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 1 | status | 0 |
> > + +------+--------+--------+
> > +
> > +- **status**:
> > +
> > + - 0: Ok
> > + - 1: Error
> > +
> > +
> > +SET_IRQ_TYPE (Cmd=6)
> > +~~~~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | 6 | line | value |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +- **value**: IRQ types.
> > +
> > + - 0: Interrupt disabled
> > + - 1: Rising edge trigger
> > + - 2: Falling edge trigger
> > + - 3: Both edge trigger
> > + - 4: High level trigger
> > + - 8: Low level trigger
>
> I'm in agreement with cmd 3, 4, 5 and 6.
>
How about cmd 2?
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > + +------+--------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 1 | status | 0 |
> > + +------+--------+--------+
> > +
> > +- **status**:
> > +
> > + - 0: Ok
> > + - 1: Error
> > +
> > +SET_WAKEUP (Cmd=16)
> > +~~~~~~~~~~~~~~~~~~~
>
> I already commented on messages that are not part of the virtio-gpio
> specification.
>
I don't believe virtio-gpio needs a SET_WAKEUP command.
In the RPMSG case, SET_WAKEUP is required because it performs an operation on
the
remote processor, so the remote side must be explicitly notified.
For virtio-gpio, however, everything is handled locally. The other side does
not need to
perform any action, so sending a SET_WAKEUP command appears unnecessary.
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > + +------+------+------+------+------+------+------+------+
> > + | 0x00 | 0x01 | 0x02 | 0x03 | 0x04 | 0x05 | 0x06 | 0x07 |
> > + | 1 | line | value |
> > + +------+------+------+------+------+------+------+------+
> > +
> > +- **value**: Wakeup enable.
> > +
> > + The remote system should always aim to stay in a power-efficient
> > + state by shutting down or clock-gating the GPIO blocks that aren't
> > + in use. Since the remoteproc driver is responsible for managing the
> > + power states of the remote firmware, the GPIO driver does not
> > + require to know the firmware's running states.
> > +
> > + When the wakeup bit is set, the remote firmware should configure
> > + the line as a wakeup source. The firmware should send the
> > + notification message to Linux after it is woken from the GPIO line.
> > +
> > + - 0: Disable wakeup from GPIO
> > + - 1: Enable wakeup from GPIO
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > + +------+--------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 1 | status | 0 |
> > + +------+--------+--------+
> > +
> > +- **status**:
> > +
> > + - 0: Ok
> > + - 1: Error
> > +
> > +Notification Message
> > +--------------------
>
> "Interrupt Messages"
>
> > +
> > +Notifications are sent by the remote core and they have
> > +**Type=2 (GPIO_RPMSG_NOTIFY)**:
> > +
> > +When a GPIO line asserts an interrupt on the remote processor, the
> > +firmware should immediately mask the corresponding interrupt source
> > +and send a notification message to the Linux. Upon completion of the
> > +interrupt handling on the Linux side, the driver should issue a
> > +command **SET_IRQ_TYPE** to the firmware to unmask the interrupt.
> > +
> > +A Notification message can arrive between a SEND and its REPLY
> > +message, and the driver is expected to handle this scenario.
> > +
> > +.. code-block:: none
> > +
> > + +------+------+--------+
> > + | 0x00 | 0x01 | 0x02 |
> > + | 2 | line | trigger|
> > + +------+------+--------+
>
> 2 things here:
>
> 1) You did not include messages that mask and unmask interrupts at the driver
> side.
Interrupt masking and unmasking are handled entirely on the local processor.
When an interrupt occurs, the remote system masks the interrupt and then sends
a notification
to Linux. After Linux processes the notification, it sends a SET_IRQ_TYPE
message back to the
remote system, which then unmasks the interrupt.
Thanks,
Shenwei
>
> 2) We are carrying virtio-gpio messages on top of RPMSG and as such, this
> whole
> protocol should be about thar:
>
> +------+------+--------+--------
> | 0x00 | payload |
> | Q | |
> +------+------+--------+--------
>
> Q = 0 requestq
> Q = 1 eventq
>
> The "payload" part is simply the format of the messages as found in the
> virtio-
> gpio specification. From there, the only thing left to mention is which
> messages
> are not supported, i.e get line names.
>
> > +
> > +- **line**: The GPIO line (pin) index of the port.
> > +
> > +- **trigger**: Optional parameter to indicate the trigger event type.
>
> Not part of the spec - remove.
>
> Given the refactoring work that is still needed, I will not look at the
> implementation.
>
> Thanks,
> Mathieu
>
> > +
> > diff --git a/Documentation/driver-api/gpio/index.rst
> > b/Documentation/driver-api/gpio/index.rst
> > index bee58f709b9a..e5eb1f82f01f 100644
> > --- a/Documentation/driver-api/gpio/index.rst
> > +++ b/Documentation/driver-api/gpio/index.rst
> > @@ -16,6 +16,7 @@ Contents:
> > drivers-on-gpio
> > bt8xxgpio
> > pca953x
> > + gpio-rpmsg
> >
> > Core
> > ====
> > --
> > 2.43.0
> >
