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