]> git.droids-corp.org - dpdk.git/commitdiff
doc: rework section on virtio-user as exception path
authorBruce Richardson <bruce.richardson@intel.com>
Fri, 10 Jun 2022 15:35:32 +0000 (16:35 +0100)
committerMaxime Coquelin <maxime.coquelin@redhat.com>
Fri, 8 Jul 2022 08:48:21 +0000 (10:48 +0200)
This patch extensively reworks the howto guide on using virtio-user for
exception packets. Changes include:

* rename "exceptional path" to "exception path"
* remove references to uio and just reference vfio-pci
* simplify testpmd command-lines, giving a basic usage example first
  before adding on detail about checksum or TSO parameters
* give a complete working example showing traffic flowing through the
  whole system from a testpmd loopback using the created TAP netdev
* replace use of "ifconfig" with Linux standard "ip" command
* other general rewording.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Chenbo Xia <chenbo.xia@intel.com>
Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>
doc/guides/howto/img/virtio_user_as_exception_path.svg [new file with mode: 0644]
doc/guides/howto/img/virtio_user_as_exceptional_path.svg [deleted file]
doc/guides/howto/index.rst
doc/guides/howto/virtio_user_as_exception_path.rst [new file with mode: 0644]
doc/guides/howto/virtio_user_as_exceptional_path.rst [deleted file]

diff --git a/doc/guides/howto/img/virtio_user_as_exception_path.svg b/doc/guides/howto/img/virtio_user_as_exception_path.svg
new file mode 100644 (file)
index 0000000..b231b70
--- /dev/null
@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by Microsoft Visio, SVG Export virtio_user_as_exceptional_pathvsdx.svg Page-1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ev="http://www.w3.org/2001/xml-events"
+               xmlns:v="http://schemas.microsoft.com/visio/2003/SVGExtensions/" width="5.77778in" height="3.88851in"
+               viewBox="0 0 416 279.973" xml:space="preserve" color-interpolation-filters="sRGB" class="st13">
+       <v:documentProperties v:langID="1033" v:viewMarkup="false"/>
+
+       <style type="text/css">
+       <![CDATA[
+               .st1 {visibility:visible}
+               .st2 {fill:#5b9bd5;fill-opacity:0.22;filter:url(#filter_2);stroke:#5b9bd5;stroke-opacity:0.22}
+               .st3 {fill:#ffffff;stroke:#c7c8c8;stroke-width:0.25}
+               .st4 {stroke:#000000;stroke-dasharray:7,5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
+               .st5 {fill:#000000;font-family:Calibri;font-size:0.833336em}
+               .st6 {fill:none;stroke:none;stroke-width:0.25}
+               .st7 {fill:#000000;font-family:Calibri;font-size:1.00001em;font-style:italic}
+               .st8 {fill:#70ad47;stroke:#c7c8c8;stroke-width:0.25}
+               .st9 {stroke:#5b9bd5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.75}
+               .st10 {marker-end:url(#mrkr4-68);marker-start:url(#mrkr4-66);stroke:#000000;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
+               .st11 {fill:#000000;fill-opacity:1;stroke:#000000;stroke-opacity:1;stroke-width:0.28409090909091}
+               .st12 {fill:#d8d8d8;stroke:#c7c8c8;stroke-width:0.25}
+               .st13 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3}
+       ]]>
+       </style>
+
+       <defs id="Markers">
+               <g id="lend4">
+                       <path d="M 2 1 L 0 0 L 2 -1 L 2 1 " style="stroke:none"/>
+               </g>
+               <marker id="mrkr4-66" class="st11" v:arrowType="4" v:arrowSize="2" v:setback="6.68" refX="6.68" orient="auto"
+                               markerUnits="strokeWidth" overflow="visible">
+                       <use xlink:href="#lend4" transform="scale(3.52) "/>
+               </marker>
+               <marker id="mrkr4-68" class="st11" v:arrowType="4" v:arrowSize="2" v:setback="7.04" refX="-7.04" orient="auto"
+                               markerUnits="strokeWidth" overflow="visible">
+                       <use xlink:href="#lend4" transform="scale(-3.52,-3.52) "/>
+               </marker>
+       </defs>
+       <defs id="Filters">
+               <filter id="filter_2">
+                       <feGaussianBlur stdDeviation="2"/>
+               </filter>
+       </defs>
+       <g v:mID="0" v:index="1" v:groupContext="foregroundPage">
+               <title>Page-1</title>
+               <v:pageProperties v:drawingScale="1" v:pageScale="1" v:drawingUnits="0" v:shadowOffsetX="9" v:shadowOffsetY="-9"/>
+               <v:layer v:name="Connector" v:index="0"/>
+               <g id="shape23-1" v:mID="23" v:groupContext="shape" transform="translate(195.804,-74.9728)">
+                       <title>Rectangle.23</title>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <g id="shadow23-2" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="113.473" width="216.6" height="166.5" class="st2"/>
+                       </g>
+                       <rect x="0" y="113.473" width="216.6" height="166.5" class="st3"/>
+               </g>
+               <g id="shape42-6" v:mID="42" v:groupContext="shape" v:layerMember="0" transform="translate(146.904,-277.473)">
+                       <title>Dynamic connector.42</title>
+                       <path d="M-9 279.97 L-9 540.97" class="st4"/>
+               </g>
+               <g id="shape45-9" v:mID="45" v:groupContext="shape" transform="translate(2.9044,-142.292)">
+                       <title>Rectangle.45</title>
+                       <desc>tap</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="34.05" cy="264.132" width="68.1" height="31.6807"/>
+                       <g id="shadow45-10" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="248.292" width="68.1" height="31.6807" class="st2"/>
+                       </g>
+                       <rect x="0" y="248.292" width="68.1" height="31.6807" class="st3"/>
+                       <text x="27.35" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>tap</text>            </g>
+               <g id="shape46-15" v:mID="46" v:groupContext="shape" transform="translate(2.9044,-43.2921)">
+                       <title>Rectangle.46</title>
+                       <desc>vhost ko</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="34.05" cy="264.132" width="68.1" height="31.6807"/>
+                       <g id="shadow46-16" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="248.292" width="68.1" height="31.6807" class="st2"/>
+                       </g>
+                       <rect x="0" y="248.292" width="68.1" height="31.6807" class="st3"/>
+                       <text x="16.86" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>vhost ko  </text>             </g>
+               <g id="shape47-21" v:mID="47" v:groupContext="shape" transform="translate(18.9544,-257.223)">
+                       <title>Sheet.47</title>
+                       <desc>Kernel space</desc>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="44.025" cy="268.723" width="88.05" height="22.5"/>
+                       <rect x="0" y="257.473" width="88.05" height="22.5" class="st6"/>
+                       <text x="13.44" y="272.32" class="st7" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>Kernel space</text>           </g>
+               <g id="shape48-24" v:mID="48" v:groupContext="shape" transform="translate(148.854,-257.223)">
+                       <title>Sheet.48</title>
+                       <desc>User space</desc>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="44.025" cy="268.723" width="88.05" height="22.5"/>
+                       <rect x="0" y="257.473" width="88.05" height="22.5" class="st6"/>
+                       <text x="17.7" y="272.32" class="st7" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>User space</text>              </g>
+               <g id="shape49-27" v:mID="49" v:groupContext="shape" transform="translate(218.904,-182.792)">
+                       <title>Rectangle.49</title>
+                       <desc>ETHDEV</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="83.25" cy="264.132" width="166.5" height="31.6807"/>
+                       <g id="shadow49-28" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="248.292" width="166.5" height="31.6807" class="st2"/>
+                       </g>
+                       <rect x="0" y="248.292" width="166.5" height="31.6807" class="st3"/>
+                       <text x="66.9" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>ETHDEV</text>          </g>
+               <g id="shape50-33" v:mID="50" v:groupContext="shape" transform="translate(218.904,-142.292)">
+                       <title>Rectangle.50</title>
+                       <desc>virtio PMD</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="38.7911" cy="264.132" width="77.59" height="31.6807"/>
+                       <g id="shadow50-34" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st2"/>
+                       </g>
+                       <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st3"/>
+                       <text x="17.12" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>virtio PMD</text>             </g>
+               <g id="shape51-39" v:mID="51" v:groupContext="shape" transform="translate(308.904,-142.292)">
+                       <title>Rectangle.51</title>
+                       <desc>other PMDs</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="38.7911" cy="264.132" width="77.59" height="31.6807"/>
+                       <g id="shadow51-40" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st2"/>
+                       </g>
+                       <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st3"/>
+                       <text x="14.6" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>other PMDs</text>              </g>
+               <g id="shape52-45" v:mID="52" v:groupContext="shape" transform="translate(218.904,-86.3131)">
+                       <title>Rectangle.52</title>
+                       <desc>virtio-user</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="38.7911" cy="256.393" width="77.59" height="47.1597"/>
+                       <g id="shadow52-46" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="232.813" width="77.5823" height="47.1597" class="st2"/>
+                       </g>
+                       <rect x="0" y="232.813" width="77.5823" height="47.1597" class="st8"/>
+                       <text x="17.84" y="247.39" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>virtio-user<v:newlineChar/><v:newlineChar/></text>            </g>
+               <g id="shape53-51" v:mID="53" v:groupContext="shape" transform="translate(223.404,-90.1829)">
+                       <title>Rectangle.53</title>
+                       <desc>vhost adapter</desc>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="34.05" cy="268.183" width="68.1" height="23.5798"/>
+                       <g id="shadow53-52" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="256.393" width="68.1" height="23.5798" class="st2"/>
+                       </g>
+                       <rect x="0" y="256.393" width="68.1" height="23.5798" class="st3"/>
+                       <text x="5.82" y="271.18" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>vhost adapter</text>           </g>
+               <g id="shape54-57" v:mID="54" v:groupContext="shape" v:layerMember="0" transform="translate(71.0044,-59.1325)">
+                       <title>Dynamic connector</title>
+                       <path d="M0 279.97 L63.9 279.97 A3 3 0 1 1 69.9 279.97 L186.69 279.97 L186.69 252.79" class="st9"/>
+               </g>
+               <g id="shape55-60" v:mID="55" v:groupContext="shape" v:layerMember="0" transform="translate(71.0044,-149.132)">
+                       <title>Dynamic connector.55</title>
+                       <path d="M6.68 270.97 L7.04 270.97 L63.9 270.97 A3 3 0 0 1 69.9 270.97 L140.86 270.97" class="st10"/>
+               </g>
+               <g id="shape56-69" v:mID="56" v:groupContext="shape" transform="translate(308.904,-5.2228)">
+                       <title>Rectangle.38</title>
+                       <v:userDefs>
+                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
+                       </v:userDefs>
+                       <g id="shadow56-70" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
+                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+                               <rect x="0" y="257.473" width="77.5823" height="22.5" rx="11.25" ry="11.25" class="st2"/>
+                       </g>
+                       <rect x="0" y="257.473" width="77.5823" height="22.5" rx="11.25" ry="11.25" class="st12"/>
+               </g>
+               <g id="shape57-74" v:mID="57" v:groupContext="shape" transform="translate(318.204,-5.2228)">
+                       <title>Sheet.57</title>
+                       <desc>NIC</desc>
+                       <v:textBlock v:margins="rect(4,4,4,4)"/>
+                       <v:textRect cx="28.125" cy="268.723" width="56.25" height="22.5"/>
+                       <rect x="0" y="257.473" width="56.25" height="22.5" class="st6"/>
+                       <text x="19.61" y="272.32" class="st7" v:langID="2052"><v:paragraph v:horizAlign="1"/><v:tabList/>NIC</text>            </g>
+               <g id="shape58-77" v:mID="58" v:groupContext="shape" v:layerMember="0" transform="translate(356.696,-142.292)">
+                       <title>Dynamic connector.41</title>
+                       <path d="M-9 286.65 L-9 287.01 L-9 387.5" class="st10"/>
+               </g>
+       </g>
+</svg>
diff --git a/doc/guides/howto/img/virtio_user_as_exceptional_path.svg b/doc/guides/howto/img/virtio_user_as_exceptional_path.svg
deleted file mode 100644 (file)
index b231b70..0000000
+++ /dev/null
@@ -1,207 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by Microsoft Visio, SVG Export virtio_user_as_exceptional_pathvsdx.svg Page-1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ev="http://www.w3.org/2001/xml-events"
-               xmlns:v="http://schemas.microsoft.com/visio/2003/SVGExtensions/" width="5.77778in" height="3.88851in"
-               viewBox="0 0 416 279.973" xml:space="preserve" color-interpolation-filters="sRGB" class="st13">
-       <v:documentProperties v:langID="1033" v:viewMarkup="false"/>
-
-       <style type="text/css">
-       <![CDATA[
-               .st1 {visibility:visible}
-               .st2 {fill:#5b9bd5;fill-opacity:0.22;filter:url(#filter_2);stroke:#5b9bd5;stroke-opacity:0.22}
-               .st3 {fill:#ffffff;stroke:#c7c8c8;stroke-width:0.25}
-               .st4 {stroke:#000000;stroke-dasharray:7,5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
-               .st5 {fill:#000000;font-family:Calibri;font-size:0.833336em}
-               .st6 {fill:none;stroke:none;stroke-width:0.25}
-               .st7 {fill:#000000;font-family:Calibri;font-size:1.00001em;font-style:italic}
-               .st8 {fill:#70ad47;stroke:#c7c8c8;stroke-width:0.25}
-               .st9 {stroke:#5b9bd5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.75}
-               .st10 {marker-end:url(#mrkr4-68);marker-start:url(#mrkr4-66);stroke:#000000;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
-               .st11 {fill:#000000;fill-opacity:1;stroke:#000000;stroke-opacity:1;stroke-width:0.28409090909091}
-               .st12 {fill:#d8d8d8;stroke:#c7c8c8;stroke-width:0.25}
-               .st13 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3}
-       ]]>
-       </style>
-
-       <defs id="Markers">
-               <g id="lend4">
-                       <path d="M 2 1 L 0 0 L 2 -1 L 2 1 " style="stroke:none"/>
-               </g>
-               <marker id="mrkr4-66" class="st11" v:arrowType="4" v:arrowSize="2" v:setback="6.68" refX="6.68" orient="auto"
-                               markerUnits="strokeWidth" overflow="visible">
-                       <use xlink:href="#lend4" transform="scale(3.52) "/>
-               </marker>
-               <marker id="mrkr4-68" class="st11" v:arrowType="4" v:arrowSize="2" v:setback="7.04" refX="-7.04" orient="auto"
-                               markerUnits="strokeWidth" overflow="visible">
-                       <use xlink:href="#lend4" transform="scale(-3.52,-3.52) "/>
-               </marker>
-       </defs>
-       <defs id="Filters">
-               <filter id="filter_2">
-                       <feGaussianBlur stdDeviation="2"/>
-               </filter>
-       </defs>
-       <g v:mID="0" v:index="1" v:groupContext="foregroundPage">
-               <title>Page-1</title>
-               <v:pageProperties v:drawingScale="1" v:pageScale="1" v:drawingUnits="0" v:shadowOffsetX="9" v:shadowOffsetY="-9"/>
-               <v:layer v:name="Connector" v:index="0"/>
-               <g id="shape23-1" v:mID="23" v:groupContext="shape" transform="translate(195.804,-74.9728)">
-                       <title>Rectangle.23</title>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <g id="shadow23-2" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="113.473" width="216.6" height="166.5" class="st2"/>
-                       </g>
-                       <rect x="0" y="113.473" width="216.6" height="166.5" class="st3"/>
-               </g>
-               <g id="shape42-6" v:mID="42" v:groupContext="shape" v:layerMember="0" transform="translate(146.904,-277.473)">
-                       <title>Dynamic connector.42</title>
-                       <path d="M-9 279.97 L-9 540.97" class="st4"/>
-               </g>
-               <g id="shape45-9" v:mID="45" v:groupContext="shape" transform="translate(2.9044,-142.292)">
-                       <title>Rectangle.45</title>
-                       <desc>tap</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="34.05" cy="264.132" width="68.1" height="31.6807"/>
-                       <g id="shadow45-10" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="248.292" width="68.1" height="31.6807" class="st2"/>
-                       </g>
-                       <rect x="0" y="248.292" width="68.1" height="31.6807" class="st3"/>
-                       <text x="27.35" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>tap</text>            </g>
-               <g id="shape46-15" v:mID="46" v:groupContext="shape" transform="translate(2.9044,-43.2921)">
-                       <title>Rectangle.46</title>
-                       <desc>vhost ko</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="34.05" cy="264.132" width="68.1" height="31.6807"/>
-                       <g id="shadow46-16" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="248.292" width="68.1" height="31.6807" class="st2"/>
-                       </g>
-                       <rect x="0" y="248.292" width="68.1" height="31.6807" class="st3"/>
-                       <text x="16.86" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>vhost ko  </text>             </g>
-               <g id="shape47-21" v:mID="47" v:groupContext="shape" transform="translate(18.9544,-257.223)">
-                       <title>Sheet.47</title>
-                       <desc>Kernel space</desc>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="44.025" cy="268.723" width="88.05" height="22.5"/>
-                       <rect x="0" y="257.473" width="88.05" height="22.5" class="st6"/>
-                       <text x="13.44" y="272.32" class="st7" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>Kernel space</text>           </g>
-               <g id="shape48-24" v:mID="48" v:groupContext="shape" transform="translate(148.854,-257.223)">
-                       <title>Sheet.48</title>
-                       <desc>User space</desc>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="44.025" cy="268.723" width="88.05" height="22.5"/>
-                       <rect x="0" y="257.473" width="88.05" height="22.5" class="st6"/>
-                       <text x="17.7" y="272.32" class="st7" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>User space</text>              </g>
-               <g id="shape49-27" v:mID="49" v:groupContext="shape" transform="translate(218.904,-182.792)">
-                       <title>Rectangle.49</title>
-                       <desc>ETHDEV</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="83.25" cy="264.132" width="166.5" height="31.6807"/>
-                       <g id="shadow49-28" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="248.292" width="166.5" height="31.6807" class="st2"/>
-                       </g>
-                       <rect x="0" y="248.292" width="166.5" height="31.6807" class="st3"/>
-                       <text x="66.9" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>ETHDEV</text>          </g>
-               <g id="shape50-33" v:mID="50" v:groupContext="shape" transform="translate(218.904,-142.292)">
-                       <title>Rectangle.50</title>
-                       <desc>virtio PMD</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="38.7911" cy="264.132" width="77.59" height="31.6807"/>
-                       <g id="shadow50-34" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st2"/>
-                       </g>
-                       <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st3"/>
-                       <text x="17.12" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>virtio PMD</text>             </g>
-               <g id="shape51-39" v:mID="51" v:groupContext="shape" transform="translate(308.904,-142.292)">
-                       <title>Rectangle.51</title>
-                       <desc>other PMDs</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="38.7911" cy="264.132" width="77.59" height="31.6807"/>
-                       <g id="shadow51-40" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st2"/>
-                       </g>
-                       <rect x="0" y="248.292" width="77.5823" height="31.6807" class="st3"/>
-                       <text x="14.6" y="267.13" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>other PMDs</text>              </g>
-               <g id="shape52-45" v:mID="52" v:groupContext="shape" transform="translate(218.904,-86.3131)">
-                       <title>Rectangle.52</title>
-                       <desc>virtio-user</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="38.7911" cy="256.393" width="77.59" height="47.1597"/>
-                       <g id="shadow52-46" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="232.813" width="77.5823" height="47.1597" class="st2"/>
-                       </g>
-                       <rect x="0" y="232.813" width="77.5823" height="47.1597" class="st8"/>
-                       <text x="17.84" y="247.39" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>virtio-user<v:newlineChar/><v:newlineChar/></text>            </g>
-               <g id="shape53-51" v:mID="53" v:groupContext="shape" transform="translate(223.404,-90.1829)">
-                       <title>Rectangle.53</title>
-                       <desc>vhost adapter</desc>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="34.05" cy="268.183" width="68.1" height="23.5798"/>
-                       <g id="shadow53-52" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="256.393" width="68.1" height="23.5798" class="st2"/>
-                       </g>
-                       <rect x="0" y="256.393" width="68.1" height="23.5798" class="st3"/>
-                       <text x="5.82" y="271.18" class="st5" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>vhost adapter</text>           </g>
-               <g id="shape54-57" v:mID="54" v:groupContext="shape" v:layerMember="0" transform="translate(71.0044,-59.1325)">
-                       <title>Dynamic connector</title>
-                       <path d="M0 279.97 L63.9 279.97 A3 3 0 1 1 69.9 279.97 L186.69 279.97 L186.69 252.79" class="st9"/>
-               </g>
-               <g id="shape55-60" v:mID="55" v:groupContext="shape" v:layerMember="0" transform="translate(71.0044,-149.132)">
-                       <title>Dynamic connector.55</title>
-                       <path d="M6.68 270.97 L7.04 270.97 L63.9 270.97 A3 3 0 0 1 69.9 270.97 L140.86 270.97" class="st10"/>
-               </g>
-               <g id="shape56-69" v:mID="56" v:groupContext="shape" transform="translate(308.904,-5.2228)">
-                       <title>Rectangle.38</title>
-                       <v:userDefs>
-                               <v:ud v:nameU="visVersion" v:val="VT0(15):26"/>
-                       </v:userDefs>
-                       <g id="shadow56-70" v:groupContext="shadow" v:shadowOffsetX="0.345598" v:shadowOffsetY="-1.97279" v:shadowType="1"
-                                       transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
-                               <rect x="0" y="257.473" width="77.5823" height="22.5" rx="11.25" ry="11.25" class="st2"/>
-                       </g>
-                       <rect x="0" y="257.473" width="77.5823" height="22.5" rx="11.25" ry="11.25" class="st12"/>
-               </g>
-               <g id="shape57-74" v:mID="57" v:groupContext="shape" transform="translate(318.204,-5.2228)">
-                       <title>Sheet.57</title>
-                       <desc>NIC</desc>
-                       <v:textBlock v:margins="rect(4,4,4,4)"/>
-                       <v:textRect cx="28.125" cy="268.723" width="56.25" height="22.5"/>
-                       <rect x="0" y="257.473" width="56.25" height="22.5" class="st6"/>
-                       <text x="19.61" y="272.32" class="st7" v:langID="2052"><v:paragraph v:horizAlign="1"/><v:tabList/>NIC</text>            </g>
-               <g id="shape58-77" v:mID="58" v:groupContext="shape" v:layerMember="0" transform="translate(356.696,-142.292)">
-                       <title>Dynamic connector.41</title>
-                       <path d="M-9 286.65 L-9 287.01 L-9 387.5" class="st10"/>
-               </g>
-       </g>
-</svg>
index c2a2c60ddb3ee51cfb73ede59100e3a727f84953..bf6337d021a42f62da8d6eb7f4f4719ddc7b8ecd 100644 (file)
@@ -15,7 +15,7 @@ HowTo Guides
     pvp_reference_benchmark
     vfd
     virtio_user_for_container_networking
-    virtio_user_as_exceptional_path
+    virtio_user_as_exception_path
     packet_capture_framework
     telemetry
     debug_troubleshoot
diff --git a/doc/guides/howto/virtio_user_as_exception_path.rst b/doc/guides/howto/virtio_user_as_exception_path.rst
new file mode 100644 (file)
index 0000000..26342b2
--- /dev/null
@@ -0,0 +1,158 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2016 Intel Corporation.
+
+.. _virtio_user_as_exception_path:
+
+Virtio_user as Exception Path
+=============================
+
+.. note::
+
+   This solution is only applicable to Linux systems.
+
+The virtual device, virtio-user, was originally introduced with the vhost-user
+backend as a high performance solution for IPC (Inter-Process Communication)
+and user space container networking.
+
+Beyond this originally intended use,
+virtio-user can be used in conjunction with the vhost-kernel backend
+as a solution for dealing with exception path packets
+which need to be injected into the Linux kernel for processing there.
+In this regard, virtio-user and vhost in kernel space are an alternative to DPDK KNI
+for transferring packets between a DPDK packet processing application and the kernel stack.
+
+This solution has a number of advantages over alternatives such as KNI:
+
+*   Maintenance
+
+    All kernel modules needed by this solution, vhost and vhost-net (kernel),
+    are upstreamed and extensively used.
+
+*   Features
+
+    vhost-net is designed to be a networking solution, and, as such,
+    has lots of networking related features,
+    such as multi queue support, TSO, multi-segment buffer support, etc.
+
+*   Performance
+
+    Similar to KNI, this solution would use one or more kthreads
+    to send/receive packets to/from user space DPDK applications,
+    which minimises the impact on the polling DPDK threads.
+
+The overview of an application using virtio-user as exception path is shown
+in :numref:`figure_virtio_user_as_exception_path`.
+
+.. _figure_virtio_user_as_exception_path:
+
+.. figure:: img/virtio_user_as_exception_path.*
+
+   Overview of a DPDK app using virtio-user as exception path
+
+
+Example Usage With Testpmd
+---------------------------
+
+.. note::
+
+   These instructions assume that the vhost/vhost-net kernel modules are available
+   and have already been loaded into the running kernel.
+   It also assumes that the DPDK virtio driver has not been disabled in the DPDK build.
+
+To run a simple test of virtio-user as exception path using testpmd:
+
+#. Compile DPDK and bind a NIC to vfio-pci as documented in :ref:`linux_gsg_linux_drivers`.
+
+   This physical NIC is for communicating with the outside world,
+   and serves as a packet source in this example.
+
+#. Run testpmd to forward packets from NIC to kernel,
+   passing in a suitable list of logical cores to run on  (``-l`` parameter),
+   and optionally the PCI address of the physical NIC to use (``-a`` parameter).
+   The virtio-user device for interfacing to the kernel is specified via a ``--vdev`` argument,
+   taking the parameters described below.
+
+   .. code-block:: console
+
+      /path/to/dpdk-testpmd -l <cores> -a <pci BDF> \
+          --vdev=virtio_user0,path=/dev/vhost-net,queues=1,queue_size=1024
+
+   ``path``
+     The path to the kernel vhost-net device.
+
+   ``queue_size``
+     256 by default. To avoid shortage of descriptors, we can increase it to 1024.
+
+   ``queues``
+     Number of virt-queues. Each queue will be served by a kthread.
+
+#. Once testpmd is running, a new network interface - called ``tap0`` by default -
+   will be present on the system.
+   This should be configured with an IP address and then enabled for use:
+
+   .. code-block:: console
+
+      ip addr add 192.168.1.1/24 dev tap0
+      ip link set dev tap0 up
+
+#. To observe packet forwarding through the kernel,
+   a second testpmd instance can be run on the system,
+   taking packets from the kernel using an ``af_packet`` socket on the ``tap0`` interface.
+
+   .. code-block:: console
+
+      /path/to/dpdk-testpmd -l <cores> --vdev=net_af_packet0,iface=tap0 --in-memory --no-pci
+
+   When running this instance,
+   we can use ``--in-memory`` flag to avoid hugepage naming conflicts with the previous instance,
+   and we also use ``--no-pci`` flag to only use the ``af_packet`` interface
+   for all traffic forwarding.
+
+#. Running traffic into the system through the NIC should see that traffic returned back again,
+   having been forwarded through both testpmd instances.
+   This can be confirmed by checking the testpmd statistics on testpmd exit.
+
+For more advanced use of virtio-user with testpmd in this scenario,
+some other more advanced options may also be used.
+For example:
+
+* ``--tx-offloads=0x02c``
+
+  This testpmd option enables Tx offloads for UDP and TCP checksum on transmit,
+  as well as TCP TSO support.
+  The list of the offload flag values can be seen in header
+  `rte_ethdev.h <https://doc.dpdk.org/api/rte__ethdev_8h.html>`_.
+
+* ``--enable-lro``
+
+  This testpmd option is used to negotiate VIRTIO_NET_F_GUEST_TSO4 and
+  VIRTIO_NET_F_GUEST_TSO6 feature so that large packets from the kernel can be
+  transmitted to the DPDK application and further TSOed by physical NIC.
+  If unsupported by the physical NIC, errors may be reported by testpmd with this option.
+
+* Enabling Rx checksum offloads for physical port:
+
+  Within testpmd, you can enable and disable offloads on a per-port basis,
+  rather than enabling them for both ports.
+  For the physical NIC, it may be desirable to enable checksum offload on packet Rx.
+  This may be done as below, if testpmd is run with ``-i`` flag for interactive mode.
+
+   .. code-block:: console
+
+      testpmd> port stop 0
+      testpmd> port config 0 rx_offload tcp_cksum on
+      testpmd> port config 0 rx_offload udp_cksum on
+      testpmd> port start 0
+
+* Multiple queue support
+
+  Better performance may be achieved by using multiple queues,
+  so that multiple kernel threads are handling the traffic on the kernel side.
+  For example, to use 2 queues on both NIC and virtio ports,
+  while also enabling TX offloads and LRO support:
+
+  .. code-block:: console
+
+     /path/to/dpdk-testpmd --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 -- \
+         -i --tx-offloads=0x002c --enable-lro --txq=2 --rxq=2 --txd=1024 --rxd=1024
+
diff --git a/doc/guides/howto/virtio_user_as_exceptional_path.rst b/doc/guides/howto/virtio_user_as_exceptional_path.rst
deleted file mode 100644 (file)
index ec021af..0000000
+++ /dev/null
@@ -1,118 +0,0 @@
-..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2016 Intel Corporation.
-
-.. _virtio_user_as_exceptional_path:
-
-Virtio_user as Exceptional Path
-===============================
-
-The virtual device, virtio-user, was originally introduced with vhost-user
-backend, as a high performance solution for IPC (Inter-Process Communication)
-and user space container networking.
-
-Virtio_user with vhost-kernel backend is a solution for exceptional path,
-such as KNI which exchanges packets with kernel networking stack. This
-solution is very promising in:
-
-*   Maintenance
-
-    All kernel modules needed by this solution, vhost and vhost-net (kernel),
-    are upstreamed and extensively used kernel module.
-
-*   Features
-
-    vhost-net is born to be a networking solution, which has lots of networking
-    related features, like multi queue, tso, multi-seg mbuf, etc.
-
-*   Performance
-
-    similar to KNI, this solution would use one or more kthreads to
-    send/receive packets to/from user space DPDK applications, which has little
-    impact on user space polling thread (except that it might enter into kernel
-    space to wake up those kthreads if necessary).
-
-The overview of an application using virtio-user as exceptional path is shown
-in :numref:`figure_virtio_user_as_exceptional_path`.
-
-.. _figure_virtio_user_as_exceptional_path:
-
-.. figure:: img/virtio_user_as_exceptional_path.*
-
-   Overview of a DPDK app using virtio-user as exceptional path
-
-
-Sample Usage
-------------
-
-As a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen before
-compiling the kernel and those kernel modules should be inserted.
-
-#.  Compile DPDK and bind a physical NIC to igb_uio/uio_pci_generic/vfio-pci.
-
-    This physical NIC is for communicating with outside.
-
-#.  Run testpmd.
-
-    .. code-block:: console
-
-        $(testpmd) -l 2-3 -n 4 \
-               --vdev=virtio_user0,path=/dev/vhost-net,queue_size=1024 \
-               -- -i --tx-offloads=0x0000002c --enable-lro \
-               --txd=1024 --rxd=1024
-
-    This command runs testpmd with two ports, one physical NIC to communicate
-    with outside, and one virtio-user to communicate with kernel.
-
-* ``--enable-lro``
-
-    This is used to negotiate VIRTIO_NET_F_GUEST_TSO4 and
-    VIRTIO_NET_F_GUEST_TSO6 feature so that large packets from kernel can be
-    transmitted to DPDK application and further TSOed by physical NIC.
-
-* ``queue_size``
-
-    256 by default. To avoid shortage of descriptors, we can increase it to 1024.
-
-* ``queues``
-
-    Number of multi-queues. Each queue will be served by a kthread. For example:
-
-    .. code-block:: console
-
-        $(testpmd) -l 2-3 -n 4 \
-               --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
-               -- -i --tx-offloads=0x0000002c --enable-lro \
-               --txq=2 --rxq=2 --txd=1024 --rxd=1024
-
-#. Enable Rx checksum offloads in testpmd:
-
-    .. code-block:: console
-
-        (testpmd) port stop 0
-        (testpmd) port config 0 rx_offload tcp_cksum on
-        (testpmd) port config 0 rx_offload udp_cksum on
-        (testpmd) port start 0
-
-#. Start testpmd:
-
-    .. code-block:: console
-
-        (testpmd) start
-
-#.  Configure IP address and start tap:
-
-    .. code-block:: console
-
-        ifconfig tap0 1.1.1.1/24 up
-
-.. note::
-
-    The tap device will be named tap0, tap1, etc, by kernel.
-
-Then, all traffic from physical NIC can be forwarded into kernel stack, and all
-traffic on the tap0 can be sent out from physical NIC.
-
-Limitations
------------
-
-This solution is only available on Linux systems.