1Using the mtty vfio-mdev sample code
  2====================================
  3
  4mtty is a sample vfio-mdev driver that demonstrates how to use the mediated
  5device framework.
  6
  7The sample driver creates an mdev device that simulates a serial port over a PCI
  8card.
  9
 101. Build and load the mtty.ko module.
 11
 12   This step creates a dummy device, /sys/devices/virtual/mtty/mtty/
 13
 14   Files in this device directory in sysfs are similar to the following::
 15
 16     # tree /sys/devices/virtual/mtty/mtty/
 17        /sys/devices/virtual/mtty/mtty/
 18        |-- mdev_supported_types
 19        |   |-- mtty-1
 20        |   |   |-- available_instances
 21        |   |   |-- create
 22        |   |   |-- device_api
 23        |   |   |-- devices
 24        |   |   `-- name
 25        |   `-- mtty-2
 26        |       |-- available_instances
 27        |       |-- create
 28        |       |-- device_api
 29        |       |-- devices
 30        |       `-- name
 31        |-- mtty_dev
 32        |   `-- sample_mtty_dev
 33        |-- power
 34        |   |-- autosuspend_delay_ms
 35        |   |-- control
 36        |   |-- runtime_active_time
 37        |   |-- runtime_status
 38        |   `-- runtime_suspended_time
 39        |-- subsystem -> ../../../../class/mtty
 40        `-- uevent
 41
 422. Create a mediated device by using the dummy device that you created in the
 43   previous step::
 44
 45     # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
 46              /sys/devices/virtual/mtty/mtty/mdev_supported_types/mtty-2/create
 47
 483. Add parameters to qemu-kvm::
 49
 50     -device vfio-pci,\
 51      sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
 52
 534. Boot the VM.
 54
 55   In the Linux guest VM, with no hardware on the host, the device appears
 56   as  follows::
 57
 58     # lspci -s 00:05.0 -xxvv
 59     00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
 60             Subsystem: Device 4348:3253
 61             Physical Slot: 5
 62             Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
 63     Stepping- SERR- FastB2B- DisINTx-
 64             Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
 65     <TAbort- <MAbort- >SERR- <PERR- INTx-
 66             Interrupt: pin A routed to IRQ 10
 67             Region 0: I/O ports at c150 [size=8]
 68             Region 1: I/O ports at c158 [size=8]
 69             Kernel driver in use: serial
 70     00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
 71     10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
 72     20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
 73     30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
 74
 75     In the Linux guest VM, dmesg output for the device is as follows:
 76
 77     serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ 10
 78     0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
 79     0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
 80
 81
 825. In the Linux guest VM, check the serial ports::
 83
 84     # setserial -g /dev/ttyS*
 85     /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
 86     /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
 87     /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
 88
 896. Using minicom or any terminal emulation program, open port /dev/ttyS1 or
 90   /dev/ttyS2 with hardware flow control disabled.
 91
 927. Type data on the minicom terminal or send data to the terminal emulation
 93   program and read the data.
 94
 95   Data is loop backed from hosts mtty driver.
 96
 978. Destroy the mediated device that you created::
 98
 99     # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
100