i386: Fix pkg_id offset for EPYC cpu models
[qemu.git] / docs / pvrdma.txt
1 Paravirtualized RDMA Device (PVRDMA)
2 ====================================
3
4
5 1. Description
6 ===============
7 PVRDMA is the QEMU implementation of VMware's paravirtualized RDMA device.
8 It works with its Linux Kernel driver AS IS, no need for any special guest
9 modifications.
10
11 While it complies with the VMware device, it can also communicate with bare
12 metal RDMA-enabled machines as peers.
13
14 It does not require an RDMA HCA in the host, it can work with Soft-RoCE (rxe).
15
16 It does not require the whole guest RAM to be pinned allowing memory
17 over-commit and, even if not implemented yet, migration support will be
18 possible with some HW assistance.
19
20 A project presentation accompany this document:
21 - http://events.linuxfoundation.org/sites/events/files/slides/lpc-2017-pvrdma-marcel-apfelbaum-yuval-shaia.pdf
22
23
24
25 2. Setup
26 ========
27
28
29 2.1 Guest setup
30 ===============
31 Fedora 27+ kernels work out of the box, older distributions
32 require updating the kernel to 4.14 to include the pvrdma driver.
33
34 However the libpvrdma library needed by User Level Software is still
35 not available as part of the distributions, so the rdma-core library
36 needs to be compiled and optionally installed.
37
38 Please follow the instructions at:
39   https://github.com/linux-rdma/rdma-core.git
40
41
42 2.2 Host Setup
43 ==============
44 The pvrdma backend is an ibdevice interface that can be exposed
45 either by a Soft-RoCE(rxe) device on machines with no RDMA device,
46 or an HCA SRIOV function(VF/PF).
47 Note that ibdevice interfaces can't be shared between pvrdma devices,
48 each one requiring a separate instance (rxe or SRIOV VF).
49
50
51 2.2.1 Soft-RoCE backend(rxe)
52 ===========================
53 A stable version of rxe is required, Fedora 27+ or a Linux
54 Kernel 4.14+ is preferred.
55
56 The rdma_rxe module is part of the Linux Kernel but not loaded by default.
57 Install the User Level library (librxe) following the instructions from:
58 https://github.com/SoftRoCE/rxe-dev/wiki/rxe-dev:-Home
59
60 Associate an ETH interface with rxe by running:
61    rxe_cfg add eth0
62 An rxe0 ibdevice interface will be created and can be used as pvrdma backend.
63
64
65 2.2.2 RDMA device Virtual Function backend
66 ==========================================
67 Nothing special is required, the pvrdma device can work not only with
68 Ethernet Links, but also Infinibands Links.
69 All is needed is an ibdevice with an active port, for Mellanox cards
70 will be something like mlx5_6 which can be the backend.
71
72
73 2.2.3 QEMU setup
74 ================
75 Configure QEMU with --enable-rdma flag, installing
76 the required RDMA libraries.
77
78
79
80 3. Usage
81 ========
82
83
84 3.1 VM Memory settings
85 ======================
86 Currently the device is working only with memory backed RAM
87 and it must be mark as "shared":
88    -m 1G \
89    -object memory-backend-ram,id=mb1,size=1G,share \
90    -numa node,memdev=mb1 \
91
92
93 3.2 MAD Multiplexer
94 ===================
95 MAD Multiplexer is a service that exposes MAD-like interface for VMs in
96 order to overcome the limitation where only single entity can register with
97 MAD layer to send and receive RDMA-CM MAD packets.
98
99 To build rdmacm-mux run
100 # make rdmacm-mux
101
102 Before running the rdmacm-mux make sure that both ib_cm and rdma_cm kernel
103 modules aren't loaded, otherwise the rdmacm-mux service will fail to start.
104
105 The application accepts 3 command line arguments and exposes a UNIX socket
106 to pass control and data to it.
107 -d rdma-device-name  Name of RDMA device to register with
108 -s unix-socket-path  Path to unix socket to listen (default /var/run/rdmacm-mux)
109 -p rdma-device-port  Port number of RDMA device to register with (default 1)
110 The final UNIX socket file name is a concatenation of the 3 arguments so
111 for example for device mlx5_0 on port 2 this /var/run/rdmacm-mux-mlx5_0-2
112 will be created.
113
114 pvrdma requires this service.
115
116 Please refer to contrib/rdmacm-mux for more details.
117
118
119 3.3 Service exposed by libvirt daemon
120 =====================================
121 The control over the RDMA device's GID table is done by updating the
122 device's Ethernet function addresses.
123 Usually the first GID entry is determined by the MAC address, the second by
124 the first IPv6 address and the third by the IPv4 address. Other entries can
125 be added by adding more IP addresses. The opposite is the same, i.e.
126 whenever an address is removed, the corresponding GID entry is removed.
127 The process is done by the network and RDMA stacks. Whenever an address is
128 added the ib_core driver is notified and calls the device driver add_gid
129 function which in turn update the device.
130 To support this in pvrdma device the device hooks into the create_bind and
131 destroy_bind HW commands triggered by pvrdma driver in guest.
132
133 Whenever changed is made to the pvrdma port's GID table a special QMP
134 messages is sent to be processed by libvirt to update the address of the
135 backend Ethernet device.
136
137 pvrdma requires that libvirt service will be up.
138
139
140 3.4 PCI devices settings
141 ========================
142 RoCE device exposes two functions - an Ethernet and RDMA.
143 To support it, pvrdma device is composed of two PCI functions, an Ethernet
144 device of type vmxnet3 on PCI slot 0 and a PVRDMA device on PCI slot 1. The
145 Ethernet function can be used for other Ethernet purposes such as IP.
146
147
148 3.5 Device parameters
149 =====================
150 - netdev: Specifies the Ethernet device function name on the host for
151   example enp175s0f0. For Soft-RoCE device (rxe) this would be the Ethernet
152   device used to create it.
153 - ibdev: The IB device name on host for example rxe0, mlx5_0 etc.
154 - mad-chardev: The name of the MAD multiplexer char device.
155 - ibport: In case of multi-port device (such as Mellanox's HCA) this
156   specify the port to use. If not set 1 will be used.
157 - dev-caps-max-mr-size: The maximum size of MR.
158 - dev-caps-max-qp:      Maximum number of QPs.
159 - dev-caps-max-cq:      Maximum number of CQs.
160 - dev-caps-max-mr:      Maximum number of MRs.
161 - dev-caps-max-pd:      Maximum number of PDs.
162 - dev-caps-max-ah:      Maximum number of AHs.
163
164 Notes:
165 - The first 3 parameters are mandatory settings, the rest have their
166   defaults.
167 - The last 8 parameters (the ones that prefixed by dev-caps) defines the top
168   limits but the final values is adjusted by the backend device limitations.
169 - netdev can be extracted from ibdev's sysfs
170   (/sys/class/infiniband/<ibdev>/device/net/)
171
172
173 3.6 Example
174 ===========
175 Define bridge device with vmxnet3 network backend:
176 <interface type='bridge'>
177   <mac address='56:b4:44:e9:62:dc'/>
178   <source bridge='bridge1'/>
179   <model type='vmxnet3'/>
180   <address type='pci' domain='0x0000' bus='0x00' slot='0x10' function='0x0' multifunction='on'/>
181 </interface>
182
183 Define pvrdma device:
184 <qemu:commandline>
185   <qemu:arg value='-object'/>
186   <qemu:arg value='memory-backend-ram,id=mb1,size=1G,share'/>
187   <qemu:arg value='-numa'/>
188   <qemu:arg value='node,memdev=mb1'/>
189   <qemu:arg value='-chardev'/>
190   <qemu:arg value='socket,path=/var/run/rdmacm-mux-rxe0-1,id=mads'/>
191   <qemu:arg value='-device'/>
192   <qemu:arg value='pvrdma,addr=10.1,ibdev=rxe0,netdev=bridge0,mad-chardev=mads'/>
193 </qemu:commandline>
194
195
196
197 4. Implementation details
198 =========================
199
200
201 4.1 Overview
202 ============
203 The device acts like a proxy between the Guest Driver and the host
204 ibdevice interface.
205 On configuration path:
206  - For every hardware resource request (PD/QP/CQ/...) the pvrdma will request
207    a resource from the backend interface, maintaining a 1-1 mapping
208    between the guest and host.
209 On data path:
210  - Every post_send/receive received from the guest will be converted into
211    a post_send/receive for the backend. The buffers data will not be touched
212    or copied resulting in near bare-metal performance for large enough buffers.
213  - Completions from the backend interface will result in completions for
214    the pvrdma device.
215
216
217 4.2 PCI BARs
218 ============
219 PCI Bars:
220         BAR 0 - MSI-X
221         MSI-X vectors:
222                 (0) Command - used when execution of a command is completed.
223                 (1) Async - not in use.
224                 (2) Completion - used when a completion event is placed in
225                   device's CQ ring.
226         BAR 1 - Registers
227         --------------------------------------------------------
228         | VERSION |  DSR | CTL | REQ | ERR |  ICR | IMR  | MAC |
229         --------------------------------------------------------
230                 DSR - Address of driver/device shared memory used
231               for the command channel, used for passing:
232                             - General info such as driver version
233                             - Address of 'command' and 'response'
234                             - Address of async ring
235                             - Address of device's CQ ring
236                             - Device capabilities
237                 CTL - Device control operations (activate, reset etc)
238                 IMG - Set interrupt mask
239                 REQ - Command execution register
240                 ERR - Operation status
241
242         BAR 2 - UAR
243         ---------------------------------------------------------
244         | QP_NUM  | SEND/RECV Flag ||  CQ_NUM |   ARM/POLL Flag |
245         ---------------------------------------------------------
246                 - Offset 0 used for QP operations (send and recv)
247                 - Offset 4 used for CQ operations (arm and poll)
248
249
250 4.3 Major flows
251 ===============
252
253 4.3.1 Create CQ
254 ===============
255     - Guest driver
256         - Allocates pages for CQ ring
257         - Creates page directory (pdir) to hold CQ ring's pages
258         - Initializes CQ ring
259         - Initializes 'Create CQ' command object (cqe, pdir etc)
260         - Copies the command to 'command' address
261         - Writes 0 into REQ register
262     - Device
263         - Reads the request object from the 'command' address
264         - Allocates CQ object and initialize CQ ring based on pdir
265         - Creates the backend CQ
266         - Writes operation status to ERR register
267         - Posts command-interrupt to guest
268     - Guest driver
269         - Reads the HW response code from ERR register
270
271 4.3.2 Create QP
272 ===============
273     - Guest driver
274         - Allocates pages for send and receive rings
275         - Creates page directory(pdir) to hold the ring's pages
276         - Initializes 'Create QP' command object (max_send_wr,
277           send_cq_handle, recv_cq_handle, pdir etc)
278         - Copies the object to 'command' address
279         - Write 0 into REQ register
280     - Device
281         - Reads the request object from 'command' address
282         - Allocates the QP object and initialize
283             - Send and recv rings based on pdir
284             - Send and recv ring state
285         - Creates the backend QP
286         - Writes the operation status to ERR register
287         - Posts command-interrupt to guest
288     - Guest driver
289         - Reads the HW response code from ERR register
290
291 4.3.3 Post receive
292 ==================
293     - Guest driver
294         - Initializes a wqe and place it on recv ring
295         - Write to qpn|qp_recv_bit (31) to QP offset in UAR
296     - Device
297         - Extracts qpn from UAR
298         - Walks through the ring and does the following for each wqe
299             - Prepares the backend CQE context to be used when
300               receiving completion from backend (wr_id, op_code, emu_cq_num)
301             - For each sge prepares backend sge
302             - Calls backend's post_recv
303
304 4.3.4 Process backend events
305 ============================
306     - Done by a dedicated thread used to process backend events;
307       at initialization is attached to the device and creates
308       the communication channel.
309     - Thread main loop:
310         - Polls for completions
311         - Extracts QEMU _cq_num, wr_id and op_code from context
312         - Writes CQE to CQ ring
313         - Writes CQ number to device CQ
314         - Sends completion-interrupt to guest
315         - Deallocates context
316         - Acks the event to backend
317
318
319
320 5. Limitations
321 ==============
322 - The device obviously is limited by the Guest Linux Driver features implementation
323   of the VMware device API.
324 - Memory registration mechanism requires mremap for every page in the buffer in order
325   to map it to a contiguous virtual address range. Since this is not the data path
326   it should not matter much. If the default max mr size is increased, be aware that
327   memory registration can take up to 0.5 seconds for 1GB of memory.
328 - The device requires target page size to be the same as the host page size,
329   otherwise it will fail to init.
330 - QEMU cannot map guest RAM from a file descriptor if a pvrdma device is attached,
331   so it can't work with huge pages. The limitation will be addressed in the future,
332   however QEMU allocates Guest RAM with MADV_HUGEPAGE so if there are enough huge
333   pages available, QEMU will use them. QEMU will fail to init if the requirements
334   are not met.
335
336
337
338 6. Performance
339 ==============
340 By design the pvrdma device exits on each post-send/receive, so for small buffers
341 the performance is affected; however for medium buffers it will became close to
342 bare metal and from 1MB buffers and  up it reaches bare metal performance.
343 (tested with 2 VMs, the pvrdma devices connected to 2 VFs of the same device)
344
345 All the above assumes no memory registration is done on data path.