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. + +- **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 + +**Reply:** + +.. code-block:: none + + +------+--------+--------+ + | 0x00 | 0x01 | 0x02 | + | 1 | status | 0 | + +------+--------+--------+ + +- **status**: + + - 0: Ok + - 1: Error + +SET_WAKEUP (Cmd=16) +~~~~~~~~~~~~~~~~~~~ + +**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 +-------------------- + +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| + +------+------+--------+ + +- **line**: The GPIO line (pin) index of the port. + +- **trigger**: Optional parameter to indicate the trigger event type. + 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
