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 7119A4401C; Mon, 13 May 2024 18:01:41 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 100904069F; Mon, 13 May 2024 18:01:37 +0200 (CEST) Received: from mail-pg1-f179.google.com (mail-pg1-f179.google.com [209.85.215.179]) by mails.dpdk.org (Postfix) with ESMTP id 2D47E402CD for ; Mon, 13 May 2024 17:59:28 +0200 (CEST) Received: by mail-pg1-f179.google.com with SMTP id 41be03b00d2f7-517ab9a4a13so3440129a12.1 for ; Mon, 13 May 2024 08:59:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1715615967; x=1716220767; 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=6k8ONKkW6oF7FbtnY/jrFIKHNtYMoassSMYzYaEA37E=; b=lFc5MxcD6fwFjWV1yOp8YXGLfsCq2JKczLNLckNzfqIZQ8zNV1qoc335HaQE/Iz0gY cnwy6i8NfgVRI3PkUQyvOcs7Lf5XrjQyro1a0zxyQ2TbfNjnSLjmgSNXwH6v/B7e71vz 2RmGbVD7jqGpC6kZLEtwuWhkmsMGvo8Tdb8flBICbBe8jDo5w4DXk4zSCYIPwVfifPQq 61LdIqVNGj4HzyY+QZTdhuU3h3yFckdmBYVzVWUA80P0PwNOvLRBRO0fiUX04m8QIf3S J0Cpsrqx4D3EaM+fEUNpJQy9ZycB46sNumvY3Q6ygu0CCDbjIHG5ZOu2A4F1NI4z7ZBi A61Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1715615967; x=1716220767; 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=6k8ONKkW6oF7FbtnY/jrFIKHNtYMoassSMYzYaEA37E=; b=BjS6A/G6LMGQEIg+3vE30dKDkkZh0w5wgNaUlE9QK20KP7HeSBKu7noqQPMnsKUwhO yzUF8kaEmUKKyf5M9DNGIp/OIq3v7An1vzLCYXMkaCtbxLu0fsyYMa09qg04y9/F1nlQ 7pnELJrTUeMiDsBHljl9QU5pNbpFrO551RVS9+hEQezh9B2f4lNllrxctbdowCs3Ipv7 ZzSi1beZAzUf9Fi+/8rlZwoWinZpQI/CzDiNYujJQg8HuVOMTwu6d7LEfaEGMkFw2kZT uZVdSw49lYcLNX+7QL2SX0Gu2r57XgsrRlSrOTSgMnRao0AZJ4Q7Z8FX9QDGyAaDDuqg 6QVA== X-Gm-Message-State: AOJu0Yy//MAYI4V7DZUXQkzGKDN8MBkdUNErLP4IW+SFNf6MsSDSG+mY ObjQil5pLCW6i5uDuyMkMZju3tkiKY2LJgyXTFcApTy36XaJ7yd2eAYk8w== X-Google-Smtp-Source: AGHT+IE65NHYVNPVxg9BEq139QXNBoDzrWJYwdkWnCIDYKBRDb9NCiQA+beAr48kScall4ngP+Sm6A== X-Received: by 2002:a05:6a20:565b:b0:1af:d44c:cfc3 with SMTP id adf61e73a8af0-1afde104374mr10370927637.32.1715615966798; Mon, 13 May 2024 08:59:26 -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.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 May 2024 08:59:26 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Cc: Thomas Monjalon Subject: [PATCH 1/9] doc: reword design section in contributors guidelines Date: Mon, 13 May 2024 08:59:03 -0700 Message-Id: <20240513155911.31872-2-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 editing for grammar and syntax of design section Signed-off-by: Nandini Persad --- .mailmap | 1 + doc/guides/contributing/design.rst | 79 ++++++++++++++---------------- doc/guides/linux_gsg/sys_reqs.rst | 2 +- 3 files changed, 38 insertions(+), 44 deletions(-) diff --git a/.mailmap b/.mailmap index 66ebc20666..7d4929c5d1 100644 --- a/.mailmap +++ b/.mailmap @@ -1002,6 +1002,7 @@ Naga Suresh Somarowthu Nalla Pradeep Na Na Nan Chen +Nandini Persad Nannan Lu Nan Zhou Narcisa Vasile diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst index b724177ba1..921578aec5 100644 --- a/doc/guides/contributing/design.rst +++ b/doc/guides/contributing/design.rst @@ -8,22 +8,26 @@ Design Environment or Architecture-specific Sources -------------------------------------------- -In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (freebsd or linux) and so on. -As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL. +In DPDK and DPDK applications, some code is architecture-specific (i686, x86_64) or environment-specific (FreeBsd or Linux, etc.). +When feasible, such instances of architecture or env-specific code should be provided via standard APIs in the EAL. -By convention, a file is common if it is not located in a directory indicating that it is specific. -For instance, a file located in a subdir of "x86_64" directory is specific to this architecture. +By convention, a file is specific if the directory is indicated. Otherwise, it is common. + +For example: + +A file located in a subdir of "x86_64" directory is specific to this architecture. A file located in a subdir of "linux" is specific to this execution environment. .. note:: Code in DPDK libraries and applications should be generic. - The correct location for architecture or executive environment specific code is in the EAL. + The correct location for architecture or executive environment-specific code is in the EAL. + +When necessary, there are several ways to handle specific code: -When absolutely necessary, there are several ways to handle specific code: -* Use a ``#ifdef`` with a build definition macro in the C code. - This can be done when the differences are small and they can be embedded in the same C file: +* When the differences are small and they can be embedded in the same C file, use a ``#ifdef`` with a build definition macro in the C code. + .. code-block:: c @@ -33,9 +37,9 @@ When absolutely necessary, there are several ways to handle specific code: titi(); #endif -* Use build definition macros and conditions in the Meson build file. This is done when the differences are more significant. - In this case, the code is split into two separate files that are architecture or environment specific. - This should only apply inside the EAL library. +* When the differences are more significant, use build definition macros and conditions in the Meson build file. +In this case, the code is split into two separate files that are architecture or environment specific. +This should only apply inside the EAL library. Per Architecture Sources ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -43,7 +47,7 @@ Per Architecture Sources The following macro options can be used: * ``RTE_ARCH`` is a string that contains the name of the architecture. -* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined only if we are building for those architectures. +* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined when building for these architectures. Per Execution Environment Sources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -51,30 +55,21 @@ Per Execution Environment Sources The following macro options can be used: * ``RTE_EXEC_ENV`` is a string that contains the name of the executive environment. -* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for this execution environment. +* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only when building for this execution environment. Mbuf features ------------- -The ``rte_mbuf`` structure must be kept small (128 bytes). - -In order to add new features without wasting buffer space for unused features, -some fields and flags can be registered dynamically in a shared area. -The "dynamic" mbuf area is the default choice for the new features. - -The "dynamic" area is eating the remaining space in mbuf, -and some existing "static" fields may need to become "dynamic". +A designated area in mbuf stores "dynamically" registered fields and flags. It is the default choice for accomodating new features. The "dynamic" area consumes the remaining space in the mbuf, indicating that it's being efficiently utilized. However, the ``rte_mbuf`` structure must be kept small (128 bytes). -Adding a new static field or flag must be an exception matching many criteria -like (non exhaustive): wide usage, performance, size. +As more features are added, the space for existinG=g "static" fields (fields that are allocated statically) may need to be reconsidered and possibly converted to "dynamic" allocation. Adding a new static field or flag should be an exception. It must meet specific criteria including widespread usage, performance impact, and size considerations. Before adding a new static feature, it must be justified by its necessity and its impact on the system's efficiency. Runtime Information - Logging, Tracing and Telemetry ---------------------------------------------------- -It is often desirable to provide information to the end-user -as to what is happening to the application at runtime. -DPDK provides a number of built-in mechanisms to provide this introspection: +The end user may inquire as to what is happening to the application at runtime. +DPDK provides several built-in mechanisms to provide these insights: * :ref:`Logging ` * :doc:`Tracing <../prog_guide/trace_lib>` @@ -82,11 +77,11 @@ DPDK provides a number of built-in mechanisms to provide this introspection: Each of these has its own strengths and suitabilities for use within DPDK components. -Below are some guidelines for when each should be used: +Here are guidelines for when each mechanism should be used: * For reporting error conditions, or other abnormal runtime issues, *logging* should be used. - Depending on the severity of the issue, the appropriate log level, for example, - ``ERROR``, ``WARNING`` or ``NOTICE``, should be used. + For example, depending on the severity of the issue, the appropriate log level, + ``ERROR``, ``WARNING`` or ``NOTICE`` should be used. .. note:: @@ -96,22 +91,21 @@ Below are some guidelines for when each should be used: * For component initialization, or other cases where a path through the code is only likely to be taken once, - either *logging* at ``DEBUG`` level or *tracing* may be used, or potentially both. + either *logging* at ``DEBUG`` level or *tracing* may be used, or both. In the latter case, tracing can provide basic information as to the code path taken, with debug-level logging providing additional details on internal state, - not possible to emit via tracing. + which is not possible to emit via tracing. * For a component's data-path, where a path is to be taken multiple times within a short timeframe, *tracing* should be used. Since DPDK tracing uses `Common Trace Format `_ for its tracing logs, post-analysis can be done using a range of external tools. -* For numerical or statistical data generated by a component, for example, per-packet statistics, +* For numerical or statistical data generated by a component, such as per-packet statistics, *telemetry* should be used. -* For any data where the data may need to be gathered at any point in the execution - to help assess the state of the application component, - for example, core configuration, device information, *telemetry* should be used. +* For any data that may need to be gathered at any point during the execution + to help assess the state of the application component (for example, core configuration, device information) *telemetry* should be used. Telemetry callbacks should not modify any program state, but be "read-only". Many libraries also include a ``rte__dump()`` function as part of their API, @@ -135,13 +129,12 @@ requirements for preventing ABI changes when implementing statistics. Mechanism to allow the application to turn library statistics on and off ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Having runtime support for enabling/disabling library statistics is recommended, -as build-time options should be avoided. However, if build-time options are used, -for example as in the table library, the options can be set using c_args. -When this flag is set, all the counters supported by current library are +Having runtime support for enabling/disabling library statistics is recommended +as build-time options should be avoided. However, if build-time options are used, as in the table library, the options can be set using c_args. +When this flag is set, all the counters supported by the current library are collected for all the instances of every object type provided by the library. When this flag is cleared, none of the counters supported by the current library -are collected for any instance of any object type provided by the library: +are collected for any instance of any object type provided by the library. Prevention of ABI changes due to library statistics support @@ -165,8 +158,8 @@ Motivation to allow the application to turn library statistics on and off It is highly recommended that each library provides statistics counters to allow an application to monitor the library-level run-time events. Typical counters -are: number of packets received/dropped/transmitted, number of buffers -allocated/freed, number of occurrences for specific events, etc. +are: the number of packets received/dropped/transmitted, the number of buffers +allocated/freed, the number of occurrences for specific events, etc. However, the resources consumed for library-level statistics counter collection have to be spent out of the application budget and the counters collected by @@ -229,5 +222,5 @@ Developers should work with the Linux Kernel community to get the required functionality upstream. PF functionality should only be added to DPDK for testing and prototyping purposes while the kernel work is ongoing. It should also be marked with an "EXPERIMENTAL" tag. If the functionality isn't -upstreamable then a case can be made to maintain the PF functionality in DPDK +upstreamable, then a case can be made to maintain the PF functionality in DPDK without the EXPERIMENTAL tag. diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst index 13be715933..0569c5cae6 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -99,7 +99,7 @@ e.g. :doc:`../nics/index` Running DPDK Applications ------------------------- -To run a DPDK application, some customization may be required on the target machine. +To run a DPDK application, customization may be required on the target machine. System Software ~~~~~~~~~~~~~~~ -- 2.34.1