[dpdk-dev,1/1] doc: correct Vhost Sample Application guide
diff mbox

Message ID 1449664541-9546-1-git-send-email-bernard.iremonger@intel.com
State Superseded, archived
Headers show

Commit Message

Bernard Iremonger Dec. 9, 2015, 12:35 p.m. UTC
correct sample console commands

Fixes: d0dff9ba445e ("doc: sample application user guide"
Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
---
 doc/guides/sample_app_ug/vhost.rst | 40 +++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

Comments

Huawei Xie Dec. 9, 2015, 1:36 p.m. UTC | #1
On 12/9/2015 8:36 PM, Iremonger, Bernard wrote:
> correct sample console commands
>
> Fixes: d0dff9ba445e ("doc: sample application user guide"
> Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
> Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
> Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
Acked-by: Huawei Xie <huawei.xie@intel.com>

Thanks.
[...]
Mcnamara, John Dec. 9, 2015, 2:43 p.m. UTC | #2
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bernard Iremonger
> Sent: Wednesday, December 9, 2015 12:36 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH 1/1] doc: correct Vhost Sample Application
> guide
> 
> correct sample console commands
> 
> Fixes: d0dff9ba445e ("doc: sample application user guide"
> Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
> Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
> Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>

Hi Bernard,

Thanks for that. One comment (in several places):


>      .. code-block:: console
> 
> -        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
> +        user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost

These long lines in code blocks don't render correctly in the PDF docs. The 
Documentation Guidelines suggest using a commandline line continuation
to maintain functionality within an 80 char doc limit:

   http://dpdk.org/doc/guides/contributing/documentation.html#code-and-literal-block-sections

So something like this:

    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost

Could be written as:

    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 \
                         --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost

Or: 

    user@target:~$ ./build/app/vhost-switch -c f -n 4 \
                                            --socket-mem 1024 \
                                            --huge-dir /mnt/huge \
                                            -- -p 0x1 --dev-basename usvhost

Regards,

John.
--
Mcnamara, John Dec. 9, 2015, 2:50 p.m. UTC | #3
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bernard Iremonger
> Sent: Wednesday, December 9, 2015 12:36 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH 1/1] doc: correct Vhost Sample Application
> guide
> 
> correct sample console commands
> 
> Fixes: d0dff9ba445e ("doc: sample application user guide"
> Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
> Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
> Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
> ---
>  doc/guides/sample_app_ug/vhost.rst | 40 +++++++++++++++++++--------------
>
> ...
> 
>      Redistribution and use in source and binary forms, with or without @@
> -386,13 +386,13 @@ Running the Sample Code
> 
>      .. code-block:: console
> 
> -        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /


Also, as a general note, not just to this document/patch.

I don't think the "user@target:~$" prefixes used in some DPDK
Doc commandlines is useful.

It prevents a straight copy and paste for testing, it makes the
literal block lines longer than they should be, it isn't used
consistently everywhere, it is visually distracting (in some
cases it is longer than the command being shown), and it isn't
always correct (I presume in the above case of "user@target" you
would need run the application as sudo if you are a non root
user).

Any objections to removing these as documents are updated?


John
Thomas Monjalon Dec. 9, 2015, 3:09 p.m. UTC | #4
2015-12-09 14:50, Mcnamara, John:
> Also, as a general note, not just to this document/patch.
> 
> I don't think the "user@target:~$" prefixes used in some DPDK
> Doc commandlines is useful.
> 
> It prevents a straight copy and paste for testing, it makes the
> literal block lines longer than they should be, it isn't used
> consistently everywhere, it is visually distracting (in some
> cases it is longer than the command being shown), and it isn't
> always correct (I presume in the above case of "user@target" you
> would need run the application as sudo if you are a non root
> user).
> 
> Any objections to removing these as documents are updated?

Generally speaking, +1 to remove extra bytes :)
Bernard Iremonger Dec. 9, 2015, 4:10 p.m. UTC | #5
Hi John,

<snip>

> Hi Bernard,
> 
> Thanks for that. One comment (in several places):
> 
> 
> >      .. code-block:: console
> >
> > -        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir
> /mnt/huge -- -p 0x1 --dev-basename usvhost
> > +        user@target:~$ ./build/app/vhost-switch -c f -n 4
> > + --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename
> > + usvhost
> 
> These long lines in code blocks don't render correctly in the PDF docs. The
> Documentation Guidelines suggest using a commandline line continuation to
> maintain functionality within an 80 char doc limit:
> 
>    http://dpdk.org/doc/guides/contributing/documentation.html#code-and-
> literal-block-sections
> 
> So something like this:
> 
>     user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --
> huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
> 
> Could be written as:
> 
>     user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 \
>                          --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
> 
> Or:
> 
>     user@target:~$ ./build/app/vhost-switch -c f -n 4 \
>                                             --socket-mem 1024 \
>                                             --huge-dir /mnt/huge \
>                                             -- -p 0x1 --dev-basename usvhost
> 
> Regards,
> 
> John.
> --

I will use a command line continuation character to stay within 80 character limit.

Regards,

Bernard.
Bernard Iremonger Dec. 9, 2015, 4:14 p.m. UTC | #6
Hi John,
<snip>

> 2015-12-09 14:50, Mcnamara, John:
> > Also, as a general note, not just to this document/patch.
> >
> > I don't think the "user@target:~$" prefixes used in some DPDK Doc
> > commandlines is useful.
> >
> > It prevents a straight copy and paste for testing, it makes the
> > literal block lines longer than they should be, it isn't used
> > consistently everywhere, it is visually distracting (in some cases it
> > is longer than the command being shown), and it isn't always correct
> > (I presume in the above case of "user@target" you would need run the
> > application as sudo if you are a non root user).
> >
> > Any objections to removing these as documents are updated?
> 
> Generally speaking, +1 to remove extra bytes :)

I will remove the "user@target:~$"  prefixes in this document.

Regards,

Bernard.
Yuanhan Liu Dec. 10, 2015, 6:40 a.m. UTC | #7
On Wed, Dec 09, 2015 at 04:14:01PM +0000, Iremonger, Bernard wrote:
> Hi John,
> <snip>
> 
> > 2015-12-09 14:50, Mcnamara, John:
> > > Also, as a general note, not just to this document/patch.
> > >
> > > I don't think the "user@target:~$" prefixes used in some DPDK Doc
> > > commandlines is useful.
> > >
> > > It prevents a straight copy and paste for testing, it makes the
> > > literal block lines longer than they should be, it isn't used
> > > consistently everywhere, it is visually distracting (in some cases it
> > > is longer than the command being shown), and it isn't always correct
> > > (I presume in the above case of "user@target" you would need run the
> > > application as sudo if you are a non root user).
> > >
> > > Any objections to removing these as documents are updated?
> > 
> > Generally speaking, +1 to remove extra bytes :)
> 
> I will remove the "user@target:~$"  prefixes in this document.

I'd personally suggest to keep the "$ " prefix, or "# " if it needs
root privilege. Which is a convention to paste commands.

	--yliu

Patch
diff mbox

diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst
index ceeaf52..70d31b6 100644
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -1,6 +1,6 @@ 
 
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -386,13 +386,13 @@  Running the Sample Code
 
     .. code-block:: console
 
-        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost
+        user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
 
     vhost user: a socket file named usvhost will be created under current directory. Use its path as the socket path in guest's qemu commandline.
 
     .. code-block:: console
 
-        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost
+        user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
 
 .. note::
 
@@ -411,7 +411,7 @@  For compatibility with the QEMU wrapper script, a base name of "usvhost" should
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
 
 **vm2vm.**
 The vm2vm parameter disable/set mode of packet switching between guests in the host.
@@ -424,7 +424,7 @@  which bases on the packet destination MAC address and VLAN tag.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- --vm2vm [0,1,2]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --vm2vm [0,1,2]
 
 **Mergeable Buffers.**
 The mergeable buffers parameter controls how virtio-net descriptors are used for virtio-net headers.
@@ -434,7 +434,7 @@  The default value is 0 or disabled since recent kernels virtio-net drivers show
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- --mergeable [0,1]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --mergeable [0,1]
 
 **Stats.**
 The stats parameter controls the printing of virtio-net device statistics.
@@ -442,7 +442,7 @@  The parameter specifies an interval second to print statistics, with an interval
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- --stats [0,n]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --stats [0,n]
 
 **RX Retry.**
 The rx-retry option enables/disables enqueue retries when the guests RX queue is full.
@@ -452,7 +452,7 @@  This option is enabled by default.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- --rx-retry [0,1]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --rx-retry [0,1]
 
 **RX Retry Number.**
 The rx-retry-num option specifies the number of retries on an RX burst,
@@ -461,7 +461,7 @@  The default value is 4.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- --rx-retry 1 --rx-retry-num 5
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --rx-retry 1 --rx-retry-num 5
 
 **RX Retry Delay Time.**
 The rx-retry-delay option specifies the timeout (in micro seconds) between retries on an RX burst,
@@ -470,7 +470,7 @@  The default value is 15.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- --rx-retry 1 --rx-retry-delay 20
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --rx-retry 1 --rx-retry-delay 20
 
 **Zero copy.**
 The zero copy option enables/disables the zero copy mode for RX/TX packet,
@@ -481,7 +481,7 @@  This option is disabled by default.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- --zero-copy [0,1]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --zero-copy [0,1]
 
 **RX descriptor number.**
 The RX descriptor number option specify the Ethernet RX descriptor number,
@@ -494,7 +494,7 @@  So it is valid only in zero copy mode is enabled. The value is 32 by default.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- --zero-copy 1 --rx-desc-num [0, n]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --zero-copy 1 --rx-desc-num [0, n]
 
 **TX descriptor number.**
 The TX descriptor number option specify the Ethernet TX descriptor number, it is valid only in zero copy mode is enabled.
@@ -502,7 +502,7 @@  The value is 64 by default.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- --zero-copy 1 --tx-desc-num [0, n]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --zero-copy 1 --tx-desc-num [0, n]
 
 **VLAN strip.**
 The VLAN strip option enable/disable the VLAN strip on host, if disabled, the guest will receive the packets with VLAN tag.
@@ -510,7 +510,7 @@  It is enabled by default.
 
 .. code-block:: console
 
-    user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- --vlan-strip [0, 1]
+    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- --vlan-strip [0, 1]
 
 Running the Virtual Machine (QEMU)
 ----------------------------------
@@ -539,7 +539,7 @@  QEMU must be executed with specific parameters to:
 
     .. code-block:: console
 
-        user@target:~$ qemu-system-x86_64 ... -mem-prealloc -mem-path / dev/hugepages ...
+        user@target:~$ qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...
 
 .. note::
 
@@ -573,7 +573,7 @@  In this case, the path passed to the guest should be that of the 1 GB page huget
 
 .. code-block:: console
 
-    user@target:~$ qemu-system-x86_64 ... -mem-prealloc -mem-path / dev/hugepages ...
+    user@target:~$ qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...
 
 .. note::
 
@@ -771,21 +771,21 @@  Run the testpmd application as follows:
 
 .. code-block:: console
 
-    user@target:~$ x86_64-native-linuxapp-gcc/app/testpmd -c 0x3 -- n 4 -socket-mem 128 -- --burst=64 -i
+    user@target:~$ x86_64-native-linuxapp-gcc/app/testpmd -c 0x3 -n 4 --socket-mem 512 -- --burst=64 --i --disable-hw-vlan-filter
 
 The destination MAC address for packets transmitted on each port can be set at the command line:
 
 .. code-block:: console
 
-    user@target:~$ x86_64-native-linuxapp-gcc/app/testpmd -c 0x3 -- n 4 -socket-mem 128 -- --burst=64 -i --eth- peer=0,aa:bb:cc:dd:ee:ff --eth-peer=1,ff,ee,dd,cc,bb,aa
+    user@target:~$ x86_64-native-linuxapp-gcc/app/testpmd -c 0x3 -n 4 --socket-mem 512 -- --burst=64 --i --disable-hw-vlan-filter --eth-peer=0,aa:bb:cc:dd:ee:ff --eth-peer=1,ff:ee:dd:cc:bb:aa
 
 *   Packets received on port 1 will be forwarded on port 0 to MAC address
 
-    aa:bb:cc:dd:ee:ff.
+    aa:bb:cc:dd:ee:ff
 
 *   Packets received on port 0 will be forwarded on port 1 to MAC address
 
-    ff,ee,dd,cc,bb,aa.
+    ff:ee:dd:cc:bb:aa
 
 The testpmd application can then be configured to act as an L2 forwarding application: