doc/guides/howto/vfd.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31
  32 VF daemon (VFd)
  33 ===============
  34
  35 VFd (the VF daemon) is a mechanism which can be used to configure features on
  36 a VF (SR-IOV Virtual Function) without direct access to the PF (SR-IOV
  37 Physical Function). VFd is an *EXPERIMENTAL* feature which can only be used in
  38 the scenario of DPDK PF with a DPDK VF. If the PF port is driven by the Linux
  39 kernel driver then the VFd feature will not work. Currently VFd is only
  40 supported by the ixgbe and i40e drivers.
  41
  42 In general VF features cannot be configured directly by an end user
  43 application since they are under the control of the PF. The normal approach to
  44 configuring a feature on a VF is that an application would call the APIs
  45 provided by the VF driver. If the required feature cannot be configured by the
  46 VF directly (the most common case) the VF sends a message to the PF through
  47 the mailbox on ixgbe and i40e. This means that the availability of the feature
  48 depends on whether the appropriate mailbox messages are defined.
  49
  50 DPDK leverages the mailbox interface defined by the Linux kernel driver so
  51 that compatibility with the kernel driver can be guaranteed. The downside of
  52 this approach is that the availability of messages supported by the kernel
  53 become a limitation when the user wants to configure features on the VF.
  54
  55 VFd is a new method of controlling the features on a VF. The VF driver doesn't
  56 talk directly to the PF driver when configuring a feature on the VF. When a VF
  57 application (i.e., an application using the VF ports) wants to enable a VF
  58 feature, it can send a message to the PF application (i.e., the application
  59 using the PF port, which can be the same as the VF application). The PF
  60 application will configure the feature for the VF. Obviously, the PF
  61 application can also configure the VF features without a request from the VF
  62 application.
  63
  64 .. _VF_daemon_overview:
  65
  66 .. figure:: img/vf_daemon_overview.*
  67
  68    VF daemon (VFd) Overview
  69
  70 Compared with the traditional approach the VFd moves the negotiation between
  71 VF and PF from the driver level to application level. So the application
  72 should define how the negotiation between the VF and PF works, or even if the
  73 control should be limited to the PF.
  74
  75 It is the application's responsibility to use VFd. Consider for example a KVM
  76 migration, the VF application may transfer from one VM to another. It is
  77 recommended in this case that the PF control the VF features without
  78 participation from the VF. Then the VF application has no capability to
  79 configure the features. So the user doesn't need to define the interface
  80 between the VF application and the PF application. The service provider should
  81 take the control of all the features.
  82
  83 The following sections describe the VFd functionality.
  84
  85 .. Note::
  86
  87    Although VFd is supported by both ixgbe and i40e, please be aware that
  88    since the hardware capability is different, the functions supported by
  89    ixgbe and i40e are not the same.
  90
  91
  92 Preparing
  93 ---------
  94
  95 VFd only can be used in the scenario of DPDK PF + DPDK VF. Users should bind
  96 the PF port to ``igb_uio``, then create the VFs based on the DPDK PF host.
  97
  98 The typical procedure to achieve this is as follows:
  99
 100 #. Boot the system without iommu, or with ``iommu=pt``.
 101
 102 #. Bind the PF port to ``igb_uio``, for example::
 103
 104       dpdk-devbind.py -b igb_uio 01:00.0
 105
 106 #. Create a Virtual Function::
 107
 108       echo 1 > /sys/bus/pci/devices/0000:01:00.0/max_vfs
 109
 110 #. Start a VM with the new VF port bypassed to it.
 111
 112 #. Run a DPDK application on the PF in the host::
 113
 114       testpmd -l 0-7 -n 4 -- -i --txqflags=0
 115
 116 #. Bind the VF port to ``igb_uio`` in the VM::
 117
 118       dpdk-devbind.py -b igb_uio 03:00.0
 119
 120 #. Run a DPDK application on the VF in the VM::
 121
 122       testpmd -l 0-7 -n 4 -- -i --txqflags=0
 123
 124
 125 Common functions of IXGBE and I40E
 126 ----------------------------------
 127
 128 The following sections show how to enable PF/VF functionality based on the
 129 above testpmd setup.
 130
 131
 132 TX loopback
 133 ~~~~~~~~~~~
 134
 135 Run a testpmd runtime command on the PF to set TX loopback::
 136
 137    set tx loopback 0 on|off
 138
 139 This sets whether the PF port and all the VF ports that belong to it are
 140 allowed to send the packets to other virtual ports.
 141
 142 Although it is a VFd function, it is the global setting for the whole
 143 physical port. When using this function, the PF and all the VFs TX loopback
 144 will be enabled/disabled.
 145
 146
 147 VF MAC address setting
 148 ~~~~~~~~~~~~~~~~~~~~~~
 149
 150 Run a testpmd runtime command on the PF to set the MAC address for a VF port::
 151
 152    set vf mac addr 0 0 A0:36:9F:7B:C3:51
 153
 154 This testpmd runtime command will change the MAC address of the VF port to
 155 this new address. If any other addresses are set before, they will be
 156 overwritten.
 157
 158
 159 VF MAC anti-spoofing
 160 ~~~~~~~~~~~~~~~~~~~~
 161
 162 Run a testpmd runtime command on the PF to enable/disable the MAC
 163 anti-spoofing for a VF port::
 164
 165    set vf mac antispoof 0 0 on|off
 166
 167 When enabling the MAC anti-spoofing, the port will not forward packets whose
 168 source MAC address is not the same as the port.
 169
 170
 171 VF VLAN anti-spoofing
 172 ~~~~~~~~~~~~~~~~~~~~~
 173
 174 Run a testpmd runtime command on the PF to enable/disable the VLAN
 175 anti-spoofing for a VF port::
 176
 177    set vf vlan antispoof 0 0 on|off
 178
 179 When enabling the VLAN anti-spoofing, the port will not send packets whose
 180 VLAN ID does not belong to VLAN IDs that this port can receive.
 181
 182
 183 VF VLAN insertion
 184 ~~~~~~~~~~~~~~~~~
 185
 186 Run a testpmd runtime command on the PF to set the VLAN insertion for a VF
 187 port::
 188
 189    set vf vlan insert 0 0 1
 190
 191 When using this testpmd runtime command, an assigned VLAN ID can be inserted
 192 to the transmitted packets by the hardware.
 193
 194 The assigned VLAN ID can be 0. It means disabling the VLAN insertion.
 195
 196
 197 VF VLAN stripping
 198 ~~~~~~~~~~~~~~~~~
 199
 200 Run a testpmd runtime command on the PF to enable/disable the VLAN stripping
 201 for a VF port::
 202
 203    set vf vlan stripq 0 0 on|off
 204
 205 This testpmd runtime command is used to enable/disable the RX VLAN stripping
 206 for a specific VF port.
 207
 208
 209 VF VLAN filtering
 210 ~~~~~~~~~~~~~~~~~
 211
 212 Run a testpmd runtime command on the PF to set the VLAN filtering for a VF
 213 port::
 214
 215    rx_vlan add 1 port 0 vf 1
 216    rx_vlan rm  1 port 0 vf 1
 217
 218 These two testpmd runtime commands can be used to add or remove the VLAN
 219 filter for several VF ports. When the VLAN filters are added only the packets
 220 that have the assigned VLAN IDs can be received. Other packets will be dropped
 221 by hardware.
 222
 223
 224 The IXGBE specific VFd functions
 225 --------------------------------
 226
 227 The functions in this section are specific to the ixgbe driver.
 228
 229
 230 All queues drop
 231 ~~~~~~~~~~~~~~~
 232
 233 Run a testpmd runtime command on the PF to enable/disable the all queues
 234 drop::
 235
 236    set all queues drop on|off
 237
 238 This is a global setting for the PF and all the VF ports of the physical port.
 239
 240 Enabling the ``all queues drop`` feature means that when there is no available
 241 descriptor for the received packets they are dropped. The ``all queues drop``
 242 feature should be enabled in SR-IOV mode to avoid one queue blocking others.
 243
 244
 245 VF packet drop
 246 ~~~~~~~~~~~~~~
 247
 248 Run a testpmd runtime command on the PF to enable/disable the packet drop for
 249 a specific VF::
 250
 251    set vf split drop 0 0 on|off
 252
 253 This is a similar function as ``all queues drop``. The difference is that this
 254 function is per VF setting and the previous function is a global setting.
 255
 256
 257 VF rate limit
 258 ~~~~~~~~~~~~~
 259
 260 Run a testpmd runtime command on the PF to all queues' rate limit for a
 261 specific VF::
 262
 263    set port 0 vf 0 rate 10 queue_mask 1
 264
 265 This is a function to set the rate limit for all the queues in the
 266 ``queue_mask`` bitmap. It is not used to set the summary of the rate
 267 limit. The rate limit of every queue will be set equally to the assigned rate
 268 limit.
 269
 270
 271 VF RX enabling
 272 ~~~~~~~~~~~~~~
 273
 274 Run a testpmd runtime command on the PF to enable/disable packet receiving for
 275 a specific VF::
 276
 277    set port 0 vf 0 rx on|off
 278
 279 This function can be used to stop/start packet receiving on a VF.
 280
 281
 282 VF TX enabling
 283 ~~~~~~~~~~~~~~
 284
 285 Run a testpmd runtime command on the PF to enable/disable packet transmitting
 286 for a specific VF::
 287
 288    set port 0 vf 0 tx on|off
 289
 290 This function can be used to stop/start packet transmitting on a VF.
 291
 292
 293 VF RX mode setting
 294 ~~~~~~~~~~~~~~~~~~
 295
 296 Run a testpmd runtime command on the PF to set the RX mode for a specific VF::
 297
 298    set port 0 vf 0 rxmode AUPE|ROPE|BAM|MPE on|off
 299
 300 This function can be used to enable/disable some RX modes on the VF, including:
 301
 302 * If it accept untagged packets.
 303 * If it accepts packets matching the MAC filters.
 304 * If it accept MAC broadcast packets,
 305 * If it enables MAC multicast promiscuous mode.
 306
 307
 308 The I40E specific VFd functions
 309 -------------------------------
 310
 311 The functions in this section are specific to the i40e driver.
 312
 313
 314 VF statistics
 315 ~~~~~~~~~~~~~
 316
 317 This provides an API to get the a specific VF's statistic from PF.
 318
 319
 320 VF statistics resetting
 321 ~~~~~~~~~~~~~~~~~~~~~~~
 322
 323 This provides an API to rest the a specific VF's statistic from PF.
 324
 325
 326 VF link status change notification
 327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 328
 329 This provide an API to let a specific VF know if the physical link status
 330 changed.
 331
 332 Normally if a VF received this notification, the driver should notify the
 333 application to reset the VF port.
 334
 335
 336 VF MAC broadcast setting
 337 ~~~~~~~~~~~~~~~~~~~~~~~~
 338
 339 Run a testpmd runtime command on the PF to enable/disable MAC broadcast packet
 340 receiving for a specific VF::
 341
 342    set vf broadcast 0 0 on|off
 343
 344
 345 VF MAC multicast promiscuous mode
 346 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 347
 348 Run a testpmd runtime command on the PF to enable/disable MAC multicast
 349 promiscuous mode for a specific VF::
 350
 351    set vf allmulti 0 0 on|off
 352
 353
 354 VF MAC unicast promiscuous mode
 355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 356
 357 Run a testpmd runtime command on the PF to enable/disable MAC unicast
 358 promiscuous mode for a specific VF::
 359
 360    set vf promisc 0 0 on|off
 361
 362
 363 VF max bandwidth
 364 ~~~~~~~~~~~~~~~~
 365
 366 Run a testpmd runtime command on the PF to set the TX maximum bandwidth for a
 367 specific VF::
 368
 369    set vf tx max-bandwidth 0 0 2000
 370
 371 The maximum bandwidth is an absolute value in Mbps.
 372
 373
 374 VF TC bandwidth allocation
 375 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 376
 377 Run a testpmd runtime command on the PF to set the TCs (traffic class) TX
 378 bandwidth allocation for a specific VF::
 379
 380    set vf tc tx min-bandwidth 0 0 (20,20,20,40)
 381
 382 The allocated bandwidth should be set for all the TCs. The allocated bandwidth
 383 is a relative value as a percentage. The sum of all the bandwidth should
 384 be 100.
 385
 386
 387 VF TC max bandwidth
 388 ~~~~~~~~~~~~~~~~~~~
 389
 390 Run a testpmd runtime command on the PF to set the TCs TX maximum bandwidth
 391 for a specific VF::
 392
 393    set vf tc tx max-bandwidth 0 0 0 10000
 394
 395 The maximum bandwidth is an absolute value in Mbps.
 396
 397
 398 TC strict priority scheduling
 399 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 400
 401 Run a testpmd runtime command on the PF to enable/disable several TCs TX
 402 strict priority scheduling::
 403
 404    set tx strict-link-priority 0 0x3
 405
 406 The 0 in the TC bitmap means disabling the strict priority scheduling for this
 407 TC. To enable use a value of 1.