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