doc/guides/contributing/design.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2018 The DPDK contributors
   3
   4 Design
   5 ======
   6
   7 Environment or Architecture-specific Sources
   8 --------------------------------------------
   9
  10 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.
  11 As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
  12
  13 By convention, a file is common if it is not located in a directory indicating that it is specific.
  14 For instance, a file located in a subdir of "x86_64" directory is specific to this architecture.
  15 A 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
  22 When 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
  39 Per Architecture Sources
  40 ~~~~~~~~~~~~~~~~~~~~~~~~
  41
  42 The 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
  47 Per Execution Environment Sources
  48 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  49
  50 The 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
  55 Mbuf features
  56 -------------
  57
  58 The ``rte_mbuf`` structure must be kept small (128 bytes).
  59
  60 In order to add new features without wasting buffer space for unused features,
  61 some fields and flags can be registered dynamically in a shared area.
  62 The "dynamic" mbuf area is the default choice for the new features.
  63
  64 The "dynamic" area is eating the remaining space in mbuf,
  65 and some existing "static" fields may need to become "dynamic".
  66
  67 Adding a new static field or flag must be an exception matching many criteria
  68 like (non exhaustive): wide usage, performance, size.
  69
  70
  71 Library Statistics
  72 ------------------
  73
  74 Description
  75 ~~~~~~~~~~~
  76
  77 This document describes the guidelines for DPDK library-level statistics counter
  78 support. This includes guidelines for turning library statistics on and off and
  79 requirements for preventing ABI changes when implementing statistics.
  80
  81
  82 Mechanism to allow the application to turn library statistics on and off
  83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  84
  85 Having runtime support for enabling/disabling library statistics is recommended,
  86 as build-time options should be avoided. However, if build-time options are used,
  87 for example as in the table library, the options can be set using c_args.
  88 When this flag is set, all the counters supported by current library are
  89 collected for all the instances of every object type provided by the library.
  90 When this flag is cleared, none of the counters supported by the current library
  91 are collected for any instance of any object type provided by the library:
  92
  93
  94 Prevention of ABI changes due to library statistics support
  95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96
  97 The layout of data structures and prototype of functions that are part of the
  98 library API should not be affected by whether the collection of statistics
  99 counters is turned on or off for the current library. In practical terms, this
 100 means that space should always be allocated in the API data structures for
 101 statistics counters and the statistics related API functions are always built
 102 into the code, regardless of whether the statistics counter collection is turned
 103 on or off for the current library.
 104
 105 When the collection of statistics counters for the current library is turned
 106 off, the counters retrieved through the statistics related API functions should
 107 have a default value of zero.
 108
 109
 110 Motivation to allow the application to turn library statistics on and off
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 It is highly recommended that each library provides statistics counters to allow
 114 an application to monitor the library-level run-time events. Typical counters
 115 are: number of packets received/dropped/transmitted, number of buffers
 116 allocated/freed, number of occurrences for specific events, etc.
 117
 118 However, the resources consumed for library-level statistics counter collection
 119 have to be spent out of the application budget and the counters collected by
 120 some libraries might not be relevant to the current application. In order to
 121 avoid any unwanted waste of resources and/or performance impacts, the
 122 application should decide at build time whether the collection of library-level
 123 statistics counters should be turned on or off for each library individually.
 124
 125 Library-level statistics counters can be relevant or not for specific
 126 applications:
 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
 148 The statistics collection consumes a certain amount of CPU resources (cycles,
 149 cache 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
 168 PF and VF Considerations
 169 ------------------------
 170
 171 The primary goal of DPDK is to provide a userspace dataplane. Managing VFs from
 172 a PF driver is a control plane feature and developers should generally rely on
 173 the Linux Kernel for that.
 174
 175 Developers should work with the Linux Kernel community to get the required
 176 functionality upstream. PF functionality should only be added to DPDK for
 177 testing and prototyping purposes while the kernel work is ongoing. It should
 178 also be marked with an "EXPERIMENTAL" tag. If the functionality isn't
 179 upstreamable then a case can be made to maintain the PF functionality in DPDK
 180 without the EXPERIMENTAL tag.