1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2021 Marvell.
4 Marvell CNXK GPIO Driver
5 ========================
7 CNXK GPIO PMD configures and manages GPIOs available on the system using
8 standard enqueue/dequeue mechanism offered by raw device abstraction. PMD relies
9 both on standard sysfs GPIO interface provided by the Linux kernel and GPIO
10 kernel driver custom interface allowing one to install userspace interrupt
16 Following features are available:
18 - export/unexport a GPIO
19 - read/write specific value from/to exported GPIO
21 - set GPIO edge that triggers interrupt
23 - register interrupt handler for specific GPIO
28 PMD relies on modified kernel GPIO driver which exposes ``ioctl()`` interface
29 for installing interrupt handlers for low latency signal processing.
31 Driver is shipped with Marvell SDK.
36 CNXK GPIO PMD binds to virtual device which gets created by passing
37 `--vdev=cnxk_gpio,gpiochip=<number>` command line to EAL. `gpiochip` parameter
38 tells PMD which GPIO controller should be used. Available controllers are
39 available under `/sys/class/gpio`. For further details on how Linux represents
40 GPIOs in userspace please refer to
41 `sysfs.txt <https://www.kernel.org/doc/Documentation/gpio/sysfs.txt>`_.
43 If `gpiochip=<number>` was omitted then first gpiochip from the alphabetically
44 sort list of available gpiochips is used.
46 .. code-block:: console
49 export gpiochip448 unexport
51 In above scenario only one GPIO controller is present hence
52 `--vdev=cnxk_gpio,gpiochip=448` should be passed to EAL.
54 Before performing actual data transfer one needs to call
55 ``rte_rawdev_queue_count()`` followed by ``rte_rawdev_queue_conf_get()``. The
56 former returns number GPIOs available in the system irrespective of GPIOs
57 being controllable or not. Thus it is user responsibility to pick the proper
58 ones. The latter call simply returns queue capacity.
60 In order to allow using only subset of available GPIOs `allowlist` PMD param may
61 be used. For example passing `--vdev=cnxk_gpio,gpiochip=448,allowlist=[0,1,2,3]`
62 to EAL will deny using all GPIOs except those specified explicitly in the
65 Respective queue needs to be configured with ``rte_rawdev_queue_setup()``. This
66 call barely exports GPIO to userspace.
68 To perform actual data transfer use standard ``rte_rawdev_enqueue_buffers()``
69 and ``rte_rawdev_dequeue_buffers()`` APIs. Not all messages produce sensible
70 responses hence dequeueing is not always necessary.
75 PMD accepts ``struct cnxk_gpio_msg`` messages which differ by type and payload.
76 Message types along with description are listed below. As for the usage examples
77 please refer to ``cnxk_gpio_selftest()``. There's a set of convenient wrappers
78 available, one for each existing command.
83 Message is used to set output to low or high. This does not work for GPIOs
86 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_VALUE``.
88 Payload must be an integer set to 0 (low) or 1 (high).
90 Consider using ``rte_pmd_gpio_set_pin_value()`` wrapper.
95 Message is used to set edge that triggers interrupt.
97 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_EDGE``.
99 Payload must be `enum cnxk_gpio_pin_edge`.
101 Consider using ``rte_pmd_gpio_set_pin_edge()`` wrapper.
106 Message is used to change GPIO direction to either input or output.
108 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_DIR``.
110 Payload must be `enum cnxk_gpio_pin_dir`.
112 Consider using ``rte_pmd_gpio_set_pin_dir()`` wrapper.
117 Message is used to set whether pin is active low.
119 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_ACTIVE_LOW``.
121 Payload must be an integer set to 0 or 1. The latter activates inversion.
123 Consider using ``rte_pmd_gpio_set_pin_active_low()`` wrapper.
128 Message is used to read GPIO value. Value can be 0 (low) or 1 (high).
130 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_VALUE``.
132 Payload contains integer set to either 0 or 1.
134 Consider using ``rte_pmd_gpio_get_pin_value()`` wrapper.
139 Message is used to read GPIO edge.
141 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_EDGE``.
143 Payload contains `enum cnxk_gpio_pin_edge`.
145 Consider using ``rte_pmd_gpio_get_pin_edge()`` wrapper.
150 Message is used to read GPIO direction.
152 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_DIR``.
154 Payload contains `enum cnxk_gpio_pin_dir`.
156 Consider using ``rte_pmd_gpio_get_pin_dir()`` wrapper.
161 Message is used check whether inverted logic is active.
163 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_ACTIVE_LOW``.
165 Payload contains an integer set to 0 or 1. The latter means inverted logic
168 Consider using ``rte_pmd_gpio_get_pin_active_low()`` wrapper.
173 Message is used to install custom interrupt handler.
175 Message must have type set to ``CNXK_GPIO_MSG_TYPE_REGISTER_IRQ``.
177 Payload needs to be set to ``struct cnxk_gpio_irq`` which describes interrupt
180 Consider using ``rte_pmd_gpio_register_gpio()`` wrapper.
185 Message is used to remove installed interrupt handler.
187 Message must have type set to ``CNXK_GPIO_MSG_TYPE_UNREGISTER_IRQ``.
189 Consider using ``rte_pmd_gpio_unregister_gpio()`` wrapper.
194 On EAL initialization CNXK GPIO device will be probed and populated into
195 the list of raw devices on condition ``--vdev=cnxk_gpio,gpiochip=<number>`` was
196 passed. ``rte_rawdev_get_dev_id("CNXK_GPIO")`` returns unique device id. Use
197 this identifier for further rawdev function calls.
199 Selftest rawdev API can be used to verify the PMD functionality. Note it blindly
200 assumes that all GPIOs are controllable so some errors during test are expected.