vmm: refactor userspace's emsr_fakewrite()
[akaros.git] / Documentation / iommu.md
1 I/O MMU
2 =======
3 **2019-08-15** Aditya Basu (`mitthu`)
4
5 Contents
6 -------------------------------
7 + Acronyms
8 + I/O MMU Workings
9     - IOTLB shootdowns
10 + Running Akaros in QEMU
11 + Example Interaction via sysfs
12
13 Acronyms
14 -------------------------------
15 + IEC:  Interrupt Entry Cache
16 + RWBF: Required Write-Buffer Flushing
17 + IVT:  Invalidate IOTLB
18
19 I/O MMU Workings
20 -------------------------------
21
22 ### IOTLB Shootdowns / flushing
23
24 * If RWBF set in capability, then perform write buffer flushing.
25 * If IOTLB is present, then we can perform one of the following:
26     + global shootdown
27     + DID specific shootdown (We perform this!)
28     + page-specific shootdown for a specific DID
29
30 Running Akaors in QEMU
31 -------------------------------
32 * Currently running in QEMU requires a recompilation. This is to allow 4-level
33   paging for the IOMMU. Do the following:
34     - For qemu version 4.0.50, we need to modify line 52 of
35       "include/hw/i386/intel_iommu.h".
36     - The macro `VTD_HOST_ADDRESS_WIDTH` will be `VTD_HOST_AW_39BIT`. Change it
37       to `VTD_HOST_AW_48BIT` and recompile.
38
39 ```bash
40 # Prepare device for passthrough (on Linux host)
41 # - unbind from existing driver
42 # - make sure the VFIO module is loaded
43 # - make sure all virtual functions are released by the driver
44 # - bind to VFIO driver for passthrough
45 $ PCIDEVICE_BDF=0000:00:04.*
46 $ echo $(PCIDEVICE_BDF) | sudo tee /sys/bus/pci/devices/$(PCIDEVICE_BDF)/driver/unbind
47 $ sudo modprobe vfio-pci
48 $ sudo rmmod ioatdma
49 $ echo $(PCIDEVICE_ID) | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id
50
51 # Standard run
52 $ sudo $(QEMU) \
53     -enable-kvm \
54     -cpu host \
55     -smp 8 \
56     -m 4096 \
57     -nographic \
58     -net nic,model=e1000 \
59     -net user,hostfwd=tcp::5555-:22 \
60     -machine q35,accel=kvm,kernel-irqchip=split \
61     -device intel-iommu,intremap=off,caching-mode=on,device-iotlb=on \
62     -device vfio-pci,host=00:04.0 \
63     -kernel obj/kern/akaros-kernel
64
65 # Trace QEMU calls (for debugging)
66 $ echo -n '' >/tmp/qemu-trace
67 $ echo 'vfio_pci_read_config' >>/tmp/qemu-trace
68 $ echo 'vfio_pci_write_config' >>/tmp/qemu-trace
69 $ echo 'vfio_region_read' >>/tmp/qemu-trace
70 $ echo 'vfio_region_write' >>/tmp/qemu-trace
71 $ echo 'pci_data_read' >>/tmp/qemu-trace
72
73 $ sudo $(QEMU) \
74     -trace events=/tmp/qemu-trace \
75     -enable-kvm \
76     -cpu host \
77     -smp 8 \
78     -m 4096 \
79     -nographic \
80     -net nic,model=e1000 \
81     -net user,hostfwd=tcp::5555-:22 \
82     -device vfio-pci,host=00:04.0 \
83     -kernel obj/kern/akaros-kernel
84 ```
85
86 Example Interaction via sysfs
87 -------------------------------
88 ```bash
89 # Mount the device
90 bash-4.3$ mkdir -p /sys/iommu
91 bash-4.3$ /bin/bind \#iommu /sys/iommu
92 bash-4.3$ cd /sys/iommu/
93
94 # All files
95 bash-4.3$ ls
96 attach    detach    info      mappings  power
97
98 # Attach devices
99 bash-4.3$ echo 0:3.0 1 >attach
100 bash-4.3$ echo 0:0.0 22 >attach
101 bash-4.3$ echo 0:1:0 22 >attach
102 bash-4.3$ echo 0:2.0 26 >attach
103
104 # Display mappings
105 bash-4.3$ cat mappings
106 Mappings for iommu@0xffff8001090acce8
107         pid = 1
108                 device = 0:3.0
109         pid = 22
110                 device = 0:0.0
111                 device = 0:1.0
112         pid = 26
113                 device = 0:2.0
114
115 # Detach devices
116 bash-4.3$ echo 0:2.0 >detach
117 bash-4.3$ echo 0:1:0 >detach
118 bash-4.3$ cat mappings
119 Mappings for iommu@0xffff8001090acce8
120         pid = 1
121                 device = 0:3.0
122         pid = 22
123                 device = 0:0.0
124
125 # Display IOMMU information
126 bash-4.3$ cat info
127 driver info:
128         default did = 1
129         status = enabled
130
131 iommu@0xffff8001090ab0e8
132         rba = 0x00000000fed90000
133         supported = yes
134         num_assigned_devs = 0
135         regspace = 0xfffffff000000000
136         host addr width (dmar) = 48
137         host addr width (cap[mgaw]) = 48
138         version = 0x10
139         capabilities = 0x00d2008c222f0686
140                 mgaw: 48
141                 sagaw (paging level): 0x6
142                 caching mode: yes (1)
143                 zlr: 0x0
144                 rwbf: not required
145                 num domains: 65536
146                 supports protected high-memory region: no
147                 supports Protected low-memory region: no
148         ext. capabilities = 0x0000000000000f46
149                 pass through: yes
150                 device iotlb: yes
151                 iotlb register offset: 0xf0
152                 snoop control: no
153                 coherency: no
154                 queue invalidation support: yes
155                 interrupt remapping support: no
156                 extended interrupt mode: 0x0
157         global status = 0xc0000000
158                 translation: enabled
159                 root table: set
160         root entry table = 0x00000001090aa000 (phy) or 0xffff8001090aa000 (vir)
161
162 # Turn off IOMMU (global)
163 bash-4.3$ cat power
164 IOMMU status: enabled
165 Write 'enable' or 'disable' OR 'on' or 'off' to change status
166
167 bash-4.3$ echo -n off >power
168
169 bash-4.3$ cat power
170 IOMMU status: disabled
171 Write 'enable' or 'disable' OR 'on' or 'off' to change status
172 ```