Message-ID: <86f7f157-d25f-48cb-806c-c8dc914033f1@foss.st.com>
Date: Thu, 18 Dec 2025 11:45:10 +0100
From: Arnaud POULIQUEN <arnaud.pouliquen@...s.st.com>
To: Shenwei Wang <shenwei.wang@....com>, Linus Walleij <linusw@...nel.org>,
        Bartosz Golaszewski <brgl@...nel.org>, Rob Herring <robh@...nel.org>,
        Krzysztof Kozlowski <krzk+dt@...nel.org>,
        Conor Dooley <conor+dt@...nel.org>,
        Bjorn Andersson <andersson@...nel.org>,
        Mathieu Poirier
	<mathieu.poirier@...aro.org>,
        Shawn Guo <shawnguo@...nel.org>,
        Sascha Hauer
	<s.hauer@...gutronix.de>,
        Jonathan Corbet <corbet@....net>
CC: Pengutronix Kernel Team <kernel@...gutronix.de>,
        Fabio Estevam
	<festevam@...il.com>, Peng Fan <peng.fan@....com>,
        <linux-gpio@...r.kernel.org>, <devicetree@...r.kernel.org>,
        <linux-kernel@...r.kernel.org>, <linux-remoteproc@...r.kernel.org>,
        <imx@...ts.linux.dev>, <linux-arm-kernel@...ts.infradead.org>,
        <linux-doc@...r.kernel.org>, <linux-imx@....com>
Subject: Re: [PATCH v6 3/5] docs: driver-api: gpio: generic gpio driver over
 rpmsg bus

Hello Shenwei,

On 12/12/25 20:43, Shenwei Wang wrote:
> Describes the gpio rpmsg transport protocol over the rpmsg bus between
> the cores.
> 
> Signed-off-by: Shenwei Wang <shenwei.wang@....com>
> ---
>   Documentation/driver-api/gpio/gpio-rpmsg.rst | 232 +++++++++++++++++++
>   Documentation/driver-api/gpio/index.rst      |   1 +
>   2 files changed, 233 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..c78d10a9a85c
> --- /dev/null
> +++ b/Documentation/driver-api/gpio/gpio-rpmsg.rst
> @@ -0,0 +1,232 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +GPIO RPMSG Protocol
> +===================
> +
> +The GPIO RPMSG transport protocol is used for communication and interaction
> +with GPIO controllers located on remote cores on the RPMSG bus.
> +
> +Message Format
> +--------------
> +
> +The RPMSG message consists of a 14-byte packet with the following layout:
> +
> +.. code-block:: none
> +
> +   +-----+-------+--------+-----+-----+------------+-----+-----+-----+----+
> +   |0x00 |0x01   |0x02    |0x03 |0x04 |0x05..0x09  |0x0A |0x0B |0x0C |0x0D|
> +   | ID  |vendor |version |type |cmd  |reserved[5] |line |port |  data    |
> +   +-----+-------+--------+-----+-----+------------+-----+-----+-----+----+
> +
> +- **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?

> +
> +- **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.


> +
> +- **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?
In such case the remote might need a message to get the GPIO value on 
wake-up.

> +
> +  - 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

> +
> +**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?

> +
> +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 ?


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

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
>   ====

Powered by blists - more mailing lists