1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2018 The DPDK contributors 3 4Design 5====== 6 7Environment or Architecture-specific Sources 8-------------------------------------------- 9 10In 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. 11As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL. 12 13By convention, a file is common if it is not located in a directory indicating that it is specific. 14For instance, a file located in a subdir of "x86_64" directory is specific to this architecture. 15A file located in a subdir of "linux" is specific to this execution environment. 16 17.. note:: 18 19 Code in DPDK libraries and applications should be generic. 20 The correct location for architecture or executive environment specific code is in the EAL. 21 22When absolutely necessary, there are several ways to handle specific code: 23 24* Use a ``#ifdef`` with a build definition macro in the C code. 25 This can be done when the differences are small and they can be embedded in the same C file: 26 27 .. code-block:: c 28 29 #ifdef RTE_ARCH_I686 30 toto(); 31 #else 32 titi(); 33 #endif 34 35* Use build definition macros and conditions in the Meson build file. This is done when the differences are more significant. 36 In this case, the code is split into two separate files that are architecture or environment specific. 37 This should only apply inside the EAL library. 38 39Per Architecture Sources 40~~~~~~~~~~~~~~~~~~~~~~~~ 41 42The following macro options can be used: 43 44* ``RTE_ARCH`` is a string that contains the name of the architecture. 45* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined only if we are building for those architectures. 46 47Per Execution Environment Sources 48~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 49 50The following macro options can be used: 51 52* ``RTE_EXEC_ENV`` is a string that contains the name of the executive environment. 53* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for this execution environment. 54 55Mbuf features 56------------- 57 58The ``rte_mbuf`` structure must be kept small (128 bytes). 59 60In order to add new features without wasting buffer space for unused features, 61some fields and flags can be registered dynamically in a shared area. 62The "dynamic" mbuf area is the default choice for the new features. 63 64The "dynamic" area is eating the remaining space in mbuf, 65and some existing "static" fields may need to become "dynamic". 66 67Adding a new static field or flag must be an exception matching many criteria 68like (non exhaustive): wide usage, performance, size. 69 70 71Library Statistics 72------------------ 73 74Description 75~~~~~~~~~~~ 76 77This document describes the guidelines for DPDK library-level statistics counter 78support. This includes guidelines for turning library statistics on and off and 79requirements for preventing ABI changes when implementing statistics. 80 81 82Mechanism to allow the application to turn library statistics on and off 83~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 84 85Having runtime support for enabling/disabling library statistics is recommended, 86as build-time options should be avoided. However, if build-time options are used, 87for example as in the table library, the options can be set using c_args. 88When this flag is set, all the counters supported by current library are 89collected for all the instances of every object type provided by the library. 90When this flag is cleared, none of the counters supported by the current library 91are collected for any instance of any object type provided by the library: 92 93 94Prevention of ABI changes due to library statistics support 95~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 96 97The layout of data structures and prototype of functions that are part of the 98library API should not be affected by whether the collection of statistics 99counters is turned on or off for the current library. In practical terms, this 100means that space should always be allocated in the API data structures for 101statistics counters and the statistics related API functions are always built 102into the code, regardless of whether the statistics counter collection is turned 103on or off for the current library. 104 105When the collection of statistics counters for the current library is turned 106off, the counters retrieved through the statistics related API functions should 107have a default value of zero. 108 109 110Motivation to allow the application to turn library statistics on and off 111~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 112 113It is highly recommended that each library provides statistics counters to allow 114an application to monitor the library-level run-time events. Typical counters 115are: number of packets received/dropped/transmitted, number of buffers 116allocated/freed, number of occurrences for specific events, etc. 117 118However, the resources consumed for library-level statistics counter collection 119have to be spent out of the application budget and the counters collected by 120some libraries might not be relevant to the current application. In order to 121avoid any unwanted waste of resources and/or performance impacts, the 122application should decide at build time whether the collection of library-level 123statistics counters should be turned on or off for each library individually. 124 125Library-level statistics counters can be relevant or not for specific 126applications: 127 128* For Application A, counters maintained by Library X are always relevant and 129 the application needs to use them to implement certain features, such as traffic 130 accounting, logging, application-level statistics, etc. In this case, 131 the application requires that collection of statistics counters for Library X is 132 always turned on. 133 134* For Application B, counters maintained by Library X are only useful during the 135 application debug stage and are not relevant once debug phase is over. In this 136 case, the application may decide to turn on the collection of Library X 137 statistics counters during the debug phase and at a later stage turn them off. 138 139* For Application C, counters maintained by Library X are not relevant at all. 140 It might be that the application maintains its own set of statistics counters 141 that monitor a different set of run-time events (e.g. number of connection 142 requests, number of active users, etc). It might also be that the application 143 uses multiple libraries (Library X, Library Y, etc) and it is interested in the 144 statistics counters of Library Y, but not in those of Library X. In this case, 145 the application may decide to turn the collection of statistics counters off for 146 Library X and on for Library Y. 147 148The statistics collection consumes a certain amount of CPU resources (cycles, 149cache bandwidth, memory bandwidth, etc) that depends on: 150 151* Number of libraries used by the current application that have statistics 152 counters collection turned on. 153 154* Number of statistics counters maintained by each library per object type 155 instance (e.g. per port, table, pipeline, thread, etc). 156 157* Number of instances created for each object type supported by each library. 158 159* Complexity of the statistics logic collection for each counter: when only 160 some occurrences of a specific event are valid, additional logic is typically 161 needed to decide whether the current occurrence of the event should be counted 162 or not. For example, in the event of packet reception, when only TCP packets 163 with destination port within a certain range should be recorded, conditional 164 branches are usually required. When processing a burst of packets that have been 165 validated for header integrity, counting the number of bits set in a bitmask 166 might be needed. 167 168PF and VF Considerations 169------------------------ 170 171The primary goal of DPDK is to provide a userspace dataplane. Managing VFs from 172a PF driver is a control plane feature and developers should generally rely on 173the Linux Kernel for that. 174 175Developers should work with the Linux Kernel community to get the required 176functionality upstream. PF functionality should only be added to DPDK for 177testing and prototyping purposes while the kernel work is ongoing. It should 178also be marked with an "EXPERIMENTAL" tag. If the functionality isn't 179upstreamable then a case can be made to maintain the PF functionality in DPDK 180without the EXPERIMENTAL tag. 181