samples/vfio-mdev/README.rst

   1 Using the mtty vfio-mdev sample code
   2 ====================================
   3
   4 mtty is a sample vfio-mdev driver that demonstrates how to use the mediated
   5 device framework.
   6
   7 The sample driver creates an mdev device that simulates a serial port over a PCI
   8 card.
   9
  10 1. 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
  42 2. 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
  48 3. Add parameters to qemu-kvm::
  49
  50      -device vfio-pci,\
  51       sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
  52
  53 4. 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
  82 5. 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
  89 6. Using minicom or any terminal emulation program, open port /dev/ttyS1 or
  90    /dev/ttyS2 with hardware flow control disabled.
  91
  92 7. 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
  97 8. Destroy the mediated device that you created::
  98
  99      # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
 100