[PATCH v6 3/5] docs: driver-api: gpio: generic gpio driver over rpmsg bus

[Shenwei Wang]

> -----Original Message-----
> From: Arnaud POULIQUEN <arnaud.pouliquen at foss.st.com>
> Sent: Thursday, December 18, 2025 4:45 AM
> To: Shenwei Wang <shenwei.wang at nxp.com>; Linus Walleij
> <linusw at kernel.org>; Bartosz Golaszewski <brgl at kernel.org>; Rob Herring
> <robh at kernel.org>; Krzysztof Kozlowski <krzk+dt at kernel.org>; Conor Dooley
> <conor+dt at kernel.org>; Bjorn Andersson <andersson at kernel.org>; Mathieu
> Poirier <mathieu.poirier at linaro.org>; Shawn Guo <shawnguo at kernel.org>;
> Sascha Hauer <s.hauer at pengutronix.de>; Jonathan Corbet <corbet at lwn.net>
> Cc: Pengutronix Kernel Team <kernel at pengutronix.de>; Fabio Estevam
> <festevam at gmail.com>; Peng Fan <peng.fan at nxp.com>; linux-
> gpio at vger.kernel.org; devicetree at vger.kernel.org; linux-
> kernel at vger.kernel.org; linux-remoteproc at vger.kernel.org; imx at lists.linux.dev;
> linux-arm-kernel at lists.infradead.org; linux-doc at vger.kernel.org; dl-linux-imx
> <linux-imx at nxp.com>
> Subject: [EXT] Re: [PATCH v6 3/5] docs: driver-api: gpio: generic gpio driver over
> rpmsg bus
> > +
> > + +-----+-------+--------+-----+-----+------------+-----+-----+-----+-
> > + ---+
> > +
> > +- **ID (Message Identification Code)**: Always be 0x5. Indicates the GPIO
> message.
> > +
> > +- **Vendor**: Vendor ID number.
> > +  - 0: Reserved
> > +  - 1: NXP
> 
> These two fields above seem useless for the rpmsg-gpio. Is there any reason to
> keep them?
> 

They are not used so far.
And they are reserved for implementing workarounds that might be required by 
different vendors or different firmware versions.

> > +
> > +- **Version**: Vendor-specific version number (such as software release).
> > +
> > +- **Type (Message Type)**: The message type can be one of:
> > +
> > +  - 0: GPIO_RPMSG_SETUP
> > +  - 1: GPIO_RPMSG_REPLY
> > +  - 2: GPIO_RPMSG_NOTIFY
> > +
> > +- **Cmd**: Command code, used for GPIO_RPMSG_SETUP messages.
> > +
> > +- **reserved[5]**: Reserved bytes. Should always be 0.
> > +
> > +- **line**: The GPIO line index.
> > +
> > +- **port**: The GPIO controller index.
> 
> The description of port and line should be OS-agnostic.
> The notion of a GPIO controller index makes sense from a Linux perspective, but
> here you should provide a hardware description.
> Additionally, I suggest reversing the order of port and line, as a line is an instance
> within a port.
> 
> Suggested definitions:
>    **port**: The GPIO port(bank) index.
>    **line**: The GPIO line(pin) index of the port.
> 

Okay, I’ll use your suggested descriptions in the next version. 
However, I’ll keep the current byte order since it’s the only implementation we’ve been able to test.

> 
> > +
> > +- **data**: See details in the command description below.
> > +
> > +GPIO Commands
> > +-------------
> > +
> > +Commands are specified in the **Cmd** field for **GPIO_RPMSG_SETUP**
> (Type=0) messages.
> > +
> > +The SETUP message is always sent from Linux to the remote firmware.
> > +Each SETUP 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.
> > +
> > +GPIO_RPMSG_INPUT_INIT (Cmd=0)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 0   | 0   |  0        |line |port | val | wk |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +- **val**: Interrupt trigger type.
> > +
> > +  - 0: Interrupt disabled
> > +  - 1: Rising edge trigger
> > +  - 2: Falling edge trigger
> > +  - 3: Both edge trigger
> > +  - 4: Low level trigger
> > +  - 5: High level trigger
> > +
> > +- **wk**: 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 responsibe for managing the
> > + power states of the
> 
> s/responsibe/responsible
> 
> > +  remote firmware, the GPIO driver does not require to konow the
> > + firmware's
> 
> s/konow/know/
> 
> > +  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.
> 
> What about the other direction? The remote could also need to disable message
> from Linux, right?

There are no restrictions on that.

> In such case the remote might need a message to get the GPIO value on wake-
> up.
> 

The remote is actually managing the GPIO controller. It can get any information 
regarding the GPIO controller if it wants. 

> > +
> > +  - 0: Disable wakeup from GPIO
> > +  - 1: Enable wakeup from GPIO
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 1   | 1   |  0        |line |port | err | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +- **err**: Error code from the remote core.
> > +
> > +  - 0: Success
> > +  - 1: General error (early remote software only returns this
> > + unclassified error)
> > +  - 2: Not supported (A command is not supported by the remote
> > + firmware)
> > +  - 3: Resource not available (The resource is not allocated to the
> > + Linux)
> > +  - 4: Resource busy (The resource is already used)
> > +  - 5: Parameter error
> > +
> > +GPIO_RPMSG_OUTPUT_INIT (Cmd=1)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> Does this means that we can not change the output level during runtime?
> else this should be renamed GPIO_RPMSG_OUTPUT_SET
> 

No. You can run the INIT cmd multiple times.

> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 0   | 1   |  0        |line |port | val | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +- **val**: Output level.
> > +
> > +  - 0: Low
> > +  - 1: High
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 1   | 1   |  0        |line |port | err | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +- **err**: See above for definitions.
> > +
> > +GPIO_RPMSG_INPUT_GET (Cmd=2)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 0   | 2   |  0        |line |port | 0   | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+-----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D |
> > +   | 5   | 1   | 0   | 1   | 2   |  0        |line |port | err |level|
> > +
> > + +-----+-----+-----+-----+-----+-----------+-----+-----+-----+-----+
> > +
> > +- **err**: See above for definitions.
> > +
> > +- **level**: Input level.
> > +
> > +  - 0: Low
> > +  - 1: High
> > +
> > +GPIO_RPMSG_GET_DIRECTION (Cmd=3)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +**Request:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 0   | 3   |  0        |line |port | 0   | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +**Reply:**
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+-----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D |
> > +   | 5   | 1   | 0   | 1   | 3   |  0        |line |port | err | dir |
> > +
> > + +-----+-----+-----+-----+-----+-----------+-----+-----+-----+-----+
> > +
> > +- **err**: See above for definitions.
> > +
> > +- **dir**: Direction.
> > +
> > +  - 0: Output
> > +  - 1: Input
> 
> So here if I well understand, the list of GPIO are defined in DT and This command
> should be use to check the direction during the probe.
> Could you document its usage?
> 

As the cmd name suggests, it’s used to retrieve the current GPIO line direction. This cmd
can run during the probe phase as well as at other times.

> > +
> > +Notification Message
> > +--------------------
> > +
> > +Notifications are sent with **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
> > +**GPIO_RPMSG_INPUT_INIT** command to the firmware to unmask the
> interrupt.
> > +
> > +A Notification message can arrive between a SETUP and its REPLY
> > +message, and the driver is expected to handle this scenario.
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 2   | 0   |  0        |line |port | 0   | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +- **line**: The GPIO line index.
> > +- **port**: The GPIO controller index.
> > +
> > +The reply message for the notification is optional. The remote
> > +firmware can implement it to simulate the interrupt acknowledgment
> behavior.
> > +
> > +The notification reply is sent with the byte index 0x4=1.
> > +
> > +.. code-block:: none
> > +
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +   |0x00 |0x01 |0x02 |0x03 |0x04 |0x05..0x09 |0x0A |0x0B |0x0C |0x0D|
> > +   | 5   | 1   | 0   | 2   | 1   |  0        |line |port | 0   | 0  |
> > +   +-----+-----+-----+-----+-----+-----------+-----+-----+-----+----+
> > +
> > +- **line**: The GPIO line index.
> > +- **port**: The GPIO controller index.
> 
> The type seems strange here, it is a reply but tagged as notification, what about
> adding a type 4 GPIO_RPMSG_NOTIFY_REPLY ?
> 

Seems reasonable. I will update it in next version.

> 
> It might be useful to specify the GPIO level as parameter, especially for  "3: Both
> edge trigger"
> 

Okay. Will add a "triggered event type" as a parameter in the notification message in the next version.

Regards,
Shenwei

> Thanks,
> Arnaud
> 
> > 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
> >   ====