Soft Patch Panel
 help / color / mirror / Atom feed
From: Yasufumi Ogawa <yasufum.o@gmail.com>
To: spp@dpdk.org, ferruh.yigit@intel.com, yasufum.o@gmail.com
Subject: [spp] [PATCH 29/29] docs: update howto define app container guide
Date: Tue, 25 Feb 2020 19:34:46 +0900
Message-ID: <20200225103446.8243-30-yasufum.o@gmail.com> (raw)
In-Reply-To: <20200225103446.8243-1-yasufum.o@gmail.com>

Update contents of `How to Define Your App Launcher` because
implemention is changed.

Signed-off-by: Yasufumi Ogawa <yasufum.o@gmail.com>
---
 docs/guides/tools/sppc/howto_launcher.rst | 210 +++++++++-------------
 1 file changed, 85 insertions(+), 125 deletions(-)

diff --git a/docs/guides/tools/sppc/howto_launcher.rst b/docs/guides/tools/sppc/howto_launcher.rst
index 77c4bf8..3f21f4a 100644
--- a/docs/guides/tools/sppc/howto_launcher.rst
+++ b/docs/guides/tools/sppc/howto_launcher.rst
@@ -61,10 +61,10 @@ DPDK Sample App Container
 
 Procedure of App container script is defined in main() and
 consists of three steps of
-(1)parsing options, (2)building docker command and
-(3)application command run inside the container.
+(1) parsing options, (2) setup docker command and
+(3) application command run inside the container.
 
-Here is a sample code of :ref:`sppc_appl_helloworld`.
+Here is a sample code of :ref:`sppc_appl_l2fwd`.
 ``parse_args()`` is defined in each
 of app container scripts to parse all of EAL, docker and application
 specific options.
@@ -78,30 +78,48 @@ for parsing the arguments.
     def main():
         args = parse_args()
 
+        # Container image name such as 'sppc/dpdk-ubuntu:18.04'
+        if args.container_image is not None:
+            container_image = args.container_image
+        else:
+            container_image = common.container_img_name(
+                common.IMG_BASE_NAMES['dpdk'],
+                args.dist_name, args.dist_ver)
+
         # Check for other mandatory opitons.
-        if args.dev_ids is None:
-            common.error_exit('--dev-ids')
+        if args.port_mask is None:
+            common.error_exit('--port-mask')
+
+If the name of container is given via ``args.container_image``, it is
+decided as a combination of basename, distribution and its version.
+Basenames are defined as ``IMG_BASE_NAMES`` in ``lib/common.py``.
+In general, You do not need to change for using DPDK sample apps.
+
+.. code-block:: python
 
-        # Setup for vhost devices with given device IDs.
-        dev_ids_list = app_helper.dev_ids_to_list(args.dev_ids)
-        sock_files = app_helper.sock_files(dev_ids_list)
+    # defined in lib/common.py
+    IMG_BASE_NAMES = {
+        'dpdk': 'sppc/dpdk',
+        'pktgen': 'sppc/pktgen',
+        'spp': 'sppc/spp',
+        'suricata': 'sppc/suricata',
+        }
 
-Each of options is accessible as ``args.dev_ids`` or
-``args.core_list``.
-Before step (2) and (3), you had better to check given option,
+Options can be referred via ``args``. For example, the name of container
+image can be referred via ``args.container_image``.
+
+Before go to step (2) and (3), you had better to check given option,
 expecially mandatory options.
-In this case, ``--dev-ids`` is the mandatory and you should terminate
-the application if it is not given.
 ``common.error_exit()`` is a helper method to print an error message
-for given option and do ``exit()``.
+for given option and do ``exit()``. In this case, ``--port-mask`` must
+be given, or exit with an error message.
 
-Setup of ``dev_ids_list`` and ``sock_files`` is required for launching
-container.
-``lib/app_helper.py`` defines helper functions commonly used
-for app containers.
+Setup of ``sock_files`` is required for creating network interfaces
+for the container. ``sock_files()`` defined in ``lib/app_helper.py`` is
+provided for creating socket files from given device UIDs.
 
 Then, setup docker command and its options as step (2).
-Docker options are setup by using helper method
+Docker options are added by using helper method
 ``setup_docker_opts()`` which generates commonly used options for app
 containers.
 This methods returns a list of a part of options to give it to
@@ -111,73 +129,43 @@ This methods returns a list of a part of options to give it to
 
     # Setup docker command.
     docker_cmd = ['sudo', 'docker', 'run', '\\']
-    docker_opts = app_helper.setup_docker_opts(
-        args, target_name, sock_files)
-
-You should notice a option ``target_name``.
-It is used as a label to choose which of container image you use.
-The name of container image is defined as a combination of basename,
-distribution name and version.
-Basename is defined as a member of ``CONTAINER_IMG_NAME`` in
-``conf/env.py``.
-
-.. code-block:: python
-
-    # defined in conf/env.py
-    CONTAINER_IMG_NAME = {
-        'dpdk': 'sppc/dpdk',
-        'pktgen': 'sppc/pktgen',
-        'spp': 'sppc/spp'}
-
-This usecase is for DPDK sample app, so you should define target as
-``dpdk``.
-You do not need to change for using DPDK sample apps in general.
-But it can be changed by using other target name.
-For example, if you give target ``pktgen`` and
-use default dist name and verion of ``ubuntu`` and ``latest``,
-The name of image is ``sppc/pktgen-ubuntu:latest``.
-
-For using images other than defined above, you can override it with
-``--container-image`` option.
-It enables to use any of container images and applications.
+    docker_opts = app_helper.setup_docker_opts(args, sock_files)
 
-You also notice that ``docker_cmd`` has ``\\`` at the end of the list.
+You also notice that ``docker_cmd`` has a backslash ``\\`` at the end of
+the list.
 It is only used to format the printed command on the terminal.
-If you do no care about formatting, you do not need to add it.
+If you do no care about formatting, you do not need to add this character.
 
 Next step is (3), to setup the application command.
-You should change ``cmd_path`` and ``file_prefix`` to specify
-the application.
-For ``cmd_path``, ``helloworld`` should be changed to other name of
-application, for example,
+You should change ``cmd_path`` to specify your application.
+In ``app/l2fwd.py``, the application compiled under ``RTE_SDK`` in DPDK's
+directory, but your application might be different.
 
 .. code-block:: python
 
-    # Setup helloworld run on container.
-    cmd_path = '%s/examples/helloworld/%s/helloworld' % (
-        env.RTE_SDK, env.RTE_TARGET)
+    # Setup l2fwd command run on container.
+    cmd_path = '{0:s}/examples/{2:s}/{1:s}/{2:s}'.format(
+        env.RTE_SDK, env.RTE_TARGET, APP_NAME)
 
-    hello_cmd = [cmd_path, '\\']
+    l2fwd_cmd = [cmd_path, '\\']
 
-    file_prefix = 'spp-hello-container%d' % dev_ids_list[0]
-    eal_opts = app_helper.setup_eal_opts(args, file_prefix)
+    # Setup EAL options.
+    eal_opts = app_helper.setup_eal_opts(args, APP_NAME)
 
-    # No application specific options for helloworld
-    hello_opts = []
+    # Setup l2fwd options.
+    l2fwd_opts = ['-p', args.port_mask, '\\']
 
-``file_prefix`` for EAL option should be unique on the system
-because it is used as the name of hugepage file.
-In SPP container, it is a combination of fixed text and vhost device ID
-because this ID is unique in SPP container and cannot be overlapped,
-at least among app containers in SPP container.
-EAL options are also generated by helper method.
+While setting up EAL option in ``setup_eal_opts()``, ``--file-prefix`` is
+generated by using the name of application and a random number. It should
+be unique on the system because it is used as the name of hugepage file.
 
-Finally, combine all of commands and its options and launch
-from ``subprocess.call()``.
+Finally, combine command and all of options before launching from
+``subprocess.call()``.
 
 .. code-block:: python
 
-    cmds = docker_cmd + docker_opts + hello_cmd + eal_opts + hello_opts
+    cmds = docker_cmd + docker_opts + [container_image, '\\'] + \
+        l2fwd_cmd + eal_opts + l2fwd_opts
     if cmds[-1] == '\\':
         cmds.pop()
     common.print_pretty_commands(cmds)
@@ -190,20 +178,17 @@ from ``subprocess.call()``.
         cmds.remove('\\')
     subprocess.call(cmds)
 
-All of commands and options are combined in to a list ``cmds``
-to give it to ``subprocess.call()``.
-You can ignore procedures for ``\\`` and
-``common.print_pretty_commands()``
-if you do not care about printing commands in the terminal.
-However, you should not to shortcut for ``args.dry_run`` because
-it is very important for users to check the command syntax
-before running it.
+There are some optional behaviors in the final step.
+``common.print_pretty_commands()`` replaces ``\\`` with a newline character
+and prints command line in pretty format.
+If you give ``--dry-run`` option, this launcher script prints command line
+and exits without launching container.
 
 
-.. _sppc_howto_dpdk_appc_nots:
+.. _sppc_howto_none_dpdk_sample_apps:
 
-App Container not for DPDK Sample
----------------------------------
+None DPDK Sample Applications in Container
+------------------------------------------
 
 There are several application using DPDK but not included in
 `sample applications
@@ -247,61 +232,36 @@ For your application, you can simply add options to ``parser`` object.
     def main():
         args = parse_args()
 
-        # Setup for vhost devices with given device IDs.
-        dev_ids_list = app_helper.dev_ids_to_list(args.dev_ids)
-        sock_files = app_helper.sock_files(dev_ids_list)
-
-        # Setup docker command.
-        docker_cmd = ['sudo', 'docker', 'run', '\\']
-        docker_opts = app_helper.setup_docker_opts(
-            args, target_name, sock_files,
-            '%s/../pktgen-dpdk' % env.RTE_SDK)
-
-        cmd_path = '%s/../pktgen-dpdk/app/%s/pktgen' % (
-            env.RTE_SDK, env.RTE_TARGET)
-
-Setup for docker command is the same as the example.
-The ``terget_name`` might be different from the image you will use,
-but you do not need to care about which of container image is used
-because it is overriden with given image with ``--container-image``
-option.
-However, you should care about the path of application ``cmd_path``
-which is run in the container.
-
-Then, you should decide ``file_prefix`` to your application container
-be unique on the system.
-The ``file_prefix`` of SPP container is named as
-``spp-[APP_NAME]-container[VHOST_ID]`` convensionally to it be unique.
+Setup of socket files for network interfaces is the same as DPDK sample apps.
+However, you might need to change paht of command  which is run in the
+container. In ``app/pktgen.py``, directory of ``pktgen`` is defined as
+``wd``, and the name of application s defined as ``APP_NAME``.
+This directory can be changed with ``--workdir`` option.
 
 .. code-block:: python
 
-    # Setup pktgen command
-    pktgen_cmd = [cmd_path, '\\']
-
-    file_prefix = 'spp-pktgen-container%d' % dev_ids_list[0]
-    eal_opts = app_helper.setup_eal_opts(args, file_prefix)
-
-You should check the arguments for the application.
-
-.. code-block:: python
+    # Setup docker command.
+    if args.workdir is not None:
+        wd = args.workdir
+    else:
+        wd = '/root/pktgen-dpdk'
+    docker_cmd = ['sudo', 'docker', 'run', '\\']
+    docker_opts = app_helper.setup_docker_opts(args, sock_files, None, wd)
 
-    ...
-    if args.pcap_file is not None:
-        pktgen_opts += ['-s', args.pcap_file, '\\']
+    # Setup pktgen command
+    pktgen_cmd = [APP_NAME, '\\']
 
-    if args.script_file is not None:
-        pktgen_opts += ['-f', args.script_file, '\\']
+    # Setup EAL options.
+    eal_opts = app_helper.setup_eal_opts(args, APP_NAME)
 
-    if args.log_file is not None:
-        pktgen_opts += ['-l', args.log_file, '\\']
-    ...
 
 Finally, combine all of commands and its options and launch
 from ``subprocess.call()``.
 
 .. code-block:: python
 
-    cmds = docker_cmd + docker_opts + pktgen_cmd + eal_opts + pktgen_opts
+    cmds = docker_cmd + docker_opts + [container_image, '\\'] + \
+        pktgen_cmd + eal_opts + pktgen_opts
     if cmds[-1] == '\\':
         cmds.pop()
     common.print_pretty_commands(cmds)
-- 
2.17.1


      parent reply	other threads:[~2020-02-25 10:35 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-25 10:34 [spp] [PATCH 00/29] Update SPP Container tools Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 01/29] tools/sppc: update options for assigning devices Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 02/29] tools/sppc: update dev options of l2fwd Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 03/29] tools/sppc: add container name option Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 04/29] tools/sppc: update l2fwd app for " Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 05/29] tools/sppc: update dev options of l3fwd Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 06/29] tools/sppc: update dev options of l3fwd-acl Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 07/29] tools/sppc: update dev options of testpmd Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 08/29] tools/sppc: update dev options of pktgen Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 09/29] tools/sppc: update dev options of load-balancer Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 10/29] tools/sppc: version checker for container DPDK ver Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 11/29] tools/sppc: check DPDK ver in load-balancer Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 12/29] tools/sppc: setup spp_pri opts in app_helper Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 13/29] tools/sppc: define file prefix for SPP Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 14/29] tools/sppc: update dev options of spp_primary Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 15/29] tools/sppc: setup with docker opts in SPP pri Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 16/29] tools/sppc: update calling setup_docker_opts() Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 17/29] tools/sppc: update dev options of helloworld Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 18/29] tools/sppc: update dev options of suricata Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 19/29] tools/sppc: update dev options of spp_nfv Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 20/29] tools/sppc: change to gen EAL opts with app name Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 21/29] tools/sppc: remove nouse variable Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 22/29] bin: remove sock files created by docker Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 23/29] tools/sppc: skip checking rule file if dry run Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 24/29] docs: revise examples in sppc Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 25/29] docs: update versions in " Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 26/29] docs: update old example in spp_primary container Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 27/29] tools/sppc: python3 support for sppc build tool Yasufumi Ogawa
2020-02-25 10:34 ` [spp] [PATCH 28/29] docs: update app container help msg Yasufumi Ogawa
2020-02-25 10:34 ` Yasufumi Ogawa [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200225103446.8243-30-yasufum.o@gmail.com \
    --to=yasufum.o@gmail.com \
    --cc=ferruh.yigit@intel.com \
    --cc=spp@dpdk.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Soft Patch Panel

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/spp/0 spp/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 spp spp/ https://inbox.dpdk.org/spp \
		spp@dpdk.org
	public-inbox-index spp

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.spp


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git