diff options
Diffstat (limited to 'doc/guides/sample_app_ug')
| -rw-r--r-- | doc/guides/sample_app_ug/eventdev_pipeline_sw_pmd.rst | 190 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/index.rst | 2 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/ipsec_secgw.rst | 51 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/ipv4_multicast.rst | 8 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/l2_forward_crypto.rst | 78 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/vhost_scsi.rst | 115 |
6 files changed, 415 insertions, 29 deletions
diff --git a/doc/guides/sample_app_ug/eventdev_pipeline_sw_pmd.rst b/doc/guides/sample_app_ug/eventdev_pipeline_sw_pmd.rst new file mode 100644 index 00000000..b1b18dd0 --- /dev/null +++ b/doc/guides/sample_app_ug/eventdev_pipeline_sw_pmd.rst @@ -0,0 +1,190 @@ + +.. BSD LICENSE + Copyright(c) 2017 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Eventdev Pipeline SW PMD Sample Application +=========================================== + +The eventdev pipeline sample application is a sample app that demonstrates +the usage of the eventdev API using the software PMD. It shows how an +application can configure a pipeline and assign a set of worker cores to +perform the processing required. + +The application has a range of command line arguments allowing it to be +configured for various numbers worker cores, stages,queue depths and cycles per +stage of work. This is useful for performance testing as well as quickly testing +a particular pipeline configuration. + + +Compiling the Application +------------------------- + +To compile the application: + +#. Go to the sample application directory: + + .. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + cd ${RTE_SDK}/examples/eventdev_pipeline_sw_pmd + +#. Set the target (a default target is used if not specified). For example: + + .. code-block:: console + + export RTE_TARGET=x86_64-native-linuxapp-gcc + + See the *DPDK Getting Started Guide* for possible RTE_TARGET values. + +#. Build the application: + + .. code-block:: console + + make + +Running the Application +----------------------- + +The application has a lot of command line options. This allows specification of +the eventdev PMD to use, and a number of attributes of the processing pipeline +options. + +An example eventdev pipeline running with the software eventdev PMD using +these settings is shown below: + + * ``-r1``: core mask 0x1 for RX + * ``-t1``: core mask 0x1 for TX + * ``-e4``: core mask 0x4 for the software scheduler + * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th + * ``-s4``: 4 atomic stages + * ``-n0``: process infinite packets (run forever) + * ``-c32``: worker dequeue depth of 32 + * ``-W1000``: do 1000 cycles of work per packet in each stage + * ``-D``: dump statistics on exit + +.. code-block:: console + + ./build/eventdev_pipeline_sw_pmd --vdev event_sw0 -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D + +The application has some sanity checking built-in, so if there is a function +(eg; the RX core) which doesn't have a cpu core mask assigned, the application +will print an error message: + +.. code-block:: console + + Core part of pipeline was not assigned any cores. This will stall the + pipeline, please check core masks (use -h for details on setting core masks): + rx: 0 + tx: 1 + +Configuration of the eventdev is covered in detail in the programmers guide, +see the Event Device Library section. + + +Observing the Application +------------------------- + +At runtime the eventdev pipeline application prints out a summary of the +configuration, and some runtime statistics like packets per second. On exit the +worker statistics are printed, along with a full dump of the PMD statistics if +required. The following sections show sample output for each of the output +types. + +Configuration +~~~~~~~~~~~~~ + +This provides an overview of the pipeline, +scheduling type at each stage, and parameters to options such as how many +flows to use and what eventdev PMD is in use. See the following sample output +for details: + +.. code-block:: console + + Config: + ports: 2 + workers: 8 + packets: 0 + priorities: 1 + Queue-prio: 0 + qid0 type: atomic + Cores available: 44 + Cores used: 10 + Eventdev 0: event_sw + Stages: + Stage 0, Type Atomic Priority = 128 + Stage 1, Type Atomic Priority = 128 + Stage 2, Type Atomic Priority = 128 + Stage 3, Type Atomic Priority = 128 + +Runtime +~~~~~~~ + +At runtime, the statistics of the consumer are printed, stating the number of +packets received, runtime in milliseconds, average mpps, and current mpps. + +.. code-block:: console + + # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps] + +Shutdown +~~~~~~~~ + +At shutdown, the application prints the number of packets received and +transmitted, and an overview of the distribution of work across worker cores. + +.. code-block:: console + + Signal 2 received, preparing to exit... + worker 12 thread done. RX=4966581 TX=4966581 + worker 13 thread done. RX=4963329 TX=4963329 + worker 14 thread done. RX=4953614 TX=4953614 + worker 0 thread done. RX=0 TX=0 + worker 11 thread done. RX=4970549 TX=4970549 + worker 10 thread done. RX=4986391 TX=4986391 + worker 9 thread done. RX=4970528 TX=4970528 + worker 15 thread done. RX=4974087 TX=4974087 + worker 8 thread done. RX=4979908 TX=4979908 + worker 2 thread done. RX=0 TX=0 + + Port Workload distribution: + worker 0 : 12.5 % (4979876 pkts) + worker 1 : 12.5 % (4970497 pkts) + worker 2 : 12.5 % (4986359 pkts) + worker 3 : 12.5 % (4970517 pkts) + worker 4 : 12.5 % (4966566 pkts) + worker 5 : 12.5 % (4963297 pkts) + worker 6 : 12.5 % (4953598 pkts) + worker 7 : 12.5 % (4974055 pkts) + +To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to +this application. When the app is terminated using ``Ctrl+C``, the +``rte_event_dev_dump()`` function is called, resulting in a dump of the +statistics that the PMD provides. The statistics provided depend on the PMD +used, see the Event Device Drivers section for a list of eventdev PMDs. diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index 02611ef8..069d4f12 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -66,9 +66,11 @@ Sample Applications User Guides packet_ordering vmdq_dcb_forwarding vhost + vhost_scsi netmap_compatibility ip_pipeline test_pipeline + eventdev_pipeline_sw_pmd dist_app vm_power_management tep_termination diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst index 885c77e3..b675cbae 100644 --- a/doc/guides/sample_app_ug/ipsec_secgw.rst +++ b/doc/guides/sample_app_ug/ipsec_secgw.rst @@ -1,5 +1,5 @@ .. BSD LICENSE - Copyright(c) 2016 Intel Corporation. All rights reserved. + Copyright(c) 2016-2017 Intel Corporation. All rights reserved. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -153,7 +153,7 @@ The mapping of lcores to port/queues is similar to other l3fwd applications. For example, given the following command line:: ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ - --vdev "cryptodev_null_pmd" -- -p 0xf -P -u 0x3 \ + --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ -f /path/to/config_file \ @@ -165,7 +165,7 @@ where each options means: * The ``--socket-mem`` to use 2GB on socket 1. -* The ``--vdev "cryptodev_null_pmd"`` option creates virtual NULL cryptodev PMD. +* The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD. * The ``-p`` option enables ports (detected) 0, 1, 2 and 3. @@ -218,7 +218,7 @@ For example, something like the following command line: ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \ - --vdev "cryptodev_aesni_mb_pmd" --vdev "cryptodev_null_pmd" \ + --vdev "crypto_aesni_mb" --vdev "crypto_null" \ -- \ -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ -f sample.cfg @@ -412,14 +412,13 @@ where each options means: * Cipher algorithm - * Optional: No + * Optional: Yes, unless <aead_algo> is not used * Available options: * *null*: NULL algorithm * *aes-128-cbc*: AES-CBC 128-bit algorithm * *aes-128-ctr*: AES-CTR 128-bit algorithm - * *aes-128-gcm*: AES-GCM 128-bit algorithm * Syntax: *cipher_algo <your algorithm>* @@ -427,7 +426,8 @@ where each options means: * Cipher key, NOT available when 'null' algorithm is used - * Optional: No, must followed by <cipher_algo> option + * Optional: Yes, unless <aead_algo> is not used. + Must be followed by <cipher_algo> option * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. The number of bytes should be as same as the specified cipher algorithm @@ -440,20 +440,20 @@ where each options means: * Authentication algorithm - * Optional: No + * Optional: Yes, unless <aead_algo> is not used * Available options: * *null*: NULL algorithm * *sha1-hmac*: HMAC SHA1 algorithm - * *aes-128-gcm*: AES-GCM 128-bit algorithm ``<auth_key>`` * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm is used. - * Optional: No, must followed by <auth_algo> option + * Optional: Yes, unless <aead_algo> is not used. + Must be followed by <auth_algo> option * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. The number of bytes should be as same as the specified authentication @@ -462,6 +462,32 @@ where each options means: For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: A1:B2:C3:D4* +``<aead_algo>`` + + * AEAD algorithm + + * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used + + * Available options: + + * *aes-128-gcm*: AES-GCM 128-bit algorithm + + * Syntax: *cipher_algo <your algorithm>* + +``<aead_key>`` + + * Cipher key, NOT available when 'null' algorithm is used + + * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used. + Must be followed by <aead_algo> option + + * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. + The number of bytes should be as same as the specified AEAD algorithm + key size. + + For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: + A1:B2:C3:D4* + ``<mode>`` * The operation mode @@ -515,9 +541,8 @@ Example SA rules: src 1111:1111:1111:1111:1111:1111:1111:5555 \ dst 2222:2222:2222:2222:2222:2222:2222:5555 - sa in 105 cipher_algo aes-128-gcm \ - cipher_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ - auth_algo aes-128-gcm \ + sa in 105 aead_algo aes-128-gcm \ + aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 Routing rule syntax diff --git a/doc/guides/sample_app_ug/ipv4_multicast.rst b/doc/guides/sample_app_ug/ipv4_multicast.rst index 3e30f509..49712a0f 100644 --- a/doc/guides/sample_app_ug/ipv4_multicast.rst +++ b/doc/guides/sample_app_ug/ipv4_multicast.rst @@ -51,6 +51,12 @@ The lookup method is the Four-byte Key (FBK) hash-based method. The lookup table is composed of pairs of destination IPv4 address (the FBK) and a port mask associated with that IPv4 address. +.. note:: + + The max port mask supported in the given hash table is 0xf, so only first + four ports can be supported. + If using non-consecutive ports, use the destination IPv4 address accordingly. + For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account, but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address) with the mask of ports to multicast packets to. @@ -117,7 +123,7 @@ Typically, to run the IPv4 Multicast sample application, issue the following com In this command: -* The -c option enables cores 0, 1, 2 and 3 +* The -l option enables cores 0, 1, 2 and 3 * The -n option specifies 3 memory channels diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst index d6df36b5..158f4b44 100644 --- a/doc/guides/sample_app_ug/l2_forward_crypto.rst +++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst @@ -46,7 +46,7 @@ for each packet that is received on a RX_PORT and performs L2 forwarding. The destination port is the adjacent port from the enabled portmask, that is, if the first four ports are enabled (portmask 0xf), ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other. -Also, the MAC addresses are affected as follows: +Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows: * The source MAC address is replaced by the TX_PORT MAC address @@ -84,12 +84,16 @@ The application requires a number of command line options: .. code-block:: console ./build/l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] / - [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY] / + [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY/AEAD] / [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] / - [--cipher_key_random_size SIZE] [--iv IV] [--iv_random_size SIZE] / + [--cipher_key_random_size SIZE] [--cipher_iv IV] [--cipher_iv_random_size SIZE] / [--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] / - [--auth_key_random_size SIZE] [--aad AAD] [--aad_random_size SIZE] / - [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK] + [--auth_key_random_size SIZE] [--auth_iv IV] [--auth_iv_random_size SIZE] / + [--aead_algo ALGO] [--aead_op ENCRYPT/DECRYPT] [--aead_key KEY] / + [--aead_key_random_size SIZE] [--aead_iv] [--aead_iv_random_size SIZE] / + [--aad AAD] [--aad_random_size SIZE] / + [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK] / + [--mac-updating] [--no-mac-updating] where, @@ -109,7 +113,9 @@ where, * chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH), - Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash(HASH_ONLY) + Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash (HASH_ONLY) + + or AEAD (AEAD) (default is Cipher->Hash) @@ -127,15 +133,15 @@ where, Note that if --cipher_key is used, this will be ignored. -* iv: set the IV to be used. Bytes has to be separated with ":" +* cipher_iv: set the cipher IV to be used. Bytes has to be separated with ":" -* iv_random_size: set the size of the IV, which will be generated randomly. +* cipher_iv_random_size: set the size of the cipher IV, which will be generated randomly. - Note that if --iv is used, this will be ignored. + Note that if --cipher_iv is used, this will be ignored. * auth_algo: select the authentication algorithm (default is sha1-hmac) -* cipher_op: select the authentication operation to perform: GENERATE or VERIFY +* auth_op: select the authentication operation to perform: GENERATE or VERIFY (default is GENERATE) @@ -147,6 +153,32 @@ where, Note that if --auth_key is used, this will be ignored. +* auth_iv: set the auth IV to be used. Bytes has to be separated with ":" + +* auth_iv_random_size: set the size of the auth IV, which will be generated randomly. + + Note that if --auth_iv is used, this will be ignored. + +* aead_algo: select the AEAD algorithm (default is aes-gcm) + +* aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT + + (default is ENCRYPT) + +* aead_key: set the AEAD key to be used. Bytes has to be separated with ":" + +* aead_key_random_size: set the size of the AEAD key, + + which will be generated randomly. + + Note that if --aead_key is used, this will be ignored. + +* aead_iv: set the AEAD IV to be used. Bytes has to be separated with ":" + +* aead_iv_random_size: set the size of the AEAD IV, which will be generated randomly. + + Note that if --aead_iv is used, this will be ignored. + * aad: set the AAD to be used. Bytes has to be separated with ":" * aad_random_size: set the size of the AAD, which will be generated randomly. @@ -162,6 +194,8 @@ where, (default is all cryptodevs). +* [no-]mac-updating: Enable or disable MAC addresses updating (enabled by default). + The application requires that crypto devices capable of performing the specified crypto operation are available on application initialization. @@ -172,8 +206,8 @@ To run the application in linuxapp environment with 2 lcores, 2 ports and 2 cryp .. code-block:: console - $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "cryptodev_aesni_mb_pmd" \ - --vdev "cryptodev_aesni_mb_pmd" -- -p 0x3 --chain CIPHER_HASH \ + $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "crypto_aesni_mb0" \ + --vdev "crypto_aesni_mb1" -- -p 0x3 --chain CIPHER_HASH \ --cipher_op ENCRYPT --cipher_algo aes-cbc \ --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \ --auth_op GENERATE --auth_algo aes-xcbc-mac \ @@ -331,8 +365,14 @@ This session is created and is later attached to the crypto operation: uint8_t cdev_id) { struct rte_crypto_sym_xform *first_xform; + struct rte_cryptodev_sym_session *session; + uint8_t socket_id = rte_cryptodev_socket_id(cdev_id); + struct rte_mempool *sess_mp = session_pool_socket[socket_id]; + - if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) { + if (options->xform_chain == L2FWD_CRYPTO_AEAD) { + first_xform = &options->aead_xform; + } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) { first_xform = &options->cipher_xform; first_xform->next = &options->auth_xform; } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) { @@ -344,8 +384,16 @@ This session is created and is later attached to the crypto operation: first_xform = &options->auth_xform; } - /* Setup Cipher Parameters */ - return rte_cryptodev_sym_session_create(cdev_id, first_xform); + session = rte_cryptodev_sym_session_create(sess_mp); + + if (session == NULL) + return NULL; + + if (rte_cryptodev_sym_session_init(cdev_id, session, + first_xform, sess_mp) < 0) + return NULL; + + return session; } ... diff --git a/doc/guides/sample_app_ug/vhost_scsi.rst b/doc/guides/sample_app_ug/vhost_scsi.rst new file mode 100644 index 00000000..8be069e0 --- /dev/null +++ b/doc/guides/sample_app_ug/vhost_scsi.rst @@ -0,0 +1,115 @@ + +.. BSD LICENSE + Copyright(c) 2010-2017 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +Vhost_scsi Sample Application +============================= + +The vhost_scsi sample application implemented a simple SCSI block device, +which used as the backend of Qemu vhost-user-scsi device. Users can extend +the exist example to use other type of block device(e.g. AIO) besides +memory based block device. Similar with vhost-user-net device, the sample +application used domain socket to communicate with Qemu, and the virtio +ring was processed by vhost_scsi sample application. + +The sample application reuse lots codes from SPDK(Storage Performance +Development Kit, https://github.com/spdk/spdk) vhost-user-scsi target, +for DPDK vhost library used in storage area, user can take SPDK as +reference as well. + +Testing steps +------------- + +This section shows the steps how to start a VM with the block device as +fast data path for critical application. + +Build +~~~~~ + +Follow the *Getting Started Guide for Linux* on generic info about +environment setup and building DPDK from source. + +In this example, you need build DPDK both on the host and inside guest. +Also, you need build this example. + +.. code-block:: console + + export RTE_SDK=/path/to/dpdk_source + export RTE_TARGET=x86_64-native-linuxapp-gcc + + cd ${RTE_SDK}/examples/vhost_scsi + make + + +Start the vhost_scsi example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + ./vhost_scsi -m 1024 + +.. _vhost_scsi_app_run_vm: + +Start the VM +~~~~~~~~~~~~ + +.. code-block:: console + + qemu-system-x86_64 -machine accel=kvm \ + -m $mem -object memory-backend-file,id=mem,size=$mem,\ + mem-path=/dev/hugepages,share=on -numa node,memdev=mem \ + -drive file=os.img,if=none,id=disk \ + -device ide-hd,drive=disk,bootindex=0 \ + -chardev socket,id=char0,path=/tmp/vhost.socket \ + -device vhost-user-scsi-pci,chardev=char0,bootindex=2 \ + ... + +.. note:: + You must check whether your Qemu can support "vhost-user-scsi" or not, + Qemu v2.10 or newer version is required. + +Vhost_scsi Common Issues +------------------------ + +* vhost_scsi can not start with block size 512 Bytes: + + Currently DPDK vhost library was designed for NET device(althrough the APIs + are generic now), for 512 Bytes block device, Qemu BIOS(x86 BIOS Enhanced + Disk Device) will enumerate all block device and do some IOs to those block + devices with 512 Bytes sector size. DPDK vhost library can not process such + scenarios(both BIOS and OS will enumerate the block device), so as a + workaround, the vhost_scsi example application hardcoded the block size + with 4096 Bytes. + +* vhost_scsi can only support the block device as fast data disk(non OS image): + + Make sure ``bootindex=2`` Qemu option is given to vhost-user-scsi-pci device. + |