doc/guides/rawdevs/cnxk_gpio.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 Marvell.
   3
   4 Marvell CNXK GPIO Driver
   5 ========================
   6
   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
  11 handlers.
  12
  13 Features
  14 --------
  15
  16 Following features are available:
  17
  18 - export/unexport a GPIO
  19 - read/write specific value from/to exported GPIO
  20 - set GPIO direction
  21 - set GPIO edge that triggers interrupt
  22 - set GPIO active low
  23 - register interrupt handler for specific GPIO
  24
  25 Requirements
  26 ------------
  27
  28 PMD relies on modified kernel GPIO driver which exposes ``ioctl()`` interface
  29 for installing interrupt handlers for low latency signal processing.
  30
  31 Driver is shipped with Marvell SDK.
  32
  33 Device Setup
  34 ------------
  35
  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>`_.
  42
  43 If `gpiochip=<number>` was omitted then first gpiochip from the alphabetically
  44 sort list of available gpiochips is used.
  45
  46 .. code-block:: console
  47
  48    $ ls /sys/class/gpio
  49    export gpiochip448 unexport
  50
  51 In above scenario only one GPIO controller is present hence
  52 `--vdev=cnxk_gpio,gpiochip=448` should be passed to EAL.
  53
  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.
  59
  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
  63 `allowlist`.
  64
  65 Respective queue needs to be configured with ``rte_rawdev_queue_setup()``. This
  66 call barely exports GPIO to userspace.
  67
  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.
  71
  72 CNXK GPIO PMD
  73 -------------
  74
  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.
  79
  80 Set GPIO value
  81 ~~~~~~~~~~~~~~
  82
  83 Message is used to set output to low or high. This does not work for GPIOs
  84 configured as input.
  85
  86 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_VALUE``.
  87
  88 Payload must be an integer set to 0 (low) or 1 (high).
  89
  90 Consider using ``rte_pmd_gpio_set_pin_value()`` wrapper.
  91
  92 Set GPIO edge
  93 ~~~~~~~~~~~~~
  94
  95 Message is used to set edge that triggers interrupt.
  96
  97 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_EDGE``.
  98
  99 Payload must be `enum cnxk_gpio_pin_edge`.
 100
 101 Consider using ``rte_pmd_gpio_set_pin_edge()`` wrapper.
 102
 103 Set GPIO direction
 104 ~~~~~~~~~~~~~~~~~~
 105
 106 Message is used to change GPIO direction to either input or output.
 107
 108 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_DIR``.
 109
 110 Payload must be `enum cnxk_gpio_pin_dir`.
 111
 112 Consider using ``rte_pmd_gpio_set_pin_dir()`` wrapper.
 113
 114 Set GPIO active low
 115 ~~~~~~~~~~~~~~~~~~~
 116
 117 Message is used to set whether pin is active low.
 118
 119 Message must have type set to ``CNXK_GPIO_MSG_TYPE_SET_PIN_ACTIVE_LOW``.
 120
 121 Payload must be an integer set to 0 or 1. The latter activates inversion.
 122
 123 Consider using ``rte_pmd_gpio_set_pin_active_low()`` wrapper.
 124
 125 Get GPIO value
 126 ~~~~~~~~~~~~~~
 127
 128 Message is used to read GPIO value. Value can be 0 (low) or 1 (high).
 129
 130 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_VALUE``.
 131
 132 Payload contains integer set to either 0 or 1.
 133
 134 Consider using ``rte_pmd_gpio_get_pin_value()`` wrapper.
 135
 136 Get GPIO edge
 137 ~~~~~~~~~~~~~
 138
 139 Message is used to read GPIO edge.
 140
 141 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_EDGE``.
 142
 143 Payload contains `enum cnxk_gpio_pin_edge`.
 144
 145 Consider using ``rte_pmd_gpio_get_pin_edge()`` wrapper.
 146
 147 Get GPIO direction
 148 ~~~~~~~~~~~~~~~~~~
 149
 150 Message is used to read GPIO direction.
 151
 152 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_DIR``.
 153
 154 Payload contains `enum cnxk_gpio_pin_dir`.
 155
 156 Consider using ``rte_pmd_gpio_get_pin_dir()`` wrapper.
 157
 158 Get GPIO active low
 159 ~~~~~~~~~~~~~~~~~~~
 160
 161 Message is used check whether inverted logic is active.
 162
 163 Message must have type set to ``CNXK_GPIO_MSG_TYPE_GET_PIN_ACTIVE_LOW``.
 164
 165 Payload contains an integer set to 0 or 1. The latter means inverted logic
 166 is turned on.
 167
 168 Consider using ``rte_pmd_gpio_get_pin_active_low()`` wrapper.
 169
 170 Request interrupt
 171 ~~~~~~~~~~~~~~~~~
 172
 173 Message is used to install custom interrupt handler.
 174
 175 Message must have type set to ``CNXK_GPIO_MSG_TYPE_REGISTER_IRQ``.
 176
 177 Payload needs to be set to ``struct cnxk_gpio_irq`` which describes interrupt
 178 being requested.
 179
 180 Consider using ``rte_pmd_gpio_register_gpio()`` wrapper.
 181
 182 Free interrupt
 183 ~~~~~~~~~~~~~~
 184
 185 Message is used to remove installed interrupt handler.
 186
 187 Message must have type set to ``CNXK_GPIO_MSG_TYPE_UNREGISTER_IRQ``.
 188
 189 Consider using ``rte_pmd_gpio_unregister_gpio()`` wrapper.
 190
 191 Self test
 192 ---------
 193
 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.
 198
 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.