INSTALL.DPDK.md

   1 Using Open vSwitch with DPDK
   2 ============================
   3
   4 Open vSwitch can use Intel(R) DPDK lib to operate entirely in
   5 userspace. This file explains how to install and use Open vSwitch in
   6 such a mode.
   7
   8 The DPDK support of Open vSwitch is considered experimental.
   9 It has not been thoroughly tested.
  10
  11 This version of Open vSwitch should be built manually with `configure`
  12 and `make`.
  13
  14 OVS needs a system with 1GB hugepages support.
  15
  16 Building and Installing:
  17 ------------------------
  18
  19 Required DPDK 1.8.0
  20 Optional `fuse`, `fuse-devel`
  21
  22 1. Configure build & install DPDK:
  23   1. Set `$DPDK_DIR`
  24
  25      ```
  26      export DPDK_DIR=/usr/src/dpdk-1.8.0
  27      cd $DPDK_DIR
  28      ```
  29
  30   2. Update `config/common_linuxapp` so that DPDK generate single lib file.
  31      (modification also required for IVSHMEM build)
  32
  33      `CONFIG_RTE_BUILD_COMBINE_LIBS=y`
  34
  35      Then run `make install` to build and isntall the library.
  36      For default install without IVSHMEM:
  37
  38      `make install T=x86_64-native-linuxapp-gcc`
  39
  40      To include IVSHMEM (shared memory):
  41
  42      `make install T=x86_64-ivshmem-linuxapp-gcc`
  43
  44      For further details refer to http://dpdk.org/
  45
  46 2. Configure & build the Linux kernel:
  47
  48    Refer to intel-dpdk-getting-started-guide.pdf for understanding
  49    DPDK kernel requirement.
  50
  51 3. Configure & build OVS:
  52
  53    * Non IVSHMEM:
  54
  55      `export DPDK_BUILD=$DPDK_DIR/x86_64-native-linuxapp-gcc/`
  56
  57    * IVSHMEM:
  58
  59      `export DPDK_BUILD=$DPDK_DIR/x86_64-ivshmem-linuxapp-gcc/`
  60
  61    ```
  62    cd $(OVS_DIR)/openvswitch
  63    ./boot.sh
  64    ./configure --with-dpdk=$DPDK_BUILD
  65    make
  66    ```
  67
  68 To have better performance one can enable aggressive compiler optimizations and
  69 use the special instructions(popcnt, crc32) that may not be available on all
  70 machines. Instead of typing `make`, type:
  71
  72 `make CFLAGS='-O3 -march=native'`
  73
  74 Refer to [INSTALL.userspace.md] for general requirements of building userspace OVS.
  75
  76 Using the DPDK with ovs-vswitchd:
  77 ---------------------------------
  78
  79 1. Setup system boot
  80    Add the following options to the kernel bootline:
  81
  82    `default_hugepagesz=1GB hugepagesz=1G hugepages=1`
  83
  84 2. Setup DPDK devices:
  85
  86    DPDK devices can be setup using either the VFIO (for DPDK 1.7+) or UIO
  87    modules. UIO requires inserting an out of tree driver igb_uio.ko that is
  88    available in DPDK. Setup for both methods are described below.
  89
  90    * UIO:
  91      1. insert uio.ko: `modprobe uio`
  92      2. insert igb_uio.ko: `insmod $DPDK_BUILD/kmod/igb_uio.ko`
  93      3. Bind network device to igb_uio:
  94             `$DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio eth1`
  95
  96    * VFIO:
  97
  98      VFIO needs to be supported in the kernel and the BIOS. More information
  99      can be found in the [DPDK Linux GSG].
 100
 101      1. Insert vfio-pci.ko: `modprobe vfio-pci`
 102      2. Set correct permissions on vfio device: `sudo /usr/bin/chmod a+x /dev/vfio`
 103         and: `sudo /usr/bin/chmod 0666 /dev/vfio/*`
 104      3. Bind network device to vfio-pci:
 105             `$DPDK_DIR/tools/dpdk_nic_bind.py --bind=vfio-pci eth1`
 106
 107 3. Mount the hugetable filsystem
 108
 109    `mount -t hugetlbfs -o pagesize=1G none /dev/hugepages`
 110
 111    Ref to http://www.dpdk.org/doc/quick-start for verifying DPDK setup.
 112
 113 4. Follow the instructions in [INSTALL.md] to install only the
 114    userspace daemons and utilities (via 'make install').
 115    1. First time only db creation (or clearing):
 116
 117       ```
 118       mkdir -p /usr/local/etc/openvswitch
 119       mkdir -p /usr/local/var/run/openvswitch
 120       rm /usr/local/etc/openvswitch/conf.db
 121       ovsdb-tool create /usr/local/etc/openvswitch/conf.db  \
 122              /usr/local/share/openvswitch/vswitch.ovsschema
 123       ```
 124
 125    2. Start ovsdb-server
 126
 127       ```
 128       ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \
 129           --remote=db:Open_vSwitch,Open_vSwitch,manager_options \
 130           --private-key=db:Open_vSwitch,SSL,private_key \
 131           --certificate=Open_vSwitch,SSL,certificate \
 132           --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert --pidfile --detach
 133       ```
 134
 135     3. First time after db creation, initialize:
 136
 137        ```
 138        ovs-vsctl --no-wait init
 139        ```
 140
 141 5. Start vswitchd:
 142
 143    DPDK configuration arguments can be passed to vswitchd via `--dpdk`
 144    argument. This needs to be first argument passed to vswitchd process.
 145    dpdk arg -c is ignored by ovs-dpdk, but it is a required parameter
 146    for dpdk initialization.
 147
 148    ```
 149    export DB_SOCK=/usr/local/var/run/openvswitch/db.sock
 150    ovs-vswitchd --dpdk -c 0x1 -n 4 -- unix:$DB_SOCK --pidfile --detach
 151    ```
 152
 153    If allocated more than one GB hugepage (as for IVSHMEM), set amount and
 154    use NUMA node 0 memory:
 155
 156    ```
 157    ovs-vswitchd --dpdk -c 0x1 -n 4 --socket-mem 1024,0 \
 158    -- unix:$DB_SOCK --pidfile --detach
 159    ```
 160
 161 6. Add bridge & ports
 162
 163    To use ovs-vswitchd with DPDK, create a bridge with datapath_type
 164    "netdev" in the configuration database.  For example:
 165
 166    `ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev`
 167
 168    Now you can add dpdk devices. OVS expect DPDK device name start with dpdk
 169    and end with portid. vswitchd should print (in the log file) the number
 170    of dpdk devices found.
 171
 172    ```
 173    ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk
 174    ovs-vsctl add-port br0 dpdk1 -- set Interface dpdk1 type=dpdk
 175    ```
 176
 177    Once first DPDK port is added to vswitchd, it creates a Polling thread and
 178    polls dpdk device in continuous loop. Therefore CPU utilization
 179    for that thread is always 100%.
 180
 181 7. Add test flows
 182
 183    Test flow script across NICs (assuming ovs in /usr/src/ovs):
 184    Execute script:
 185
 186    ```
 187    #! /bin/sh
 188    # Move to command directory
 189    cd /usr/src/ovs/utilities/
 190
 191    # Clear current flows
 192    ./ovs-ofctl del-flows br0
 193
 194    # Add flows between port 1 (dpdk0) to port 2 (dpdk1)
 195    ./ovs-ofctl add-flow br0 in_port=1,action=output:2
 196    ./ovs-ofctl add-flow br0 in_port=2,action=output:1
 197    ```
 198
 199 8. Performance tuning
 200
 201    With pmd multi-threading support, OVS creates one pmd thread for each
 202    numa node as default.  The pmd thread handles the I/O of all DPDK
 203    interfaces on the same numa node.  The following two commands can be used
 204    to configure the multi-threading behavior.
 205
 206    `ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=<hex string>`
 207
 208    The command above asks for a CPU mask for setting the affinity of pmd
 209    threads.  A set bit in the mask means a pmd thread is created and pinned
 210    to the corresponding CPU core.  For more information, please refer to
 211    `man ovs-vswitchd.conf.db`
 212
 213    `ovs-vsctl set Open_vSwitch . other_config:n-dpdk-rxqs=<integer>`
 214
 215    The command above sets the number of rx queues of each DPDK interface. The
 216    rx queues are assigned to pmd threads on the same numa node in round-robin
 217    fashion.  For more information, please refer to `man ovs-vswitchd.conf.db`
 218
 219    Ideally for maximum throughput, the pmd thread should not be scheduled out
 220    which temporarily halts its execution. The following affinitization methods
 221    can help.
 222
 223    Lets pick core 4,6,8,10 for pmd threads to run on.  Also assume a dual 8 core
 224    sandy bridge system with hyperthreading enabled where CPU1 has cores 0,...,7
 225    and 16,...,23 & CPU2 cores 8,...,15 & 24,...,31.  (A different cpu
 226    configuration could have different core mask requirements).
 227
 228    To kernel bootline add core isolation list for cores and associated hype cores
 229    (e.g.  isolcpus=4,20,6,22,8,24,10,26,).  Reboot system for isolation to take
 230    effect, restart everything.
 231
 232    Configure pmd threads on core 4,6,8,10 using 'pmd-cpu-mask':
 233
 234    `ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=00000550`
 235
 236    You should be able to check that pmd threads are pinned to the correct cores
 237    via:
 238
 239    ```
 240    top -p `pidof ovs-vswitchd` -H -d1
 241    ```
 242
 243    Note, the pmd threads on a numa node are only created if there is at least
 244    one DPDK interface from the numa node that has been added to OVS.
 245
 246    Note, core 0 is always reserved from non-pmd threads and should never be set
 247    in the cpu mask.
 248
 249 DPDK Rings :
 250 ------------
 251
 252 Following the steps above to create a bridge, you can now add dpdk rings
 253 as a port to the vswitch.  OVS will expect the DPDK ring device name to
 254 start with dpdkr and end with a portid.
 255
 256 `ovs-vsctl add-port br0 dpdkr0 -- set Interface dpdkr0 type=dpdkr`
 257
 258 DPDK rings client test application
 259
 260 Included in the test directory is a sample DPDK application for testing
 261 the rings.  This is from the base dpdk directory and modified to work
 262 with the ring naming used within ovs.
 263
 264 location tests/ovs_client
 265
 266 To run the client :
 267
 268 ```
 269 cd /usr/src/ovs/tests/
 270 ovsclient -c 1 -n 4 --proc-type=secondary -- -n "port id you gave dpdkr"
 271 ```
 272
 273 In the case of the dpdkr example above the "port id you gave dpdkr" is 0.
 274
 275 It is essential to have --proc-type=secondary
 276
 277 The application simply receives an mbuf on the receive queue of the
 278 ethernet ring and then places that same mbuf on the transmit ring of
 279 the ethernet ring.  It is a trivial loopback application.
 280
 281 DPDK rings in VM (IVSHMEM shared memory communications)
 282 -------------------------------------------------------
 283
 284 In addition to executing the client in the host, you can execute it within
 285 a guest VM. To do so you will need a patched qemu.  You can download the
 286 patch and getting started guide at :
 287
 288 https://01.org/packet-processing/downloads
 289
 290 A general rule of thumb for better performance is that the client
 291 application should not be assigned the same dpdk core mask "-c" as
 292 the vswitchd.
 293
 294 DPDK vhost:
 295 -----------
 296
 297 vhost-cuse is only supported at present i.e. not using the standard QEMU
 298 vhost-user interface. It is intended that vhost-user support will be added
 299 in future releases when supported in DPDK and that vhost-cuse will eventually
 300 be deprecated. See [DPDK Docs] for more info on vhost.
 301
 302 Prerequisites:
 303 1.  DPDK 1.8 with vhost support enabled and recompile OVS as above.
 304
 305      Update `config/common_linuxapp` so that DPDK is built with vhost
 306      libraries:
 307
 308      `CONFIG_RTE_LIBRTE_VHOST=y`
 309
 310 2.  Insert the Cuse module:
 311
 312       `modprobe cuse`
 313
 314 3.  Build and insert the `eventfd_link` module:
 315
 316      `cd $DPDK_DIR/lib/librte_vhost/eventfd_link/`
 317      `make`
 318      `insmod $DPDK_DIR/lib/librte_vhost/eventfd_link.ko`
 319
 320 Following the steps above to create a bridge, you can now add DPDK vhost
 321 as a port to the vswitch.
 322
 323 `ovs-vsctl add-port br0 dpdkvhost0 -- set Interface dpdkvhost0 type=dpdkvhost`
 324
 325 Unlike DPDK ring ports, DPDK vhost ports can have arbitrary names:
 326
 327 `ovs-vsctl add-port br0 port123ABC -- set Interface port123ABC type=dpdkvhost`
 328
 329 However, please note that when attaching userspace devices to QEMU, the
 330 name provided during the add-port operation must match the ifname parameter
 331 on the QEMU command line.
 332
 333
 334 DPDK vhost VM configuration:
 335 ----------------------------
 336
 337    vhost ports use a Linux* character device to communicate with QEMU.
 338    By default it is set to `/dev/vhost-net`. It is possible to reuse this
 339    standard device for DPDK vhost, which makes setup a little simpler but it
 340    is better practice to specify an alternative character device in order to
 341    avoid any conflicts if kernel vhost is to be used in parallel.
 342
 343 1. This step is only needed if using an alternative character device.
 344
 345    The new character device filename must be specified on the vswitchd
 346    commandline:
 347
 348         `./vswitchd/ovs-vswitchd --dpdk --cuse_dev_name my-vhost-net -c 0x1 ...`
 349
 350    Note that the `--cuse_dev_name` argument and associated string must be the first
 351    arguments after `--dpdk` and come before the EAL arguments. In the example
 352    above, the character device to be used will be `/dev/my-vhost-net`.
 353
 354 2. This step is only needed if reusing the standard character device. It will
 355    conflict with the kernel vhost character device so the user must first
 356    remove it.
 357
 358        `rm -rf /dev/vhost-net`
 359
 360 3a. Configure virtio-net adaptors:
 361    The following parameters must be passed to the QEMU binary:
 362
 363      ```
 364      -netdev tap,id=<id>,script=no,downscript=no,ifname=<name>,vhost=on
 365      -device virtio-net-pci,netdev=net1,mac=<mac>
 366      ```
 367
 368      Repeat the above parameters for multiple devices.
 369
 370      The DPDK vhost library will negiotiate its own features, so they
 371      need not be passed in as command line params. Note that as offloads are
 372      disabled this is the equivalent of setting:
 373
 374      `csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off`
 375
 376 3b. If using an alternative character device. It must be also explicitly
 377     passed to QEMU using the `vhostfd` argument:
 378
 379      ```
 380      -netdev tap,id=<id>,script=no,downscript=no,ifname=<name>,vhost=on,
 381      vhostfd=<open_fd>
 382      -device virtio-net-pci,netdev=net1,mac=<mac>
 383      ```
 384
 385      The open file descriptor must be passed to QEMU running as a child
 386      process. This could be done with a simple python script.
 387
 388        ```
 389        #!/usr/bin/python
 390        fd = os.open("/dev/usvhost", os.O_RDWR)
 391        subprocess.call("qemu-system-x86_64 .... -netdev tap,id=vhostnet0,\
 392                         vhost=on,vhostfd=" + fd +"...", shell=True)
 393
 394    Alternatively the the `qemu-wrap.py` script can be used to automate the
 395    requirements specified above and can be used in conjunction with libvirt if
 396    desired. See the "DPDK vhost VM configuration with QEMU wrapper" section
 397    below.
 398
 399 4. Configure huge pages:
 400    QEMU must allocate the VM's memory on hugetlbfs. Vhost ports access a
 401    virtio-net device's virtual rings and packet buffers mapping the VM's
 402    physical memory on hugetlbfs. To enable vhost-ports to map the VM's
 403    memory into their process address space, pass the following paramters
 404    to QEMU:
 405
 406      `-object memory-backend-file,id=mem,size=4096M,mem-path=/dev/hugepages,
 407       share=on -numa node,memdev=mem -mem-prealloc`
 408
 409
 410 DPDK vhost VM configuration with QEMU wrapper:
 411 ----------------------------------------------
 412
 413 The QEMU wrapper script automatically detects and calls QEMU with the
 414 necessary parameters. It performs the following actions:
 415
 416   * Automatically detects the location of the hugetlbfs and inserts this
 417     into the command line parameters.
 418   * Automatically open file descriptors for each virtio-net device and
 419     inserts this into the command line parameters.
 420   * Calls QEMU passing both the command line parameters passed to the
 421     script itself and those it has auto-detected.
 422
 423 Before use, you **must** edit the configuration parameters section of the
 424 script to point to the correct emulator location and set additional
 425 settings. Of these settings, `emul_path` and `us_vhost_path` **must** be
 426 set. All other settings are optional.
 427
 428 To use directly from the command line simply pass the wrapper some of the
 429 QEMU parameters: it will configure the rest. For example:
 430
 431 ```
 432 qemu-wrap.py -cpu host -boot c -hda <disk image> -m 4096 -smp 4
 433   --enable-kvm -nographic -vnc none -net none -netdev tap,id=net1,
 434   script=no,downscript=no,ifname=if1,vhost=on -device virtio-net-pci,
 435   netdev=net1,mac=00:00:00:00:00:01
 436
 437 DPDK vhost VM configuration with libvirt:
 438 -----------------------------------------
 439
 440 If you are using libvirt, you must enable libvirt to access the character
 441 device by adding it to controllers cgroup for libvirtd using the following
 442 steps.
 443
 444      1. In `/etc/libvirt/qemu.conf` add/edit the following lines:
 445
 446         ```
 447         1) clear_emulator_capabilities = 0
 448         2) user = "root"
 449         3) group = "root"
 450         4) cgroup_device_acl = [
 451                "/dev/null", "/dev/full", "/dev/zero",
 452                "/dev/random", "/dev/urandom",
 453                "/dev/ptmx", "/dev/kvm", "/dev/kqemu",
 454                "/dev/rtc", "/dev/hpet", "/dev/net/tun",
 455                "/dev/<my-vhost-device>",
 456                "/dev/hugepages"]
 457         ```
 458
 459         <my-vhost-device> refers to "vhost-net" if using the `/dev/vhost-net`
 460         device. If you have specificed a different name on the ovs-vswitchd
 461         commandline using the "--cuse_dev_name" parameter, please specify that
 462         filename instead.
 463
 464      2. Disable SELinux or set to permissive mode
 465
 466      3. Restart the libvirtd process
 467         For example, on Fedora:
 468
 469           `systemctl restart libvirtd.service`
 470
 471 After successfully editing the configuration, you may launch your
 472 vhost-enabled VM. The XML describing the VM can be configured like so
 473 within the <qemu:commandline> section:
 474
 475      1. Set up shared hugepages:
 476
 477      ```
 478      <qemu:arg value='-object'/>
 479      <qemu:arg value='memory-backend-file,id=mem,size=4096M,mem-path=/dev/hugepages,share=on'/>
 480      <qemu:arg value='-numa'/>
 481      <qemu:arg value='node,memdev=mem'/>
 482      <qemu:arg value='-mem-prealloc'/>
 483      ```
 484
 485      2. Set up your tap devices:
 486
 487      ```
 488      <qemu:arg value='-netdev'/>
 489      <qemu:arg value='type=tap,id=net1,script=no,downscript=no,ifname=vhost0,vhost=on'/>
 490      <qemu:arg value='-device'/>
 491      <qemu:arg value='virtio-net-pci,netdev=net1,mac=00:00:00:00:00:01'/>
 492      ```
 493
 494      Repeat for as many devices as are desired, modifying the id, ifname
 495      and mac as necessary.
 496
 497      Again, if you are using an alternative character device (other than
 498      `/dev/vhost-net`), please specify the file descriptor like so:
 499
 500      `<qemu:arg value='type=tap,id=net3,script=no,downscript=no,ifname=vhost0,vhost=on,vhostfd=<open_fd>'/>`
 501
 502      Where <open_fd> refers to the open file descriptor of the character device.
 503      Instructions of how to retrieve the file descriptor can be found in the
 504      "DPDK vhost VM configuration" section.
 505      Alternatively, the process is automated with the qemu-wrap.py script,
 506      detailed in the next section.
 507
 508 Now you may launch your VM using virt-manager, or like so:
 509
 510     `virsh create my_vhost_vm.xml`
 511
 512 DPDK vhost VM configuration with libvirt and QEMU wrapper:
 513 ----------------------------------------------------------
 514
 515 To use the qemu-wrapper script in conjuntion with libvirt, follow the
 516 steps in the previous section before proceeding with the following steps:
 517
 518   1. Place `qemu-wrap.py` in libvirtd's binary search PATH ($PATH)
 519      Ideally in the same directory that the QEMU binary is located.
 520
 521   2. Ensure that the script has the same owner/group and file permissions
 522      as the QEMU binary.
 523
 524   3. Update the VM xml file using "virsh edit VM.xml"
 525
 526        1. Set the VM to use the launch script.
 527           Set the emulator path contained in the `<emulator><emulator/>` tags.
 528           For example, replace:
 529
 530             `<emulator>/usr/bin/qemu-kvm<emulator/>`
 531
 532             with:
 533
 534             `<emulator>/usr/bin/qemu-wrap.py<emulator/>`
 535
 536   4. Edit the Configuration Parameters section of the script to point to
 537   the correct emulator location and set any additional options. If you are
 538   using a alternative character device name, please set "us_vhost_path" to the
 539   location of that device. The script will automatically detect and insert
 540   the correct "vhostfd" value in the QEMU command line arguements.
 541
 542   5. Use virt-manager to launch the VM
 543
 544 Restrictions:
 545 -------------
 546
 547   - Work with 1500 MTU, needs few changes in DPDK lib to fix this issue.
 548   - Currently DPDK port does not make use any offload functionality.
 549   - DPDK-vHost support works with 1G huge pages.
 550
 551   ivshmem:
 552   - The shared memory is currently restricted to the use of a 1GB
 553     huge pages.
 554   - All huge pages are shared amongst the host, clients, virtual
 555     machines etc.
 556
 557 Bug Reporting:
 558 --------------
 559
 560 Please report problems to bugs@openvswitch.org.
 561
 562 [INSTALL.userspace.md]:INSTALL.userspace.md
 563 [INSTALL.md]:INSTALL.md
 564 [DPDK Linux GSG]: http://www.dpdk.org/doc/guides/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-igb-uioor-vfio-modules
 565 [DPDK Docs]: http://dpdk.org/doc