From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id B0476A0524 for ; Tue, 25 Feb 2020 11:35:44 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id A88F9B62; Tue, 25 Feb 2020 11:35:44 +0100 (CET) Received: from mail-pl1-f178.google.com (mail-pl1-f178.google.com [209.85.214.178]) by dpdk.org (Postfix) with ESMTP id 522101BF8D for ; Tue, 25 Feb 2020 11:35:43 +0100 (CET) Received: by mail-pl1-f178.google.com with SMTP id g6so5328420plt.2 for ; Tue, 25 Feb 2020 02:35:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id:in-reply-to:references; bh=cEO7cFnoHBZgk3D9U9x+AVmxn1DrODvBHroKl9VV0GQ=; b=TXTCIPpVWJ1o3k3maxatulA+PaxxxPTGEpRoUKfajh++BThsS4a5NYSjw1MYO1Xbz/ UunHu3XIm4xepKDnJ0deCdR3UKZiecX73oco4hE8iGvNEdGdSFJLcdezZRcouXs8Dk+e UkbXVcoNiGt05wEAJqxx5KYWAZMaS8Bak2/qWTltUKCtSzYc4Cepxx1e1U7KLcogRjUx nppoOU6fa/DpodERtOe0CWpZ2als936mlsn/BtWdIsKi7VOxZost0EIRNdSUUhHxMo/v hIe9oUEL/IqXqYB/x39Cix3Idwvjgl+tmuIUvkYeTMzylI5SGjjve1dV7QupaJGZBmgs PsaQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references; bh=cEO7cFnoHBZgk3D9U9x+AVmxn1DrODvBHroKl9VV0GQ=; b=PwM7CVwr7e8Y0s2Tz9H+iGLt1cZsWjZe7fJLaIEIS30NfRo6KCRmOq30tZSMipCq7j JR8WJYzfwAGDQt9vMMhLq0IcdrahTBhIAPzt9f5yvdgoEROQoj2t9Gxsxd4NDTcehQff yyLrkUI9txyOO4dXTfNSUdrbMfW9p/r990lQ/KAqDbYn0MVhtpZMbw8Y31MTnvGb9s3N zllb9Wlvk53T50HPN0rHe7qeSWECmO5AsGz3isROdlfJN1KiN7PYiHEy1PeEmFu+S8oK MvHj9/YBDSIyh6UCudlGyUq5mNHeXesKWO34N7fEum814gIWl9Wtez2whIEP/6cRmfQo s3wQ== X-Gm-Message-State: APjAAAUwhQUjrm67Ztyob1Svxzi8woZ4ccu9zXdmwdnZeBURdTxygmL4 fyhMEv74ftCOoEebZSlqYTjEE0Bj X-Google-Smtp-Source: APXvYqxp+Qw+67xgejfYp5kf1DV+pZRGOQqGfmreSHjfDyvZbwVHpF33wZ847norNvAL1aJlaRMbDg== X-Received: by 2002:a17:90a:6:: with SMTP id 6mr4531056pja.71.1582626941936; Tue, 25 Feb 2020 02:35:41 -0800 (PST) Received: from localhost.localdomain ([2400:4050:c8c2:de00:35bc:b9a3:f404:3cf2]) by smtp.gmail.com with ESMTPSA id a10sm15819987pgk.71.2020.02.25.02.35.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 02:35:41 -0800 (PST) From: Yasufumi Ogawa To: spp@dpdk.org, ferruh.yigit@intel.com, yasufum.o@gmail.com Date: Tue, 25 Feb 2020 19:34:46 +0900 Message-Id: <20200225103446.8243-30-yasufum.o@gmail.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200225103446.8243-1-yasufum.o@gmail.com> References: <20200225103446.8243-1-yasufum.o@gmail.com> Subject: [spp] [PATCH 29/29] docs: update howto define app container guide X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: spp-bounces@dpdk.org Sender: "spp" Update contents of `How to Define Your App Launcher` because implemention is changed. Signed-off-by: Yasufumi Ogawa --- 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