doc: add virtio-gpio doc

add virtio-gpio doc

Signed-off-by: Gao Junhao <junhao.gao@intel.com>

Author: gaojunhao0504

doc/developer-guides/hld/hld-virtio-devices.rst

@@ -753,6 +753,8 @@ their temporary IDs are listed in the following table.
    +--------------+-------------+-------------+-------------+-------------+
    | I2C          | 0x8086      | 0x860a      | 0x8086      | 0xFFF6      |
    +--------------+-------------+-------------+-------------+-------------+
+   | GPIO         | 0x8086      | 0x8609      | 0x8086      | 0xFFF7      |
+   +--------------+-------------+-------------+-------------+-------------+
 
 The following sections introduce the status of virtio devices currently
 supported in ACRN.
@@ -766,3 +768,4 @@ supported in ACRN.
    virtio-console
    virtio-rnd
    virtio-i2c
+   virtio-gpio

doc/developer-guides/hld/images/virtio-gpio-1.png

@@ -0,0 +1,60 @@
+ .. _virtio-gpio:
+
+Virtio-gpio
+###########
+
+virtio-gpio provides a virtual GPIO controller, which will map part of native GPIOs to UOS, UOS can perform GPIO operations through it, including setting values, including set/get value, set/get direction and set configuration (only Open Source and Open Drain types are currently supported). GPIOs quite often be used as IRQs, typically for wakeup events,  virtio-gpio supports level and edge interrupt trigger modes.
+
+The virtio-gpio architecture is shown below
+
+.. figure:: images/virtio-gpio-1.png
+   :align: center
+   :name: virtio-gpio-1
+
+   Virtio-gpio Architecture
+
+Virtio-gpio is implemented as a virtio legacy device in the ACRN device model (DM), and is registered as a PCI virtio device to the guest OS. No changes are required in the frontend Linux virtio-gpio except that the guest (UOS) kernel should be built with ``CONFIG_VIRTIO_GPIO=y``.
+
+There are three virtqueues used between FE and BE, one for gpio operations, one for irq request and one for irq event notification.
+
+Virtio-gpio FE driver will register a gpiochip and irqchip when it is probed, the base and number of gpio are generated by the BE. Each gpiochip or irqchip operation(e.g. get_direction of gpiochip or irq_set_type of irqchip) will trigger a virtqueue_kick on its own virtqueue. If some gpio has been set to interrupt mode, the interrupt events will be handled within the irq virtqueue callback.
+
+GPIO mapping
+************
+
+.. figure:: images/virtio-gpio-2.png
+   :align: center
+   :name: virtio-gpio-2
+
+   GPIO mapping
+
+-  Each UOS has only one GPIO chip instance, its number of GPIO is based on acrn-dm command line and GPIO base always start from 0.
+
+-  Each GPIO is exclusive, uos can’t map the same native gpio.
+
+-  Each acrn-dm maximum number of GPIO is 64.
+
+Usage
+*****
+
+add the following parameters into command line::
+
+        -s <slot>,virtio-gpio,<@controller_name{offset|name[=mapping_name]:offset|name[=mapping_name]:…}@controller_name{…}…]>
+
+-  **controller_name**: Input “ls /sys/bus/gpio/devices” to check native gpio controller information.Usually, the devices represent the controller_name, you can use it as controller_name directly. You can also input “cat /sys/bus/gpio/device/XXX/dev” to get device id that can be used to match /dev/XXX, then use XXX as the controller_name. On MRB and NUC platforms, the controller_name are gpiochip0, gpiochip1, gpiochip2.gpiochip3.
+
+-  **offset|name**: you can use gpio offset or its name to locate one native gpio within the gpio controller.
+
+-  **mapping_name**: This is optional, if you want to use a customized name for a FE gpio, you can set a new name for a FE virtual gpio.
+
+Example
+*******
+
+-  Map three native gpio to UOS, they are native gpiochip0 with offset of 1 and 6, and with the name “reset”. In UOS, the three gpio has no name, and base from 0.::
+
+        -s 10,virtio-gpio,@gpiochip0{1:6:reset}
+
+-  Map four native gpio to UOS, native gpiochip0’s gpio with offset 1 and offset 6 map to FE virtual gpio with offset 0 and offset 1 without names, native gpiochip0’s gpio with name “reset” maps to FE virtual gpio with offset 2 and its name is “shutdown”, native gpiochip1’s gpio with offset 0 maps to FE virtual gpio with offset 3 and its name is “reset”.::
+        
+        -s 10,virtio-gpio,@gpiochip0{1:6:reset=shutdown}@gpiochip1{0=reset}
+