README.rst
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
101