]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright 2018 The DPDK contributors | |
3 | ||
4 | DPDK ABI/API policy | |
5 | =================== | |
7c673cae FG |
6 | |
7 | Description | |
8 | ----------- | |
9 | ||
10 | This document details some methods for handling ABI management in the DPDK. | |
7c673cae FG |
11 | |
12 | General Guidelines | |
13 | ------------------ | |
14 | ||
15 | #. Whenever possible, ABI should be preserved | |
9f95a23c | 16 | #. ABI/API may be changed with a deprecation process |
7c673cae | 17 | #. The modification of symbols can generally be managed with versioning |
9f95a23c TL |
18 | #. Libraries or APIs marked in ``experimental`` state may change without constraint |
19 | #. New APIs will be marked as ``experimental`` for at least one release to allow | |
20 | any issues found by users of the new API to be fixed quickly | |
21 | #. The addition of symbols is generally not problematic | |
7c673cae FG |
22 | #. The removal of symbols generally is an ABI break and requires bumping of the |
23 | LIBABIVER macro | |
9f95a23c TL |
24 | #. Updates to the minimum hardware requirements, which drop support for hardware which |
25 | was previously supported, should be treated as an ABI change. | |
7c673cae FG |
26 | |
27 | What is an ABI | |
9f95a23c | 28 | ~~~~~~~~~~~~~~ |
7c673cae FG |
29 | |
30 | An ABI (Application Binary Interface) is the set of runtime interfaces exposed | |
31 | by a library. It is similar to an API (Application Programming Interface) but | |
32 | is the result of compilation. It is also effectively cloned when applications | |
33 | link to dynamic libraries. That is to say when an application is compiled to | |
34 | link against dynamic libraries, it is assumed that the ABI remains constant | |
35 | between the time the application is compiled/linked, and the time that it runs. | |
36 | Therefore, in the case of dynamic linking, it is critical that an ABI is | |
37 | preserved, or (when modified), done in such a way that the application is unable | |
38 | to behave improperly or in an unexpected fashion. | |
39 | ||
9f95a23c TL |
40 | |
41 | ABI/API Deprecation | |
7c673cae FG |
42 | ------------------- |
43 | ||
9f95a23c TL |
44 | The DPDK ABI policy |
45 | ~~~~~~~~~~~~~~~~~~~ | |
46 | ||
7c673cae FG |
47 | ABI versions are set at the time of major release labeling, and the ABI may |
48 | change multiple times, without warning, between the last release label and the | |
49 | HEAD label of the git tree. | |
50 | ||
51 | ABI versions, once released, are available until such time as their | |
52 | deprecation has been noted in the Release Notes for at least one major release | |
53 | cycle. For example consider the case where the ABI for DPDK 2.0 has been | |
54 | shipped and then a decision is made to modify it during the development of | |
55 | DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1 | |
56 | release and the modification will be made available in the DPDK 2.2 release. | |
57 | ||
58 | ABI versions may be deprecated in whole or in part as needed by a given | |
59 | update. | |
60 | ||
61 | Some ABI changes may be too significant to reasonably maintain multiple | |
62 | versions. In those cases ABI's may be updated without backward compatibility | |
63 | being provided. The requirements for doing so are: | |
64 | ||
65 | #. At least 3 acknowledgments of the need to do so must be made on the | |
66 | dpdk.org mailing list. | |
67 | ||
9f95a23c TL |
68 | - The acknowledgment of the maintainer of the component is mandatory, or if |
69 | no maintainer is available for the component, the tree/sub-tree maintainer | |
70 | for that component must acknowledge the ABI change instead. | |
71 | ||
72 | - It is also recommended that acknowledgments from different "areas of | |
73 | interest" be sought for each deprecation, for example: from NIC vendors, | |
74 | CPU vendors, end-users, etc. | |
75 | ||
76 | #. The changes (including an alternative map file) can be included with | |
77 | deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, | |
78 | to provide more details about oncoming changes. | |
79 | ``RTE_NEXT_ABI`` wrapper will be removed when it become the default ABI. | |
80 | More preferred way to provide this information is sending the feature | |
81 | as a separate patch and reference it in deprecation notice. | |
7c673cae FG |
82 | |
83 | #. A full deprecation cycle, as explained above, must be made to offer | |
84 | downstream consumers sufficient warning of the change. | |
85 | ||
7c673cae FG |
86 | Note that the above process for ABI deprecation should not be undertaken |
87 | lightly. ABI stability is extremely important for downstream consumers of the | |
88 | DPDK, especially when distributed in shared object form. Every effort should | |
89 | be made to preserve the ABI whenever possible. The ABI should only be changed | |
90 | for significant reasons, such as performance enhancements. ABI breakage due to | |
91 | changes such as reorganizing public structure fields for aesthetic or | |
92 | readability purposes should be avoided. | |
93 | ||
9f95a23c TL |
94 | .. note:: |
95 | ||
96 | Updates to the minimum hardware requirements, which drop support for hardware | |
97 | which was previously supported, should be treated as an ABI change, and | |
98 | follow the relevant deprecation policy procedures as above: 3 acks and | |
99 | announcement at least one release in advance. | |
100 | ||
7c673cae | 101 | Examples of Deprecation Notices |
9f95a23c | 102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
7c673cae FG |
103 | |
104 | The following are some examples of ABI deprecation notices which would be | |
105 | added to the Release Notes: | |
106 | ||
107 | * The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0, | |
108 | to be replaced with the inline function ``rte_foo()``. | |
109 | ||
110 | * The function ``rte_mbuf_grok()`` has been updated to include a new parameter | |
111 | in version 2.0. Backwards compatibility will be maintained for this function | |
112 | until the release of version 2.1 | |
113 | ||
114 | * The members of ``struct rte_foo`` have been reorganized in release 2.0 for | |
115 | performance reasons. Existing binary applications will have backwards | |
116 | compatibility in release 2.0, while newly built binaries will need to | |
117 | reference the new structure variant ``struct rte_foo2``. Compatibility will | |
118 | be removed in release 2.2, and all applications will require updating and | |
119 | rebuilding to the new structure at that time, which will be renamed to the | |
120 | original ``struct rte_foo``. | |
121 | ||
122 | * Significant ABI changes are planned for the ``librte_dostuff`` library. The | |
123 | upcoming release 2.0 will not contain these changes, but release 2.1 will, | |
124 | and no backwards compatibility is planned due to the extensive nature of | |
125 | these changes. Binaries using this library built prior to version 2.1 will | |
126 | require updating and recompilation. | |
127 | ||
9f95a23c TL |
128 | New API replacing previous one |
129 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7c673cae | 130 | |
9f95a23c TL |
131 | If a new API proposed functionally replaces an existing one, when the new API |
132 | becomes non-experimental then the old one is marked with ``__rte_deprecated``. | |
133 | Deprecated APIs are removed completely just after the next LTS. | |
7c673cae | 134 | |
9f95a23c | 135 | Reminder that old API should follow deprecation process to be removed. |
7c673cae | 136 | |
7c673cae | 137 | |
9f95a23c TL |
138 | Experimental APIs |
139 | ----------------- | |
7c673cae | 140 | |
9f95a23c TL |
141 | APIs marked as ``experimental`` are not considered part of the ABI and may |
142 | change without warning at any time. Since changes to APIs are most likely | |
143 | immediately after their introduction, as users begin to take advantage of | |
144 | those new APIs and start finding issues with them, new DPDK APIs will be | |
145 | automatically marked as ``experimental`` to allow for a period of stabilization | |
146 | before they become part of a tracked ABI. | |
147 | ||
148 | Note that marking an API as experimental is a multi step process. | |
149 | To mark an API as experimental, the symbols which are desired to be exported | |
150 | must be placed in an EXPERIMENTAL version block in the corresponding libraries' | |
151 | version map script. | |
152 | Secondly, the corresponding definitions of those exported functions, and | |
153 | their forward declarations (in the development header files), must be marked | |
154 | with the ``__rte_experimental`` tag (see ``rte_compat.h``). | |
155 | The DPDK build makefiles perform a check to ensure that the map file and the | |
156 | C code reflect the same list of symbols. | |
157 | This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API`` | |
158 | during compilation in the corresponding library Makefile. | |
159 | ||
160 | In addition to tagging the code with ``__rte_experimental``, | |
161 | the doxygen markup must also contain the EXPERIMENTAL string, | |
162 | and the MAINTAINERS file should note the EXPERIMENTAL libraries. | |
163 | ||
164 | For removing the experimental tag associated with an API, deprecation notice | |
165 | is not required. Though, an API should remain in experimental state for at least | |
166 | one release. Thereafter, normal process of posting patch for review to mailing | |
167 | list can be followed. | |
168 | ||
169 | ||
170 | Library versioning | |
171 | ------------------ | |
11fdf7f2 TL |
172 | |
173 | Downstreams might want to provide different DPDK releases at the same time to | |
174 | support multiple consumers of DPDK linked against older and newer sonames. | |
175 | ||
176 | Also due to the interdependencies that DPDK libraries can have applications | |
177 | might end up with an executable space in which multiple versions of a library | |
178 | are mapped by ld.so. | |
179 | ||
180 | Think of LibA that got an ABI bump and LibB that did not get an ABI bump but is | |
181 | depending on LibA. | |
182 | ||
183 | .. note:: | |
184 | ||
185 | Application | |
186 | \-> LibA.old | |
187 | \-> LibB.new -> LibA.new | |
188 | ||
189 | That is a conflict which can be avoided by setting ``CONFIG_RTE_MAJOR_ABI``. | |
190 | If set, the value of ``CONFIG_RTE_MAJOR_ABI`` overwrites all - otherwise per | |
191 | library - versions defined in the libraries ``LIBABIVER``. | |
192 | An example might be ``CONFIG_RTE_MAJOR_ABI=16.11`` which will make all libraries | |
193 | ``librte<?>.so.16.11`` instead of ``librte<?>.so.<LIBABIVER>``. | |
194 | ||
9f95a23c TL |
195 | |
196 | ABI versioning | |
197 | -------------- | |
198 | ||
199 | Versioning Macros | |
200 | ~~~~~~~~~~~~~~~~~ | |
201 | ||
202 | When a symbol is exported from a library to provide an API, it also provides a | |
203 | calling convention (ABI) that is embodied in its name, return type and | |
204 | arguments. Occasionally that function may need to change to accommodate new | |
205 | functionality or behavior. When that occurs, it is desirable to allow for | |
206 | backward compatibility for a time with older binaries that are dynamically | |
207 | linked to the DPDK. | |
208 | ||
209 | To support backward compatibility the ``rte_compat.h`` | |
210 | header file provides macros to use when updating exported functions. These | |
211 | macros are used in conjunction with the ``rte_<library>_version.map`` file for | |
212 | a given library to allow multiple versions of a symbol to exist in a shared | |
213 | library so that older binaries need not be immediately recompiled. | |
214 | ||
215 | The macros exported are: | |
216 | ||
217 | * ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding | |
218 | versioned symbol ``b@DPDK_n`` to the internal function ``b_e``. | |
219 | ||
220 | * ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing | |
221 | the linker to bind references to symbol ``b`` to the internal symbol | |
222 | ``b_e``. | |
223 | ||
224 | * ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the | |
225 | fully qualified function ``p``, so that if a symbol becomes versioned, it | |
226 | can still be mapped back to the public symbol name. | |
227 | ||
7c673cae | 228 | Examples of ABI Macro use |
9f95a23c | 229 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
7c673cae FG |
230 | |
231 | Updating a public API | |
9f95a23c | 232 | _____________________ |
7c673cae FG |
233 | |
234 | Assume we have a function as follows | |
235 | ||
236 | .. code-block:: c | |
237 | ||
238 | /* | |
239 | * Create an acl context object for apps to | |
240 | * manipulate | |
241 | */ | |
242 | struct rte_acl_ctx * | |
243 | rte_acl_create(const struct rte_acl_param *param) | |
244 | { | |
245 | ... | |
246 | } | |
247 | ||
248 | ||
249 | Assume that struct rte_acl_ctx is a private structure, and that a developer | |
250 | wishes to enhance the acl api so that a debugging flag can be enabled on a | |
251 | per-context basis. This requires an addition to the structure (which, being | |
252 | private, is safe), but it also requires modifying the code as follows | |
253 | ||
254 | .. code-block:: c | |
255 | ||
256 | /* | |
257 | * Create an acl context object for apps to | |
258 | * manipulate | |
259 | */ | |
260 | struct rte_acl_ctx * | |
261 | rte_acl_create(const struct rte_acl_param *param, int debug) | |
262 | { | |
263 | ... | |
264 | } | |
265 | ||
266 | ||
267 | Note also that, being a public function, the header file prototype must also be | |
268 | changed, as must all the call sites, to reflect the new ABI footprint. We will | |
269 | maintain previous ABI versions that are accessible only to previously compiled | |
270 | binaries | |
271 | ||
272 | The addition of a parameter to the function is ABI breaking as the function is | |
273 | public, and existing application may use it in its current form. However, the | |
274 | compatibility macros in DPDK allow a developer to use symbol versioning so that | |
275 | multiple functions can be mapped to the same public symbol based on when an | |
276 | application was linked to it. To see how this is done, we start with the | |
277 | requisite libraries version map file. Initially the version map file for the | |
278 | acl library looks like this | |
279 | ||
280 | .. code-block:: none | |
281 | ||
282 | DPDK_2.0 { | |
283 | global: | |
284 | ||
285 | rte_acl_add_rules; | |
286 | rte_acl_build; | |
287 | rte_acl_classify; | |
288 | rte_acl_classify_alg; | |
289 | rte_acl_classify_scalar; | |
290 | rte_acl_create; | |
291 | rte_acl_dump; | |
292 | rte_acl_find_existing; | |
293 | rte_acl_free; | |
294 | rte_acl_ipv4vlan_add_rules; | |
295 | rte_acl_ipv4vlan_build; | |
296 | rte_acl_list_dump; | |
297 | rte_acl_reset; | |
298 | rte_acl_reset_rules; | |
299 | rte_acl_set_ctx_classify; | |
300 | ||
301 | local: *; | |
302 | }; | |
303 | ||
304 | This file needs to be modified as follows | |
305 | ||
306 | .. code-block:: none | |
307 | ||
308 | DPDK_2.0 { | |
309 | global: | |
310 | ||
311 | rte_acl_add_rules; | |
312 | rte_acl_build; | |
313 | rte_acl_classify; | |
314 | rte_acl_classify_alg; | |
315 | rte_acl_classify_scalar; | |
316 | rte_acl_create; | |
317 | rte_acl_dump; | |
318 | rte_acl_find_existing; | |
319 | rte_acl_free; | |
320 | rte_acl_ipv4vlan_add_rules; | |
321 | rte_acl_ipv4vlan_build; | |
322 | rte_acl_list_dump; | |
323 | rte_acl_reset; | |
324 | rte_acl_reset_rules; | |
325 | rte_acl_set_ctx_classify; | |
326 | ||
327 | local: *; | |
328 | }; | |
329 | ||
330 | DPDK_2.1 { | |
331 | global: | |
332 | rte_acl_create; | |
333 | ||
334 | } DPDK_2.0; | |
335 | ||
336 | The addition of the new block tells the linker that a new version node is | |
337 | available (DPDK_2.1), which contains the symbol rte_acl_create, and inherits the | |
338 | symbols from the DPDK_2.0 node. This list is directly translated into a list of | |
339 | exported symbols when DPDK is compiled as a shared library | |
340 | ||
341 | Next, we need to specify in the code which function map to the rte_acl_create | |
342 | symbol at which versions. First, at the site of the initial symbol definition, | |
343 | we need to update the function so that it is uniquely named, and not in conflict | |
344 | with the public symbol name | |
345 | ||
346 | .. code-block:: c | |
347 | ||
348 | struct rte_acl_ctx * | |
349 | -rte_acl_create(const struct rte_acl_param *param) | |
350 | +rte_acl_create_v20(const struct rte_acl_param *param) | |
351 | { | |
352 | size_t sz; | |
353 | struct rte_acl_ctx *ctx; | |
354 | ... | |
355 | ||
356 | Note that the base name of the symbol was kept intact, as this is conducive to | |
357 | the macros used for versioning symbols. That is our next step, mapping this new | |
358 | symbol name to the initial symbol name at version node 2.0. Immediately after | |
359 | the function, we add this line of code | |
360 | ||
361 | .. code-block:: c | |
362 | ||
363 | VERSION_SYMBOL(rte_acl_create, _v20, 2.0); | |
364 | ||
365 | Remembering to also add the rte_compat.h header to the requisite c file where | |
366 | these changes are being made. The above macro instructs the linker to create a | |
367 | new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older | |
368 | builds, but now points to the above newly named function. We have now mapped | |
369 | the original rte_acl_create symbol to the original function (but with a new | |
370 | name) | |
371 | ||
372 | Next, we need to create the 2.1 version of the symbol. We create a new function | |
373 | name, with a different suffix, and implement it appropriately | |
374 | ||
375 | .. code-block:: c | |
376 | ||
377 | struct rte_acl_ctx * | |
378 | rte_acl_create_v21(const struct rte_acl_param *param, int debug); | |
379 | { | |
380 | struct rte_acl_ctx *ctx = rte_acl_create_v20(param); | |
381 | ||
382 | ctx->debug = debug; | |
383 | ||
384 | return ctx; | |
385 | } | |
386 | ||
387 | This code serves as our new API call. Its the same as our old call, but adds | |
388 | the new parameter in place. Next we need to map this function to the symbol | |
389 | ``rte_acl_create@DPDK_2.1``. To do this, we modify the public prototype of the call | |
390 | in the header file, adding the macro there to inform all including applications, | |
391 | that on re-link, the default rte_acl_create symbol should point to this | |
392 | function. Note that we could do this by simply naming the function above | |
393 | rte_acl_create, and the linker would chose the most recent version tag to apply | |
394 | in the version script, but we can also do this in the header file | |
395 | ||
396 | .. code-block:: c | |
397 | ||
398 | struct rte_acl_ctx * | |
399 | -rte_acl_create(const struct rte_acl_param *param); | |
400 | +rte_acl_create(const struct rte_acl_param *param, int debug); | |
401 | +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1); | |
402 | ||
403 | The BIND_DEFAULT_SYMBOL macro explicitly tells applications that include this | |
404 | header, to link to the rte_acl_create_v21 function and apply the DPDK_2.1 | |
405 | version node to it. This method is more explicit and flexible than just | |
406 | re-implementing the exact symbol name, and allows for other features (such as | |
407 | linking to the old symbol version by default, when the new ABI is to be opt-in | |
408 | for a period. | |
409 | ||
410 | One last thing we need to do. Note that we've taken what was a public symbol, | |
411 | and duplicated it into two uniquely and differently named symbols. We've then | |
412 | mapped each of those back to the public symbol ``rte_acl_create`` with different | |
413 | version tags. This only applies to dynamic linking, as static linking has no | |
414 | notion of versioning. That leaves this code in a position of no longer having a | |
415 | symbol simply named ``rte_acl_create`` and a static build will fail on that | |
416 | missing symbol. | |
417 | ||
418 | To correct this, we can simply map a function of our choosing back to the public | |
419 | symbol in the static build with the ``MAP_STATIC_SYMBOL`` macro. Generally the | |
420 | assumption is that the most recent version of the symbol is the one you want to | |
421 | map. So, back in the C file where, immediately after ``rte_acl_create_v21`` is | |
422 | defined, we add this | |
423 | ||
424 | .. code-block:: c | |
425 | ||
426 | struct rte_acl_ctx * | |
427 | rte_acl_create_v21(const struct rte_acl_param *param, int debug) | |
428 | { | |
429 | ... | |
430 | } | |
431 | MAP_STATIC_SYMBOL(struct rte_acl_ctx *rte_acl_create(const struct rte_acl_param *param, int debug), rte_acl_create_v21); | |
432 | ||
433 | That tells the compiler that, when building a static library, any calls to the | |
434 | symbol ``rte_acl_create`` should be linked to ``rte_acl_create_v21`` | |
435 | ||
436 | That's it, on the next shared library rebuild, there will be two versions of | |
437 | rte_acl_create, an old DPDK_2.0 version, used by previously built applications, | |
438 | and a new DPDK_2.1 version, used by future built applications. | |
439 | ||
440 | ||
441 | Deprecating part of a public API | |
9f95a23c | 442 | ________________________________ |
7c673cae FG |
443 | |
444 | Lets assume that you've done the above update, and after a few releases have | |
445 | passed you decide you would like to retire the old version of the function. | |
446 | After having gone through the ABI deprecation announcement process, removal is | |
447 | easy. Start by removing the symbol from the requisite version map file: | |
448 | ||
449 | .. code-block:: none | |
450 | ||
451 | DPDK_2.0 { | |
452 | global: | |
453 | ||
454 | rte_acl_add_rules; | |
455 | rte_acl_build; | |
456 | rte_acl_classify; | |
457 | rte_acl_classify_alg; | |
458 | rte_acl_classify_scalar; | |
459 | rte_acl_dump; | |
460 | - rte_acl_create | |
461 | rte_acl_find_existing; | |
462 | rte_acl_free; | |
463 | rte_acl_ipv4vlan_add_rules; | |
464 | rte_acl_ipv4vlan_build; | |
465 | rte_acl_list_dump; | |
466 | rte_acl_reset; | |
467 | rte_acl_reset_rules; | |
468 | rte_acl_set_ctx_classify; | |
469 | ||
470 | local: *; | |
471 | }; | |
472 | ||
473 | DPDK_2.1 { | |
474 | global: | |
475 | rte_acl_create; | |
476 | } DPDK_2.0; | |
477 | ||
478 | ||
479 | Next remove the corresponding versioned export. | |
480 | ||
481 | .. code-block:: c | |
482 | ||
483 | -VERSION_SYMBOL(rte_acl_create, _v20, 2.0); | |
484 | ||
485 | ||
486 | Note that the internal function definition could also be removed, but its used | |
487 | in our example by the newer version _v21, so we leave it in place. This is a | |
488 | coding style choice. | |
489 | ||
490 | Lastly, we need to bump the LIBABIVER number for this library in the Makefile to | |
491 | indicate to applications doing dynamic linking that this is a later, and | |
492 | possibly incompatible library version: | |
493 | ||
494 | .. code-block:: c | |
495 | ||
496 | -LIBABIVER := 1 | |
497 | +LIBABIVER := 2 | |
498 | ||
499 | Deprecating an entire ABI version | |
9f95a23c | 500 | _________________________________ |
7c673cae FG |
501 | |
502 | While removing a symbol from and ABI may be useful, it is often more practical | |
503 | to remove an entire version node at once. If a version node completely | |
504 | specifies an API, then removing part of it, typically makes it incomplete. In | |
505 | those cases it is better to remove the entire node | |
506 | ||
507 | To do this, start by modifying the version map file, such that all symbols from | |
508 | the node to be removed are merged into the next node in the map | |
509 | ||
510 | In the case of our map above, it would transform to look as follows | |
511 | ||
512 | .. code-block:: none | |
513 | ||
514 | DPDK_2.1 { | |
515 | global: | |
516 | ||
517 | rte_acl_add_rules; | |
518 | rte_acl_build; | |
519 | rte_acl_classify; | |
520 | rte_acl_classify_alg; | |
521 | rte_acl_classify_scalar; | |
522 | rte_acl_dump; | |
523 | rte_acl_create | |
524 | rte_acl_find_existing; | |
525 | rte_acl_free; | |
526 | rte_acl_ipv4vlan_add_rules; | |
527 | rte_acl_ipv4vlan_build; | |
528 | rte_acl_list_dump; | |
529 | rte_acl_reset; | |
530 | rte_acl_reset_rules; | |
531 | rte_acl_set_ctx_classify; | |
532 | ||
533 | local: *; | |
534 | }; | |
535 | ||
536 | Then any uses of BIND_DEFAULT_SYMBOL that pointed to the old node should be | |
537 | updated to point to the new version node in any header files for all affected | |
538 | symbols. | |
539 | ||
540 | .. code-block:: c | |
541 | ||
542 | -BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 2.0); | |
543 | +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1); | |
544 | ||
545 | Lastly, any VERSION_SYMBOL macros that point to the old version node should be | |
546 | removed, taking care to keep, where need old code in place to support newer | |
547 | versions of the symbol. | |
548 | ||
9f95a23c | 549 | |
7c673cae FG |
550 | Running the ABI Validator |
551 | ------------------------- | |
552 | ||
11fdf7f2 | 553 | The ``devtools`` directory in the DPDK source tree contains a utility program, |
7c673cae FG |
554 | ``validate-abi.sh``, for validating the DPDK ABI based on the Linux `ABI |
555 | Compliance Checker | |
556 | <http://ispras.linuxbase.org/index.php/ABI_compliance_checker>`_. | |
557 | ||
558 | This has a dependency on the ``abi-compliance-checker`` and ``and abi-dumper`` | |
559 | utilities which can be installed via a package manager. For example:: | |
560 | ||
561 | sudo yum install abi-compliance-checker | |
562 | sudo yum install abi-dumper | |
563 | ||
564 | The syntax of the ``validate-abi.sh`` utility is:: | |
565 | ||
9f95a23c | 566 | ./devtools/validate-abi.sh <REV1> <REV2> |
7c673cae FG |
567 | |
568 | Where ``REV1`` and ``REV2`` are valid gitrevisions(7) | |
569 | https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html | |
9f95a23c | 570 | on the local repo. |
7c673cae FG |
571 | |
572 | For example:: | |
573 | ||
574 | # Check between the previous and latest commit: | |
9f95a23c TL |
575 | ./devtools/validate-abi.sh HEAD~1 HEAD |
576 | ||
577 | # Check on a specific compilation target: | |
578 | ./devtools/validate-abi.sh -t x86_64-native-linux-gcc HEAD~1 HEAD | |
7c673cae FG |
579 | |
580 | # Check between two tags: | |
9f95a23c | 581 | ./devtools/validate-abi.sh v2.0.0 v2.1.0 |
7c673cae FG |
582 | |
583 | # Check between git master and local topic-branch "vhost-hacking": | |
9f95a23c | 584 | ./devtools/validate-abi.sh master vhost-hacking |
7c673cae FG |
585 | |
586 | After the validation script completes (it can take a while since it need to | |
587 | compile both tags) it will create compatibility reports in the | |
9f95a23c TL |
588 | ``./abi-check/compat_report`` directory. Listed incompatibilities can be found |
589 | as follows:: | |
7c673cae | 590 | |
9f95a23c | 591 | grep -lr Incompatible abi-check/compat_reports/ |