1 .. _virtio-gpio:
2
3Virtio-GPIO
4###########
5
6Virtio-gpio provides a virtual general-purpose input/output (GPIO) controller
7that can map native GPIOs to a User VM. The User VM can perform GPIO operations
8through it, including set value, get value, set direction, get direction, and
9set configuration. Only Open Source and Open Drain types are
10supported. GPIOs are often used as IRQs, typically for wakeup events.
11Virtio-gpio supports level and edge interrupt trigger modes.
12
13The virtio-gpio architecture is shown below:
14
15.. figure:: images/virtio-gpio-1.png
16   :align: center
17   :name: virtio-gpio-1
18
19   Virtio-gpio Architecture
20
21Virtio-gpio is implemented as a virtio legacy device in the ACRN Device
22Model (DM), and is registered as a PCI virtio device to the guest OS. No
23changes are required in the frontend Linux virtio-gpio except that the
24guest (User VM) kernel should be built with ``CONFIG_VIRTIO_GPIO=y``.
25
26Three virtqueues are used between FE and BE, one for GPIO
27operations, one for IRQ requests, and one for IRQ event notification.
28
29The virtio-gpio FE driver registers a gpiochip and irqchip when it is
30probed. BE generates the base and number of GPIOs. Each
31gpiochip or irqchip operation (for example, get_direction of gpiochip or
32irq_set_type of irqchip) triggers a virtqueue_kick on its own
33virtqueue. If a GPIO has been set to interrupt mode, the interrupt
34events are handled within the IRQ virtqueue callback.
35
36GPIO Mapping
37************
38
39.. figure:: images/virtio-gpio-2.png
40   :align: center
41   :name: virtio-gpio-2
42
43   GPIO Mapping
44
45-  Each User VM has only one GPIO chip instance. The number of GPIOs is
46   based on the acrn-dm command line. The GPIO base always starts from 0.
47
48-  Each GPIO is exclusive. A User VM can't map the same native GPIO.
49
50-  For each acrn-dm, the maximum number of GPIOs is 64.
51
52Usage
53*****
54
55Add the following parameters into the command line::
56
57        -s <slot>,virtio-gpio,<@controller_name{offset|name[=mapping_name]:offset|name[=mapping_name]:...}@controller_name{...}...]>
58
59-  **controller_name**: Input ``ls /sys/bus/gpio/devices`` to check native
60   GPIO controller information. Usually, the devices represent the
61   controller_name, and you can use it as controller_name directly. You can
62   also input ``cat /sys/bus/gpio/device/XXX/dev`` to get a device ID that can
63   be used to match ``/dev/XXX``, then use XXX as the controller_name. On MRB
64   and Intel NUC platforms, the controller_name values are gpiochip0, gpiochip1,
65   gpiochip2.gpiochip3.
66
67-  **offset|name**: You can use the GPIO offset or its name to locate one
68   native GPIO within the GPIO controller.
69
70-  **mapping_name**: This parameter is optional. If you want to use a customized
71   name for a FE GPIO, you can set a new name for a FE virtual GPIO.
72
73Example
74*******
75
76-  Map three native GPIOs to the User VM. They are native gpiochip0 with
77   offset of 1 and 6, and with the name ``reset``. In the User VM, the three
78   GPIOs have no name, and base starts from 0::
79
80        -s 10,virtio-gpio,@gpiochip0{1:6:reset}
81
82-  Map four native GPIOs to the User VM. The native gpiochip0's GPIO with offset
83   1 and offset 6 map to FE virtual GPIO with offset 0 and offset 1 without
84   names. The native gpiochip0's GPIO with name ``reset`` maps to FE virtual
85   GPIO with offset 2 and its name is ``shutdown``. The native gpiochip1's GPIO
86   with offset 0 maps to FE virtual GPIO with offset 3 and its name is
87   ``reset``::
88
89        -s 10,virtio-gpio,@gpiochip0{1:6:reset=shutdown}@gpiochip1{0=reset}
90