]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright 2018 The DPDK contributors | |
3 | ||
7c673cae FG |
4 | Design |
5 | ====== | |
6 | ||
7 | Environment or Architecture-specific Sources | |
8 | -------------------------------------------- | |
9 | ||
9f95a23c | 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. |
7c673cae FG |
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. | |
9f95a23c | 15 | A file located in a subdir of "linux" is specific to this execution environment. |
7c673cae FG |
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 the CONFIG option 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 the CONFIG option in the Makefile. 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 | .. note:: | |
40 | ||
41 | As in the linux kernel, the ``CONFIG_`` prefix is not used in C code. | |
42 | This is only needed in Makefiles or shell scripts. | |
43 | ||
44 | Per Architecture Sources | |
45 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
46 | ||
47 | The following config options can be used: | |
48 | ||
49 | * ``CONFIG_RTE_ARCH`` is a string that contains the name of the architecture. | |
50 | * ``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. | |
51 | ||
52 | Per Execution Environment Sources | |
53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
54 | ||
55 | The following config options can be used: | |
56 | ||
57 | * ``CONFIG_RTE_EXEC_ENV`` is a string that contains the name of the executive environment. | |
9f95a23c | 58 | * ``CONFIG_RTE_EXEC_ENV_FREEBSD`` or ``CONFIG_RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment. |
7c673cae FG |
59 | |
60 | Library Statistics | |
61 | ------------------ | |
62 | ||
63 | Description | |
64 | ~~~~~~~~~~~ | |
65 | ||
66 | This document describes the guidelines for DPDK library-level statistics counter | |
67 | support. This includes guidelines for turning library statistics on and off and | |
68 | requirements for preventing ABI changes when implementing statistics. | |
69 | ||
70 | ||
71 | Mechanism to allow the application to turn library statistics on and off | |
72 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
73 | ||
74 | Each library that maintains statistics counters should provide a single build | |
75 | time flag that decides whether the statistics counter collection is enabled or | |
76 | not. This flag should be exposed as a variable within the DPDK configuration | |
77 | file. When this flag is set, all the counters supported by current library are | |
78 | collected for all the instances of every object type provided by the library. | |
79 | When this flag is cleared, none of the counters supported by the current library | |
80 | are collected for any instance of any object type provided by the library: | |
81 | ||
82 | .. code-block:: console | |
83 | ||
9f95a23c | 84 | # DPDK file config/common_linux, config/common_freebsd, etc. |
7c673cae FG |
85 | CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n |
86 | ||
87 | The default value for this DPDK configuration file variable (either "yes" or | |
88 | "no") is decided by each library. | |
89 | ||
90 | ||
91 | Prevention of ABI changes due to library statistics support | |
92 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
93 | ||
94 | The layout of data structures and prototype of functions that are part of the | |
95 | library API should not be affected by whether the collection of statistics | |
96 | counters is turned on or off for the current library. In practical terms, this | |
97 | means that space should always be allocated in the API data structures for | |
98 | statistics counters and the statistics related API functions are always built | |
99 | into the code, regardless of whether the statistics counter collection is turned | |
100 | on or off for the current library. | |
101 | ||
102 | When the collection of statistics counters for the current library is turned | |
103 | off, the counters retrieved through the statistics related API functions should | |
104 | have a default value of zero. | |
105 | ||
106 | ||
107 | Motivation to allow the application to turn library statistics on and off | |
108 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
109 | ||
110 | It is highly recommended that each library provides statistics counters to allow | |
111 | an application to monitor the library-level run-time events. Typical counters | |
112 | are: number of packets received/dropped/transmitted, number of buffers | |
113 | allocated/freed, number of occurrences for specific events, etc. | |
114 | ||
115 | However, the resources consumed for library-level statistics counter collection | |
116 | have to be spent out of the application budget and the counters collected by | |
117 | some libraries might not be relevant to the current application. In order to | |
118 | avoid any unwanted waste of resources and/or performance impacts, the | |
119 | application should decide at build time whether the collection of library-level | |
120 | statistics counters should be turned on or off for each library individually. | |
121 | ||
122 | Library-level statistics counters can be relevant or not for specific | |
123 | applications: | |
124 | ||
125 | * For Application A, counters maintained by Library X are always relevant and | |
126 | the application needs to use them to implement certain features, such as traffic | |
127 | accounting, logging, application-level statistics, etc. In this case, | |
128 | the application requires that collection of statistics counters for Library X is | |
129 | always turned on. | |
130 | ||
131 | * For Application B, counters maintained by Library X are only useful during the | |
132 | application debug stage and are not relevant once debug phase is over. In this | |
133 | case, the application may decide to turn on the collection of Library X | |
134 | statistics counters during the debug phase and at a later stage turn them off. | |
135 | ||
136 | * For Application C, counters maintained by Library X are not relevant at all. | |
137 | It might be that the application maintains its own set of statistics counters | |
138 | that monitor a different set of run-time events (e.g. number of connection | |
139 | requests, number of active users, etc). It might also be that the application | |
140 | uses multiple libraries (Library X, Library Y, etc) and it is interested in the | |
141 | statistics counters of Library Y, but not in those of Library X. In this case, | |
142 | the application may decide to turn the collection of statistics counters off for | |
143 | Library X and on for Library Y. | |
144 | ||
145 | The statistics collection consumes a certain amount of CPU resources (cycles, | |
146 | cache bandwidth, memory bandwidth, etc) that depends on: | |
147 | ||
148 | * Number of libraries used by the current application that have statistics | |
149 | counters collection turned on. | |
150 | ||
151 | * Number of statistics counters maintained by each library per object type | |
152 | instance (e.g. per port, table, pipeline, thread, etc). | |
153 | ||
154 | * Number of instances created for each object type supported by each library. | |
155 | ||
156 | * Complexity of the statistics logic collection for each counter: when only | |
157 | some occurrences of a specific event are valid, additional logic is typically | |
158 | needed to decide whether the current occurrence of the event should be counted | |
159 | or not. For example, in the event of packet reception, when only TCP packets | |
160 | with destination port within a certain range should be recorded, conditional | |
161 | branches are usually required. When processing a burst of packets that have been | |
162 | validated for header integrity, counting the number of bits set in a bitmask | |
163 | might be needed. | |
11fdf7f2 TL |
164 | |
165 | PF and VF Considerations | |
166 | ------------------------ | |
167 | ||
168 | The primary goal of DPDK is to provide a userspace dataplane. Managing VFs from | |
169 | a PF driver is a control plane feature and developers should generally rely on | |
170 | the Linux Kernel for that. | |
171 | ||
172 | Developers should work with the Linux Kernel community to get the required | |
173 | functionality upstream. PF functionality should only be added to DPDK for | |
174 | testing and prototyping purposes while the kernel work is ongoing. It should | |
175 | also be marked with an "EXPERIMENTAL" tag. If the functionality isn't | |
176 | upstreamable then a case can be made to maintain the PF functionality in DPDK | |
177 | without the EXPERIMENTAL tag. |