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