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 7462C4401C; Mon, 13 May 2024 18:02:20 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id B2ECF40A89; Mon, 13 May 2024 18:01:43 +0200 (CEST) Received: from mail-pf1-f176.google.com (mail-pf1-f176.google.com [209.85.210.176]) by mails.dpdk.org (Postfix) with ESMTP id 424F84068E for ; Mon, 13 May 2024 17:59:44 +0200 (CEST) Received: by mail-pf1-f176.google.com with SMTP id d2e1a72fcca58-6f4f2b1c997so1629262b3a.0 for ; Mon, 13 May 2024 08:59:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1715615983; x=1716220783; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=vmzpZMXRQ1wNyRuj1P7z4ooSWBsAJZ0JhU9+Vv186kg=; b=Fruy1WqzZcGgY3l3fWPc30btrYEYkC+HeRL0kazC5vv2LHGje3L/UtktGKWEK3GqXg gXbD9W4uG/zxdYCAndSXGs62ntj3lbDjEunTx9u2vJO/n4DsQI/GeF+2Nv48S+PZGdaC gcNsYFY005SPR05EXetEpwAEIGTSC3woA24k9YpA6H267Wvn3WpQlggxz1NFTxiax0KI QMbLg4idZ679mmh8nooprBOxF1XMtagojvVi8RK8AILT1nPH/JS2nlWwqjgLWefMbtlR uH+QHQer8HwvHcvTYZXWfINLV9kGHI5h1OB+Wnrd25P5W0MGM90FDJl2gP0Ftpb94pJL XCJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1715615983; x=1716220783; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=vmzpZMXRQ1wNyRuj1P7z4ooSWBsAJZ0JhU9+Vv186kg=; b=wmZoO0psD67Y9EANp/fMSYyGOZd1LFEEx+D3KUzXe1/2PeR+2PW+AuYT3XGkGXJiUn 3CWly5q2tHezPvrNaLQwmCPkqchDdbbw33/eD/ZvkxJhlV/8LGBxZOvVT4ihFFJwIi53 J/UWCojyxJu79+Kb6TaGbCcVxXyZSOjQKwe1eUQuHcDJooF0LK4hqUjMjJ6oVgfpD55a MEL/McsyVCIAjsj8UDeqIZX5TFXvVh20Ce9/I8WYewKPgpmYMG0nfX3nGmYo6xRJlozF 3sPAem+BGtT8ZJzGmxGirHqlow2N+N4huRvR4GDohovbWok7hPm6aPaQSblzrAyHOoJ1 Vm8A== X-Gm-Message-State: AOJu0YwtUR4d6Ty5L/8xx/94/BYRJ5pLn2HKwhufQvK3YI7GfJJB1z1P E76SBKUhOD5My7E37qHg1WpZ5syJV2kJ8np5aHDJ42BRbHTwZUBm+izEmw== X-Google-Smtp-Source: AGHT+IEMf6+ntsa9OURyzlZ1o+ot0Q0cKIUA4L1BH5/TEHoMeQEgl5hBa9JmcpL1CHfxoXLTElBpGw== X-Received: by 2002:a05:6a00:3a0f:b0:6ea:914e:a108 with SMTP id d2e1a72fcca58-6f4e02af1f2mr9631798b3a.12.1715615982842; Mon, 13 May 2024 08:59:42 -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.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 May 2024 08:59:42 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Cc: Jerin Jacob , Sunil Kumar Kori Subject: [PATCH 6/9] doc: reword log library section in prog guide Date: Mon, 13 May 2024 08:59:08 -0700 Message-Id: <20240513155911.31872-7-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 changes made for syntax in the log library section and 7.1 section of the programmer's guide. A couple sentences at the end of the trace library section were also edited. Signed-off-by: Nandini Persad --- doc/guides/prog_guide/cmdline.rst | 24 +++++++++++----------- doc/guides/prog_guide/log_lib.rst | 32 ++++++++++++++--------------- doc/guides/prog_guide/trace_lib.rst | 22 ++++++++++---------- 3 files changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/guides/prog_guide/cmdline.rst b/doc/guides/prog_guide/cmdline.rst index e20281ceb5..6b10ab6c99 100644 --- a/doc/guides/prog_guide/cmdline.rst +++ b/doc/guides/prog_guide/cmdline.rst @@ -5,8 +5,8 @@ Command-line Library ==================== Since its earliest versions, DPDK has included a command-line library - -primarily for internal use by, for example, ``dpdk-testpmd`` and the ``dpdk-test`` binaries, -but the library is also exported on install and can be used by any end application. +primarily for internal use by, for example, ``dpdk-testpmd`` and the ``dpdk-test`` binaries. +However, the library is also exported on install and can be used by any end application. This chapter covers the basics of the command-line library and how to use it in an application. Library Features @@ -18,7 +18,7 @@ The DPDK command-line library supports the following features: * Ability to read and process commands taken from an input file, e.g. startup script -* Parameterized commands able to take multiple parameters with different datatypes: +* Parameterized commands that can take multiple parameters with different datatypes: * Strings * Signed/unsigned 16/32/64-bit integers @@ -56,7 +56,7 @@ Creating a Command List File The ``dpdk-cmdline-gen.py`` script takes as input a list of commands to be used by the application. While these can be piped to it via standard input, using a list file is probably best. -The format of the list file must be: +The format of the list file must follow these requirements: * Comment lines start with '#' as first non-whitespace character @@ -75,7 +75,7 @@ The format of the list file must be: * ``dst_ip6`` * Variable fields, which take their values from a list of options, - have the comma-separated option list placed in braces, rather than a the type name. + have the comma-separated option list placed in braces, rather than by the type name. For example, * ``<(rx,tx,rxtx)>mode`` @@ -127,13 +127,13 @@ and the callback stubs will be written to an equivalent ".c" file. Providing the Function Callbacks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As discussed above, the script output is a header file, containing structure definitions, -but the callback functions themselves obviously have to be provided by the user. -These callback functions must be provided as non-static functions in a C file, +As discussed above, the script output is a header file containing structure definitions, +but the callback functions must be provided by the user. +These callback functions must be provided as non-static functions in a C file and named ``cmd__parsed``. The function prototypes can be seen in the generated output header. -The "cmdname" part of the function name is built up by combining the non-variable initial tokens in the command. +The "cmdname" part of the function name is built by combining the non-variable initial tokens in the command. So, given the commands in our worked example below: ``quit`` and ``show port stats ``, the callback functions would be: @@ -151,11 +151,11 @@ the callback functions would be: ... } -These functions must be provided by the developer, but, as stated above, +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. -To get at the results structure for each command above, +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. @@ -179,7 +179,7 @@ To integrate the script output with the application, we must ``#include`` the generated header into our applications 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). +``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. diff --git a/doc/guides/prog_guide/log_lib.rst b/doc/guides/prog_guide/log_lib.rst index ff9d1b54a2..05f032dfad 100644 --- a/doc/guides/prog_guide/log_lib.rst +++ b/doc/guides/prog_guide/log_lib.rst @@ -5,7 +5,7 @@ Log Library =========== The DPDK Log library provides the logging functionality for other DPDK libraries and drivers. -By default, in a Linux application, logs are sent to syslog and also to the console. +By default, in a Linux application, logs are sent to syslog and the console. On FreeBSD and Windows applications, logs are sent only to the console. However, the log function can be overridden by the user to use a different logging mechanism. @@ -26,14 +26,14 @@ These levels, specified in ``rte_log.h`` are (from most to least important): At runtime, only messages of a configured level or above (i.e. of higher importance) will be emitted by the application to the log output. -That level can be configured either by the application calling the relevant APIs from the logging library, +That level can be configured either by the application calling relevant APIs from the logging library, or by the user passing the ``--log-level`` parameter to the EAL via the application. Setting Global Log Level ~~~~~~~~~~~~~~~~~~~~~~~~ To adjust the global log level for an application, -just pass a numeric level or a level name to the ``--log-level`` EAL parameter. +pass a numeric level or a level name to the ``--log-level`` EAL parameter. For example:: /path/to/app --log-level=error @@ -47,9 +47,9 @@ Within an application, the log level can be similarly set using the ``rte_log_se Setting Log Level for a Component ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In some cases, for example, for debugging purposes, -it may be desirable to increase or decrease the log level for only a specific component, or set of components. -To facilitate this, the ``--log-level`` argument also accepts an, optionally wildcarded, component name, +In some cases (such as debugging purposes), +you may want to increase or decrease the log level for only a specific component or set of components. +To facilitate this, the ``--log-level`` argument also accepts an optionally wildcarded component name, along with the desired level for that component. For example:: @@ -57,13 +57,13 @@ For example:: /path/to/app --log-level=lib.*:warning -Within an application, the same result can be got using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. +Within an application, you can achieve the same result using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. Using Logging APIs to Generate Log Messages ------------------------------------------- -To output log messages, ``rte_log()`` API function should be used. -As well as the log message, ``rte_log()`` takes two additional parameters: +To output log messages, the ``rte_log()`` API function should be used, +as well as the log message, ``rte_log()`` which takes two additional parameters: * The log level * The log component type @@ -73,16 +73,16 @@ The component type is a unique id that identifies the particular DPDK component To get this id, each component needs to register itself at startup, using the macro ``RTE_LOG_REGISTER_DEFAULT``. This macro takes two parameters, with the second being the default log level for the component. -The first parameter, called "type", the name of the "logtype", or "component type" variable used in the component. -This variable will be defined by the macro, and should be passed as the second parameter in calls to ``rte_log()``. +The first parameter, called "type", is the name of the "logtype", or "component type" variable used in the component. +This variable will be defined by the macro and should be passed as the second parameter in calls to ``rte_log()``. In general, most DPDK components define their own logging macros to simplify the calls to the log APIs. They do this by: * Hiding the component type parameter inside the macro so it never needs to be passed explicitly. * Using the log-level definitions given in ``rte_log.h`` to allow short textual names to be used in - place of the numeric log levels. + place of numeric log levels. -The following code is taken from ``rte_cfgfile.c`` and shows the log registration, +The following code is taken from ``rte_cfgfile.c`` and shows the log registration and subsequent definition of a shortcut logging macro. It can be used as a template for any new components using DPDK logging. @@ -97,10 +97,10 @@ It can be used as a template for any new components using DPDK logging. it should be placed near the top of the C file using it. If not, the logtype variable should be defined as an "extern int" near the top of the file. - Similarly, if logging is to be done by multiple files in a component, - only one file should register the logtype via the macro, + Similarly, if logging will be done by multiple files in a component, + only one file should register the logtype via the macro and the logtype should be defined as an "extern int" in a common header file. - Any component-specific logging macro should similarly be defined in that header. + Any component-specific logging macro should be similarly defined in that header. Throughout the cfgfile library, all logging calls are therefore of the form: diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst index e2983017d8..4177f8ba15 100644 --- a/doc/guides/prog_guide/trace_lib.rst +++ b/doc/guides/prog_guide/trace_lib.rst @@ -195,12 +195,12 @@ to babeltrace with no options:: all their events, merging them in chronological order. You can pipe the output of the babeltrace into a tool like grep(1) for further -filtering. Below example grep the events for ``ethdev`` only:: +filtering. Here's an example of how you grep the events for ``ethdev`` only:: babeltrace /tmp/my-dpdk-trace | grep ethdev You can pipe the output of babeltrace into a tool like wc(1) to count the -recorded events. Below example count the number of ``ethdev`` events:: +recorded events. Below is an example of counting the number of ``ethdev`` events:: babeltrace /tmp/my-dpdk-trace | grep ethdev | wc --lines @@ -210,14 +210,14 @@ Use the tracecompass GUI tool ``Tracecompass`` is another tool to view/analyze the DPDK traces which gives a graphical view of events. Like ``babeltrace``, tracecompass also provides an interface to search for a particular event. -To use ``tracecompass``, following are the minimum required steps: +To use ``tracecompass``, the following are the minimum required steps: - Install ``tracecompass`` to the localhost. Variants are available for Linux, Windows, and OS-X. - Launch ``tracecompass`` which will open a graphical window with trace management interfaces. -- Open a trace using ``File->Open Trace`` option and select metadata file which - is to be viewed/analyzed. +- Open a trace using the ``File->Open Trace`` option and select the metadata file which + will be viewed/analyzed. For more details, refer `Trace Compass `_. @@ -225,7 +225,7 @@ For more details, refer Quick start ----------- -This section steps you through the details of generating trace and viewing it. +This section steps you through the details of generating the trace and viewing it. - Start the dpdk-test:: @@ -238,8 +238,8 @@ This section steps you through the details of generating trace and viewing it. Implementation details ---------------------- -As DPDK trace library is designed to generate traces that uses ``Common Trace -Format (CTF)``. ``CTF`` specification consists of the following units to create +As the DPDK trace library is designed to generate traces that use the ``Common Trace +Format (CTF)``. ``CTF`` specification and consists of the following units to create a trace. - ``Stream`` Sequence of packets. @@ -249,7 +249,7 @@ a trace. For detailed information, refer to `Common Trace Format `_. -The implementation details broadly divided into the following areas: +Implementation details are broadly divided into the following areas: Trace metadata creation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -277,7 +277,7 @@ per thread to enable lock less trace-emit function. For non lcore threads, the trace memory is allocated on the first trace emission. -For lcore threads, if trace points are enabled through a EAL option, the trace +For lcore threads, if trace points are enabled through an EAL option, the trace memory is allocated when the threads are known of DPDK (``rte_eal_init`` for EAL lcores, ``rte_thread_register`` for non-EAL lcores). Otherwise, when trace points are enabled later in the life of the application, @@ -348,7 +348,7 @@ trace.header | timestamp [47:0] | +----------------------+ -The trace header is 64 bits, it consists of 48 bits of timestamp and 16 bits +The trace header is 64 bits. It consists of 48 bits of timestamp and 16 bits event ID. The ``packet.header`` and ``packet.context`` will be written in the slow path -- 2.34.1