doc/guides/contributing/design.rst

   1 Design
   2 ======
   3
   4 Environment or Architecture-specific Sources
   5 --------------------------------------------
   6
   7 In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (bsdapp or linuxapp) and so on.
   8 As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
   9
  10 By convention, a file is common if it is not located in a directory indicating that it is specific.
  11 For instance, a file located in a subdir of "x86_64" directory is specific to this architecture.
  12 A file located in a subdir of "linuxapp" is specific to this execution environment.
  13
  14 .. note::
  15
  16         Code in DPDK libraries and applications should be generic.
  17         The correct location for architecture or executive environment specific code is in the EAL.
  18
  19 When absolutely necessary, there are several ways to handle specific code:
  20
  21 * Use a ``#ifdef`` with the CONFIG option in the C code.
  22   This can be done when the differences are small and they can be embedded in the same C file:
  23
  24 .. code-block: console
  25
  26    #ifdef RTE_ARCH_I686
  27    toto();
  28    #else
  29    titi();
  30    #endif
  31
  32 * Use the CONFIG option in the Makefile. This is done when the differences are more significant.
  33   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.
  34
  35 .. note:
  36
  37         As in the linux kernel, the "CONFIG_" prefix is not used in C code.
  38         This is only needed in Makefiles or shell scripts.
  39
  40 Per Architecture Sources
  41 ~~~~~~~~~~~~~~~~~~~~~~~~
  42
  43 The following config options can be used:
  44
  45 * CONFIG_RTE_ARCH is a string that contains the name of the architecture.
  46 * CONFIG_RTE_ARCH_I686, CONFIG_RTE_ARCH_X86_64, CONFIG_RTE_ARCH_X86_64_32 or CONFIG_RTE_ARCH_PPC_64 are defined only if we are building for those architectures.
  47
  48 Per Execution Environment Sources
  49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  50
  51 The following config options can be used:
  52
  53 * CONFIG_RTE_EXEC_ENV is a string that contains the name of the executive environment.
  54 * CONFIG_RTE_EXEC_ENV_BSDAPP or CONFIG_RTE_EXEC_ENV_LINUXAPP are defined only if we are building for this execution environment.
  55
  56 Library Statistics
  57 ------------------
  58
  59 Description
  60 ~~~~~~~~~~~
  61
  62 This document describes the guidelines for DPDK library-level statistics counter
  63 support. This includes guidelines for turning library statistics on and off and
  64 requirements for preventing ABI changes when implementing statistics.
  65
  66
  67 Mechanism to allow the application to turn library statistics on and off
  68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69
  70 Each library that maintains statistics counters should provide a single build
  71 time flag that decides whether the statistics counter collection is enabled or
  72 not. This flag should be exposed as a variable within the DPDK configuration
  73 file. When this flag is set, all the counters supported by current library are
  74 collected for all the instances of every object type provided by the library.
  75 When this flag is cleared, none of the counters supported by the current library
  76 are collected for any instance of any object type provided by the library:
  77
  78 .. code-block:: console
  79
  80         # DPDK file config/common_linuxapp, config/common_bsdapp, etc.
  81         CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
  82
  83 The default value for this DPDK configuration file variable (either "yes" or
  84 "no") is decided by each library.
  85
  86
  87 Prevention of ABI changes due to library statistics support
  88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  89
  90 The layout of data structures and prototype of functions that are part of the
  91 library API should not be affected by whether the collection of statistics
  92 counters is turned on or off for the current library. In practical terms, this
  93 means that space should always be allocated in the API data structures for
  94 statistics counters and the statistics related API functions are always built
  95 into the code, regardless of whether the statistics counter collection is turned
  96 on or off for the current library.
  97
  98 When the collection of statistics counters for the current library is turned
  99 off, the counters retrieved through the statistics related API functions should
 100 have a default value of zero.
 101
 102
 103 Motivation to allow the application to turn library statistics on and off
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106 It is highly recommended that each library provides statistics counters to allow
 107 an application to monitor the library-level run-time events. Typical counters
 108 are: number of packets received/dropped/transmitted, number of buffers
 109 allocated/freed, number of occurrences for specific events, etc.
 110
 111 However, the resources consumed for library-level statistics counter collection
 112 have to be spent out of the application budget and the counters collected by
 113 some libraries might not be relevant to the current application. In order to
 114 avoid any unwanted waste of resources and/or performance impacts, the
 115 application should decide at build time whether the collection of library-level
 116 statistics counters should be turned on or off for each library individually.
 117
 118 Library-level statistics counters can be relevant or not for specific
 119 applications:
 120
 121 * For Application A, counters maintained by Library X are always relevant and
 122   the application needs to use them to implement certain features, such as traffic
 123   accounting, logging, application-level statistics, etc. In this case,
 124   the application requires that collection of statistics counters for Library X is
 125   always turned on.
 126
 127 * For Application B, counters maintained by Library X are only useful during the
 128   application debug stage and are not relevant once debug phase is over. In this
 129   case, the application may decide to turn on the collection of Library X
 130   statistics counters during the debug phase and at a later stage turn them off.
 131
 132 * For Application C, counters maintained by Library X are not relevant at all.
 133   It might be that the application maintains its own set of statistics counters
 134   that monitor a different set of run-time events (e.g. number of connection
 135   requests, number of active users, etc). It might also be that the application
 136   uses multiple libraries (Library X, Library Y, etc) and it is interested in the
 137   statistics counters of Library Y, but not in those of Library X. In this case,
 138   the application may decide to turn the collection of statistics counters off for
 139   Library X and on for Library Y.
 140
 141 The statistics collection consumes a certain amount of CPU resources (cycles,
 142 cache bandwidth, memory bandwidth, etc) that depends on:
 143
 144 * Number of libraries used by the current application that have statistics
 145   counters collection turned on.
 146
 147 * Number of statistics counters maintained by each library per object type
 148   instance (e.g. per port, table, pipeline, thread, etc).
 149
 150 * Number of instances created for each object type supported by each library.
 151
 152 * Complexity of the statistics logic collection for each counter: when only
 153   some occurrences of a specific event are valid, additional logic is typically
 154   needed to decide whether the current occurrence of the event should be counted
 155   or not. For example, in the event of packet reception, when only TCP packets
 156   with destination port within a certain range should be recorded, conditional
 157   branches are usually required. When processing a burst of packets that have been
 158   validated for header integrity, counting the number of bits set in a bitmask
 159   might be needed.