From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id BF4B64401C; Mon, 13 May 2024 18:02:28 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id B9C0840DCD; Mon, 13 May 2024 18:01:44 +0200 (CEST) Received: from mail-pf1-f179.google.com (mail-pf1-f179.google.com [209.85.210.179]) by mails.dpdk.org (Postfix) with ESMTP id 4E6FF4068E for ; Mon, 13 May 2024 17:59:47 +0200 (CEST) Received: by mail-pf1-f179.google.com with SMTP id d2e1a72fcca58-6f44bcbaae7so4065639b3a.2 for ; Mon, 13 May 2024 08:59:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1715615986; x=1716220786; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=fjmTry2NeZgJJ1Rj4aw47Bopi2Et1pkxZannefL0ELM=; b=fFZKhOR2pY/ypfAzx/Ey29KEnNRl8UP178OSEPfY00rz5NGZat6JQzGc1bpgdlgH/N +EZWyN13lJzLoKgFDs9FGE72qvQAE3hfy3AR2aD2Sl6DwMm+X0KLqwAlKF7J0QuswVtM GaViu/beV+No3OC3Ar2i4qsLyh5bEkgBK+fdp6FlyO0bSzD7WcvRGtrHbh2TQEP77MBB a5Jn9fGHu/k/vI//Gigf564oVUycShNkmgqDsUgr0pMPk43o64vvNzEtNef7lXImh6S9 Z37gWRKqTq2FA/yU9G5kbgFLiGhN3MkfsmJ/4aoFGA3GX5iWB44RGRMIqbDTxoWF1rzT VIdw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1715615986; x=1716220786; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=fjmTry2NeZgJJ1Rj4aw47Bopi2Et1pkxZannefL0ELM=; b=fmug2KCfm3PAczcZdSy0jV1293WrMpkSH+kZavh9hTcbc26cmFH6FLHIsKBpKDGLXv KpxLBTYQMK2yyiUowEc8gkPQQBT4Gi1KuykayNDLmr9J1lhRCrcJB9cPRVafTYx91n7h FCHvn7wz5q6p+Qd5EcRlPkuth0ZtK2TIEn2c1WNkxmBy8NzHSoSpUFCrg5q58IpkPsHa DUqRWEIN/gVj7H7I/0AdWd4ujYj8Mn2VTlJ0LiMH7qkANp3IVm7D5w0oB3HzCIK0cqOW ua4UTupoa/dqSBW4H20iJEm9bjLqvOJTlWUfxZ1mYrluC9K5ougKGbOVp74mdAQR9AZN 05wA== X-Gm-Message-State: AOJu0YyEdxC8HY4w0IqpR7VdceJbjlwMxtIw7Unu6V0hCOCzNtySIMxF clNmK1NFFMEp4zE72KUmUcJ7KqhIwCsRQnwcLEjoONCGpCB4aX8V/CFYFA== X-Google-Smtp-Source: AGHT+IGpDnxIZwhhXWQi6B+rkHuh8k3c6iZNy3iSWOwN8En6O9ukyolqEYw/5Zj1XUs280H11Hyfhg== X-Received: by 2002:a05:6a00:3a0b:b0:6ec:f2e7:21a8 with SMTP id d2e1a72fcca58-6f4e0346677mr10957713b3a.21.1715615986069; Mon, 13 May 2024 08:59:46 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-6f4d2aa16dfsm7715078b3a.93.2024.05.13.08.59.45 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 May 2024 08:59:45 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH 7/9] doc: reword cmdline section in prog guide Date: Mon, 13 May 2024 08:59:09 -0700 Message-Id: <20240513155911.31872-8-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240513155911.31872-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Mailman-Approved-At: Mon, 13 May 2024 18:01:34 +0200 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org minor syntax edits Signed-off-by: Nandini Persad --- doc/guides/prog_guide/cmdline.rst | 34 +++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/guides/prog_guide/cmdline.rst b/doc/guides/prog_guide/cmdline.rst index 6b10ab6c99..8aa1ef180b 100644 --- a/doc/guides/prog_guide/cmdline.rst +++ b/doc/guides/prog_guide/cmdline.rst @@ -62,7 +62,7 @@ The format of the list file must follow these requirements: * One command per line -* Variable fields are prefixed by the type-name in angle-brackets, for example: +* Variable fields are prefixed by the type-name in angle-brackets. For example: * ``message`` @@ -75,7 +75,7 @@ The format of the list file must follow these requirements: * ``dst_ip6`` * Variable fields, which take their values from a list of options, - have the comma-separated option list placed in braces, rather than by the type name. + have the comma-separated option list placed in braces rather than by the type name. For example, * ``<(rx,tx,rxtx)>mode`` @@ -112,7 +112,7 @@ The generated content includes: * A command-line context array definition, suitable for passing to ``cmdline_new`` -If so desired, the script can also output function stubs for the callback functions for each command. +If needed, the script can also output function stubs for the callback functions for each command. This behaviour is triggered by passing the ``--stubs`` flag to the script. In this case, an output file must be provided with a filename ending in ".h", and the callback stubs will be written to an equivalent ".c" file. @@ -120,7 +120,7 @@ and the callback stubs will be written to an equivalent ".c" file. .. note:: The stubs are written to a separate file, - to allow continuous use of the script to regenerate the command-line header, + to allow continuous use of the script to regenerate the command-line header without overwriting any code the user has added to the callback functions. This makes it easy to incrementally add new commands to an existing application. @@ -154,7 +154,7 @@ the callback functions would be: These functions must be provided by the developer. However, as stated above, stub functions may be generated by the script automatically using the ``--stubs`` parameter. -The same "cmdname" stem is used in the naming of the generated structures too. +The same "cmdname" stem is used in the naming of the generated structures as well. To get to the results structure for each command above, the ``parsed_result`` parameter should be cast to ``struct cmd_quit_result`` or ``struct cmd_show_port_stats_result`` respectively. @@ -176,13 +176,12 @@ Integrating with the Application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To integrate the script output with the application, -we must ``#include`` the generated header into our applications C file, +we must ``#include`` the generated header into our application's C file, and then have the command-line created via either ``cmdline_new`` or ``cmdline_stdin_new``. The first parameter to the function call should be the context array in the generated header file, ``ctx`` by default (Modifiable via script parameter). -The callback functions may be in this same file, or in a separate one - -they just need to be available to the linker at build-time. +The callback functions may be in the same or separate file, as long as they are available to the linker at build-time. Limitations of the Script Approach ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -242,19 +241,19 @@ The resulting struct looks like: As before, we choose names to match the tokens in the command. Since our numeric parameter is a 16-bit value, we use ``uint16_t`` type for it. -Any of the standard sized integer types can be used as parameters, depending on the desired result. +Any of the standard-sized integer types can be used as parameters depending on the desired result. Beyond the standard integer types, -the library also allows variable parameters to be of a number of other types, +the library also allows variable parameters to be of a number of other types as called out in the feature list above. * For variable string parameters, the type should be ``cmdline_fixed_string_t`` - the same as for fixed tokens, but these will be initialized differently (as described below). -* For ethernet addresses use type ``struct rte_ether_addr`` +* For ethernet addresses, use type ``struct rte_ether_addr`` -* For IP addresses use type ``cmdline_ipaddr_t`` +* For IP addresses, use type ``cmdline_ipaddr_t`` Providing Field Initializers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -267,6 +266,7 @@ For fixed string tokens, like "quit", "show" and "port", the initializer will be static cmdline_parse_token_string_t cmd_quit_quit_tok = TOKEN_STRING_INITIALIZER(struct cmd_quit_result, quit, "quit"); + The convention for naming used here is to include the base name of the overall result structure - ``cmd_quit`` in this case, as well as the name of the field within that structure - ``quit`` in this case, followed by ``_tok``. @@ -311,8 +311,8 @@ The callback function should have type: where the first parameter is a pointer to the result structure defined above, the second parameter is the command-line instance, and the final parameter is a user-defined pointer provided when we associate the callback with the command. -Most callback functions only use the first parameter, or none at all, -but the additional two parameters provide some extra flexibility, +Most callback functions only use the first parameter or none at all, +but the additional two parameters provide some extra flexibility to allow the callback to work with non-global state in your application. For our two example commands, the relevant callback functions would look very similar in definition. @@ -341,7 +341,7 @@ Associating Callback and Command The ``cmdline_parse_inst_t`` type defines a "parse instance", i.e. a sequence of tokens to be matched and then an associated function to be called. -Also included in the instance type are a field for help text for the command, +Also included in the instance type are a field for help text for the command and any additional user-defined parameter to be passed to the callback functions referenced above. For example, for our simple "quit" command: @@ -362,8 +362,8 @@ then set the user-defined parameter to NULL, provide a help message to be given, on request, to the user explaining the command, before finally listing out the single token to be matched for this command instance. -For our second, port stats, example, -as well as making things a little more complicated by having multiple tokens to be matched, +For our second "port stats" example, +as well as making things more complex by having multiple tokens to be matched, we can also demonstrate passing in a parameter to the function. Let us suppose that our application does not always use all the ports available to it, but instead only uses a subset of the ports, stored in an array called ``active_ports``. -- 2.34.1