diff options
author | 2016-06-14 07:54:47 -0700 | |
---|---|---|
committer | 2016-06-14 07:55:43 -0700 | |
commit | 5129044dce1f85ce4950f31bcf90f3886466f06a (patch) | |
tree | 1c6269614c0c15ffef8451c58ae8f8b30a1bc804 /doc/guides/contributing | |
parent | e04be89c2409570e0055b2cda60bd11395bb93b0 (diff) |
Imported upstream release 16.04
* gbp import-orig ../dpdk-16.04.tar.xz
Change-Id: Iac2196db782ba322f6974d8a752acc34ce5024c3
Signed-off-by: C.J. Collier <cjcollier@linuxfoundation.org>
Diffstat (limited to 'doc/guides/contributing')
-rw-r--r-- | doc/guides/contributing/cheatsheet.rst | 8 | ||||
-rw-r--r-- | doc/guides/contributing/coding_style.rst | 687 | ||||
-rw-r--r-- | doc/guides/contributing/design.rst | 160 | ||||
-rw-r--r-- | doc/guides/contributing/documentation.rst | 752 | ||||
-rw-r--r-- | doc/guides/contributing/img/patch_cheatsheet.svg | 1484 | ||||
-rw-r--r-- | doc/guides/contributing/index.rst | 13 | ||||
-rw-r--r-- | doc/guides/contributing/patches.rst | 395 | ||||
-rw-r--r-- | doc/guides/contributing/versioning.rst | 494 |
8 files changed, 3993 insertions, 0 deletions
diff --git a/doc/guides/contributing/cheatsheet.rst b/doc/guides/contributing/cheatsheet.rst new file mode 100644 index 00000000..7bc07715 --- /dev/null +++ b/doc/guides/contributing/cheatsheet.rst @@ -0,0 +1,8 @@ +Patch Cheatsheet +================ + +.. _figure_patch_cheatsheet: + +.. figure:: img/patch_cheatsheet.* + + Cheat sheet for submitting patches to dev@dpdk.org diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst new file mode 100644 index 00000000..ad1392d2 --- /dev/null +++ b/doc/guides/contributing/coding_style.rst @@ -0,0 +1,687 @@ +.. _coding_style: + +DPDK Coding Style +================= + +Description +----------- + +This document specifies the preferred style for source files in the DPDK source tree. +It is based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK. + +General Guidelines +------------------ + +The rules and guidelines given in this document cannot cover every situation, so the following general guidelines should be used as a fallback: + +* The code style should be consistent within each individual file. +* In the case of creating new files, the style should be consistent within each file in a given directory or module. +* The primary reason for coding standards is to increase code readability and comprehensibility, therefore always use whatever option will make the code easiest to read. + +Line length is recommended to be not more than 80 characters, including comments. +[Tab stop size should be assumed to be 8-characters wide]. + +.. note:: + + The above is recommendation, and not a hard limit. + However, it is expected that the recommendations should be followed in all but the rarest situations. + +C Comment Style +--------------- + +Usual Comments +~~~~~~~~~~~~~~ + +These comments should be used in normal cases. +To document a public API, a doxygen-like format must be used: refer to :ref:`doxygen_guidelines`. + +.. code-block:: c + + /* + * VERY important single-line comments look like this. + */ + + /* Most single-line comments look like this. */ + + /* + * Multi-line comments look like this. Make them real sentences. Fill + * them so they look like real paragraphs. + */ + +License Header +~~~~~~~~~~~~~~ + +Each file should begin with a special comment containing the appropriate copyright and license for the file. +Generally this is the BSD License, except for code for Linux Kernel modules. +After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file. + +C Preprocessor Directives +------------------------- + +Header Includes +~~~~~~~~~~~~~~~ + +In DPDK sources, the include files should be ordered as following: + +#. libc includes (system includes first) +#. DPDK EAL includes +#. DPDK misc libraries includes +#. application-specific includes + +Include files from the local application directory are included using quotes, while includes from other paths are included using angle brackets: "<>". + +Example: + +.. code-block:: c + + #include <stdio.h> + #include <stdlib.h> + + #include <rte_eal.h> + + #include <rte_ring.h> + #include <rte_mempool.h> + + #include "application.h" + +Header File Guards +~~~~~~~~~~~~~~~~~~ + +Headers should be protected against multiple inclusion with the usual: + +.. code-block:: c + + #ifndef _FILE_H_ + #define _FILE_H_ + + /* Code */ + + #endif /* _FILE_H_ */ + + +Macros +~~~~~~ + +Do not ``#define`` or declare names except with the standard DPDK prefix: ``RTE_``. +This is to ensure there are no collisions with definitions in the application itself. + +The names of "unsafe" macros (ones that have side effects), and the names of macros for manifest constants, are all in uppercase. + +The expansions of expression-like macros are either a single token or have outer parentheses. +If a macro is an inline expansion of a function, the function name is all in lowercase and the macro has the same name all in uppercase. +If the macro encapsulates a compound statement, enclose it in a do-while loop, so that it can be used safely in if statements. +Any final statement-terminating semicolon should be supplied by the macro invocation rather than the macro, to make parsing easier for pretty-printers and editors. + +For example: + +.. code-block:: c + + #define MACRO(x, y) do { \ + variable = (x) + (y); \ + (y) += 2; \ + } while(0) + +.. note:: + + Wherever possible, enums and inline functions should be preferred to macros, since they provide additional degrees of type-safety and can allow compilers to emit extra warnings about unsafe code. + +Conditional Compilation +~~~~~~~~~~~~~~~~~~~~~~~ + +* When code is conditionally compiled using ``#ifdef`` or ``#if``, a comment may be added following the matching + ``#endif`` or ``#else`` to permit the reader to easily discern where conditionally compiled code regions end. +* This comment should be used only for (subjectively) long regions, regions greater than 20 lines, or where a series of nested ``#ifdef``'s may be confusing to the reader. + Exceptions may be made for cases where code is conditionally not compiled for the purposes of lint(1), or other tools, even though the uncompiled region may be small. +* The comment should be separated from the ``#endif`` or ``#else`` by a single space. +* For short conditionally compiled regions, a closing comment should not be used. +* The comment for ``#endif`` should match the expression used in the corresponding ``#if`` or ``#ifdef``. +* The comment for ``#else`` and ``#elif`` should match the inverse of the expression(s) used in the preceding ``#if`` and/or ``#elif`` statements. +* In the comments, the subexpression ``defined(FOO)`` is abbreviated as "FOO". + For the purposes of comments, ``#ifndef FOO`` is treated as ``#if !defined(FOO)``. + +.. code-block:: c + + #ifdef KTRACE + #include <sys/ktrace.h> + #endif + + #ifdef COMPAT_43 + /* A large region here, or other conditional code. */ + #else /* !COMPAT_43 */ + /* Or here. */ + #endif /* COMPAT_43 */ + + #ifndef COMPAT_43 + /* Yet another large region here, or other conditional code. */ + #else /* COMPAT_43 */ + /* Or here. */ + #endif /* !COMPAT_43 */ + +.. note:: + + Conditional compilation should be used only when absolutely necessary, as it increases the number of target binaries that need to be built and tested. + +C Types +------- + +Integers +~~~~~~~~ + +For fixed/minimum-size integer values, the project uses the form uintXX_t (from stdint.h) instead of older BSD-style integer identifiers of the form u_intXX_t. + +Enumerations +~~~~~~~~~~~~ + +* Enumeration values are all uppercase. + +.. code-block:: c + + enum enumtype { ONE, TWO } et; + +* Enum types should be used in preference to macros #defining a set of (sequential) values. +* Enum types should be prefixed with ``rte_`` and the elements by a suitable prefix [generally starting ``RTE_<enum>_`` - where <enum> is a shortname for the enum type] to avoid namespace collisions. + +Bitfields +~~~~~~~~~ + +The developer should group bitfields that are included in the same integer, as follows: + +.. code-block:: c + + struct grehdr { + uint16_t rec:3, + srr:1, + seq:1, + key:1, + routing:1, + csum:1, + version:3, + reserved:4, + ack:1; + /* ... */ + } + +Variable Declarations +~~~~~~~~~~~~~~~~~~~~~ + +In declarations, do not put any whitespace between asterisks and adjacent tokens, except for tokens that are identifiers related to types. +(These identifiers are the names of basic types, type qualifiers, and typedef-names other than the one being declared.) +Separate these identifiers from asterisks using a single space. + +For example: + +.. code-block:: c + + int *x; /* no space after asterisk */ + int * const x; /* space after asterisk when using a type qualifier */ + +* All externally-visible variables should have an ``rte_`` prefix in the name to avoid namespace collisions. +* Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in variable names. + Lower-case letters and underscores only. + +Structure Declarations +~~~~~~~~~~~~~~~~~~~~~~ + +* In general, when declaring variables in new structures, declare them sorted by use, then by size (largest to smallest), and then in alphabetical order. + Sorting by use means that commonly used variables are used together and that the structure layout makes logical sense. + Ordering by size then ensures that as little padding is added to the structure as possible. +* For existing structures, additions to structures should be added to the end so for backward compatibility reasons. +* Each structure element gets its own line. +* Try to make the structure readable by aligning the member names using spaces as shown below. +* Names following extremely long types, which therefore cannot be easily aligned with the rest, should be separated by a single space. + +.. code-block:: c + + struct foo { + struct foo *next; /* List of active foo. */ + struct mumble amumble; /* Comment for mumble. */ + int bar; /* Try to align the comments. */ + struct verylongtypename *baz; /* Won't fit with other members */ + }; + + +* Major structures should be declared at the top of the file in which they are used, or in separate header files if they are used in multiple source files. +* Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file. +* Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions. + +Queues +~~~~~~ + +Use queue(3) macros rather than rolling your own lists, whenever possible. +Thus, the previous example would be better written: + +.. code-block:: c + + #include <sys/queue.h> + + struct foo { + LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */ + struct mumble amumble; /* Comment for mumble. */ + int bar; /* Try to align the comments. */ + struct verylongtypename *baz; /* Won't fit with other members */ + }; + LIST_HEAD(, foo) foohead; /* Head of global foo list. */ + + +DPDK also provides an optimized way to store elements in lockless rings. +This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access. + +Typedefs +~~~~~~~~ + +Avoid using typedefs for structure types. + +For example, use: + +.. code-block:: c + + struct my_struct_type { + /* ... */ + }; + + struct my_struct_type my_var; + + +rather than: + +.. code-block:: c + + typedef struct my_struct_type { + /* ... */ + } my_struct_type; + + my_struct_type my_var + + +Typedefs are problematic because they do not properly hide their underlying type; +for example, you need to know if the typedef is the structure itself, as shown above, or a pointer to the structure. +In addition, they must be declared exactly once, whereas an incomplete structure type can be mentioned as many times as necessary. +Typedefs are difficult to use in stand-alone header files. +The header that defines the typedef must be included before the header that uses it, or by the header that uses it (which causes namespace pollution), +or there must be a back-door mechanism for obtaining the typedef. + +Note that #defines used instead of typedefs also are problematic (since they do not propagate the pointer type correctly due to direct text replacement). +For example, ``#define pint int *`` does not work as expected, while ``typedef int *pint`` does work. +As stated when discussing macros, typedefs should be preferred to macros in cases like this. + +When convention requires a typedef; make its name match the struct tag. +Avoid typedefs ending in ``_t``, except as specified in Standard C or by POSIX. + +.. note:: + + It is recommended to use typedefs to define function pointer types, for reasons of code readability. + This is especially true when the function type is used as a parameter to another function. + +For example: + +.. code-block:: c + + /** + * Definition of a remote launch function. + */ + typedef int (lcore_function_t)(void *); + + /* launch a function of lcore_function_t type */ + int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned slave_id); + + +C Indentation +------------- + +General +~~~~~~~ + +* Indentation is a hard tab, that is, a tab character, not a sequence of spaces, + +.. note:: + + Global whitespace rule in DPDK, use tabs for indentation, spaces for alignment. + +* Do not put any spaces before a tab for indentation. +* If you have to wrap a long statement, put the operator at the end of the line, and indent again. +* For control statements (if, while, etc.), continuation it is recommended that the next line be indented by two tabs, rather than one, + to prevent confusion as to whether the second line of the control statement forms part of the statement body or not. + Alternatively, the line continuation may use additional spaces to line up to an appropriately point on the preceding line, for example, to align to an opening brace. + +.. note:: + + As with all style guidelines, code should match style already in use in an existing file. + +.. code-block:: c + + while (really_long_variable_name_1 == really_long_variable_name_2 && + var3 == var4){ /* confusing to read as */ + x = y + z; /* control stmt body lines up with second line of */ + a = b + c; /* control statement itself if single indent used */ + } + + if (really_long_variable_name_1 == really_long_variable_name_2 && + var3 == var4){ /* two tabs used */ + x = y + z; /* statement body no longer lines up */ + a = b + c; + } + + z = a + really + long + statement + that + needs + + two + lines + gets + indented + on + the + + second + and + subsequent + lines; + + +* Do not add whitespace at the end of a line. + +* Do not add whitespace or a blank line at the end of a file. + + +Control Statements and Loops +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Include a space after keywords (if, while, for, return, switch). +* Do not use braces (``{`` and ``}``) for control statements with zero or just a single statement, unless that statement is more than a single line in which case the braces are permitted. + +.. code-block:: c + + for (p = buf; *p != '\0'; ++p) + ; /* nothing */ + for (;;) + stmt; + for (;;) { + z = a + really + long + statement + that + needs + + two + lines + gets + indented + on + the + + second + and + subsequent + lines; + } + for (;;) { + if (cond) + stmt; + } + if (val != NULL) + val = realloc(val, newsize); + + +* Parts of a for loop may be left empty. + +.. code-block:: c + + for (; cnt < 15; cnt++) { + stmt1; + stmt2; + } + +* Closing and opening braces go on the same line as the else keyword. +* Braces that are not necessary should be left out. + +.. code-block:: c + + if (test) + stmt; + else if (bar) { + stmt; + stmt; + } else + stmt; + + +Function Calls +~~~~~~~~~~~~~~ + +* Do not use spaces after function names. +* Commas should have a space after them. +* No spaces after ``(`` or ``[`` or preceding the ``]`` or ``)`` characters. + +.. code-block:: c + + error = function(a1, a2); + if (error != 0) + exit(error); + + +Operators +~~~~~~~~~ + +* Unary operators do not require spaces, binary operators do. +* Do not use parentheses unless they are required for precedence or unless the statement is confusing without them. + However, remember that other people may be more easily confused than you. + +Exit +~~~~ + +Exits should be 0 on success, or 1 on failure. + +.. code-block:: c + + exit(0); /* + * Avoid obvious comments such as + * "Exit 0 on success." + */ + } + +Local Variables +~~~~~~~~~~~~~~~ + +* Variables should be declared at the start of a block of code rather than in the middle. + The exception to this is when the variable is ``const`` in which case the declaration must be at the point of first use/assignment. +* When declaring variables in functions, multiple variables per line are OK. + However, if multiple declarations would cause the line to exceed a reasonable line length, begin a new set of declarations on the next line rather than using a line continuation. +* Be careful to not obfuscate the code by initializing variables in the declarations, only the last variable on a line should be initialized. + If multiple variables are to be initialized when defined, put one per line. +* Do not use function calls in initializers, except for ``const`` variables. + +.. code-block:: c + + int i = 0, j = 0, k = 0; /* bad, too many initializer */ + + char a = 0; /* OK, one variable per line with initializer */ + char b = 0; + + float x, y = 0.0; /* OK, only last variable has initializer */ + + +Casts and sizeof +~~~~~~~~~~~~~~~~ + +* Casts and sizeof statements are not followed by a space. +* Always write sizeof statements with parenthesis. + The redundant parenthesis rules do not apply to sizeof(var) instances. + +C Function Definition, Declaration and Use +------------------------------------------- + +Prototypes +~~~~~~~~~~ + +* It is recommended (and generally required by the compiler) that all non-static functions are prototyped somewhere. +* Functions local to one source module should be declared static, and should not be prototyped unless absolutely necessary. +* Functions used from other parts of code (external API) must be prototyped in the relevant include file. +* Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering. +* Functions that are used locally in more than one module go into a separate header file, for example, "extern.h". +* Do not use the ``__P`` macro. +* Functions that are part of an external API should be documented using Doxygen-like comments above declarations. See :ref:`doxygen_guidelines` for details. +* Functions that are part of the external API must have an ``rte_`` prefix on the function name. +* Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in function names. Lower-case letters and underscores only. +* When prototyping functions, associate names with parameter types, for example: + +.. code-block:: c + + void function1(int fd); /* good */ + void function2(int); /* bad */ + +* Short function prototypes should be contained on a single line. + Longer prototypes, e.g. those with many parameters, can be split across multiple lines. + The second and subsequent lines should be further indented as for line statement continuations as described in the previous section. + +.. code-block:: c + + static char *function1(int _arg, const char *_arg2, + struct foo *_arg3, + struct bar *_arg4, + struct baz *_arg5); + static void usage(void); + +.. note:: + + Unlike function definitions, the function prototypes do not need to place the function return type on a separate line. + +Definitions +~~~~~~~~~~~ + +* The function type should be on a line by itself preceding the function. +* The opening brace of the function body should be on a line by itself. + +.. code-block:: c + + static char * + function(int a1, int a2, float fl, int a4) + { + + +* Do not declare functions inside other functions. + ANSI C states that such declarations have file scope regardless of the nesting of the declaration. + Hiding file declarations in what appears to be a local scope is undesirable and will elicit complaints from a good compiler. +* Old-style (K&R) function declaration should not be used, use ANSI function declarations instead as shown below. +* Long argument lists should be wrapped as described above in the function prototypes section. + +.. code-block:: c + + /* + * All major routines should have a comment briefly describing what + * they do. The comment before the "main" routine should describe + * what the program does. + */ + int + main(int argc, char *argv[]) + { + char *ep; + long num; + int ch; + +C Statement Style and Conventions +--------------------------------- + +NULL Pointers +~~~~~~~~~~~~~ + +* NULL is the preferred null pointer constant. + Use NULL instead of ``(type *)0`` or ``(type *)NULL``, except where the compiler does not know the destination type e.g. for variadic args to a function. +* Test pointers against NULL, for example, use: + +.. code-block:: c + + if (p == NULL) /* Good, compare pointer to NULL */ + + if (!p) /* Bad, using ! on pointer */ + + +* Do not use ! for tests unless it is a boolean, for example, use: + +.. code-block:: c + + if (*p == '\0') /* check character against (char)0 */ + +Return Value +~~~~~~~~~~~~ + +* Functions which create objects, or allocate memory, should return pointer types, and NULL on error. + The error type should be indicated may setting the variable ``rte_errno`` appropriately. +* Functions which work on bursts of packets, such as RX-like or TX-like functions, should return the number of packets handled. +* Other functions returning int should generally behave like system calls: + returning 0 on success and -1 on error, setting ``rte_errno`` to indicate the specific type of error. +* Where already standard in a given library, the alternative error approach may be used where the negative value is not -1 but is instead ``-errno`` if relevant, for example, ``-EINVAL``. + Note, however, to allow consistency across functions returning integer or pointer types, the previous approach is preferred for any new libraries. +* For functions where no error is possible, the function type should be ``void`` not ``int``. +* Routines returning ``void *`` should not have their return values cast to any pointer type. + (Typecasting can prevent the compiler from warning about missing prototypes as any implicit definition of a function returns int, + which, unlike ``void *``, needs a typecast to assign to a pointer variable.) + +.. note:: + + The above rule about not typecasting ``void *`` applies to malloc, as well as to DPDK functions. + +* Values in return statements should not be enclosed in parentheses. + +Logging and Errors +~~~~~~~~~~~~~~~~~~ + +In the DPDK environment, use the logging interface provided: + +.. code-block:: c + + #define RTE_LOGTYPE_TESTAPP1 RTE_LOGTYPE_USER1 + #define RTE_LOGTYPE_TESTAPP2 RTE_LOGTYPE_USER2 + + /* enable these logs type */ + rte_set_log_type(RTE_LOGTYPE_TESTAPP1, 1); + rte_set_log_type(RTE_LOGTYPE_TESTAPP2, 1); + + /* log in debug level */ + rte_set_log_level(RTE_LOG_DEBUG); + RTE_LOG(DEBUG, TESTAPP1, "this is is a debug level message\n"); + RTE_LOG(INFO, TESTAPP1, "this is is a info level message\n"); + RTE_LOG(WARNING, TESTAPP1, "this is is a warning level message\n"); + + /* log in info level */ + rte_set_log_level(RTE_LOG_INFO); + RTE_LOG(DEBUG, TESTAPP2, "debug level message (not displayed)\n"); + +Branch Prediction +~~~~~~~~~~~~~~~~~ + +* When a test is done in a critical zone (called often or in a data path) the code can use the ``likely()`` and ``unlikely()`` macros to indicate the expected, or preferred fast path. + They are expanded as a compiler builtin and allow the developer to indicate if the branch is likely to be taken or not. Example: + +.. code-block:: c + + #include <rte_branch_prediction.h> + if (likely(x > 1)) + do_stuff(); + +.. note:: + + The use of ``likely()`` and ``unlikely()`` should only be done in performance critical paths, + and only when there is a clearly preferred path, or a measured performance increase gained from doing so. + These macros should be avoided in non-performance-critical code. + +Static Variables and Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code). +* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file. + +.. note:: + Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused. + +Const Attribute +~~~~~~~~~~~~~~~ + +The ``const`` attribute should be used as often as possible when a variable is read-only. + +Inline ASM in C code +~~~~~~~~~~~~~~~~~~~~ + +The ``asm`` and ``volatile`` keywords do not have underscores. The AT&T syntax should be used. +Input and output operands should be named to avoid confusion, as shown in the following example: + +.. code-block:: c + + asm volatile("outb %[val], %[port]" + : : + [port] "dN" (port), + [val] "a" (val)); + +Control Statements +~~~~~~~~~~~~~~~~~~ + +* Forever loops are done with for statements, not while statements. +* Elements in a switch statement that cascade should have a FALLTHROUGH comment. For example: + +.. code-block:: c + + switch (ch) { /* Indent the switch. */ + case 'a': /* Don't indent the case. */ + aflag = 1; /* Indent case body one tab. */ + /* FALLTHROUGH */ + case 'b': + bflag = 1; + break; + case '?': + default: + usage(); + /* NOTREACHED */ + } diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst new file mode 100644 index 00000000..bac3d1b4 --- /dev/null +++ b/doc/guides/contributing/design.rst @@ -0,0 +1,160 @@ +Design +====== + +Environment or Architecture-specific Sources +-------------------------------------------- + +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. +As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL. + +By convention, a file is common if it is not located in a directory indicating that it is specific. +For instance, a file located in a subdir of "x86_64" directory is specific to this architecture. +A file located in a subdir of "linuxapp" is specific to this execution environment. + +.. note:: + + Code in DPDK libraries and applications should be generic. + The correct location for architecture or executive environment specific code is in the EAL. + +When absolutely necessary, there are several ways to handle specific code: + +* Use a ``#ifdef`` with the CONFIG option in the C code. + This can be done when the differences are small and they can be embedded in the same C file: + + .. code-block:: c + + #ifdef RTE_ARCH_I686 + toto(); + #else + titi(); + #endif + +* Use the CONFIG option in the Makefile. This is done when the differences are more significant. + 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. + +.. note:: + + As in the linux kernel, the ``CONFIG_`` prefix is not used in C code. + This is only needed in Makefiles or shell scripts. + +Per Architecture Sources +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following config options can be used: + +* ``CONFIG_RTE_ARCH`` is a string that contains the name of the architecture. +* ``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. + +Per Execution Environment Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following config options can be used: + +* ``CONFIG_RTE_EXEC_ENV`` is a string that contains the name of the executive environment. +* ``CONFIG_RTE_EXEC_ENV_BSDAPP`` or ``CONFIG_RTE_EXEC_ENV_LINUXAPP`` are defined only if we are building for this execution environment. + +Library Statistics +------------------ + +Description +~~~~~~~~~~~ + +This document describes the guidelines for DPDK library-level statistics counter +support. This includes guidelines for turning library statistics on and off and +requirements for preventing ABI changes when implementing statistics. + + +Mechanism to allow the application to turn library statistics on and off +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each library that maintains statistics counters should provide a single build +time flag that decides whether the statistics counter collection is enabled or +not. This flag should be exposed as a variable within the DPDK configuration +file. When this flag is set, all the counters supported by current library are +collected for all the instances of every object type provided by the library. +When this flag is cleared, none of the counters supported by the current library +are collected for any instance of any object type provided by the library: + +.. code-block:: console + + # DPDK file config/common_linuxapp, config/common_bsdapp, etc. + CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n + +The default value for this DPDK configuration file variable (either "yes" or +"no") is decided by each library. + + +Prevention of ABI changes due to library statistics support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The layout of data structures and prototype of functions that are part of the +library API should not be affected by whether the collection of statistics +counters is turned on or off for the current library. In practical terms, this +means that space should always be allocated in the API data structures for +statistics counters and the statistics related API functions are always built +into the code, regardless of whether the statistics counter collection is turned +on or off for the current library. + +When the collection of statistics counters for the current library is turned +off, the counters retrieved through the statistics related API functions should +have a default value of zero. + + +Motivation to allow the application to turn library statistics on and off +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is highly recommended that each library provides statistics counters to allow +an application to monitor the library-level run-time events. Typical counters +are: number of packets received/dropped/transmitted, number of buffers +allocated/freed, number of occurrences for specific events, etc. + +However, the resources consumed for library-level statistics counter collection +have to be spent out of the application budget and the counters collected by +some libraries might not be relevant to the current application. In order to +avoid any unwanted waste of resources and/or performance impacts, the +application should decide at build time whether the collection of library-level +statistics counters should be turned on or off for each library individually. + +Library-level statistics counters can be relevant or not for specific +applications: + +* For Application A, counters maintained by Library X are always relevant and + the application needs to use them to implement certain features, such as traffic + accounting, logging, application-level statistics, etc. In this case, + the application requires that collection of statistics counters for Library X is + always turned on. + +* For Application B, counters maintained by Library X are only useful during the + application debug stage and are not relevant once debug phase is over. In this + case, the application may decide to turn on the collection of Library X + statistics counters during the debug phase and at a later stage turn them off. + +* For Application C, counters maintained by Library X are not relevant at all. + It might be that the application maintains its own set of statistics counters + that monitor a different set of run-time events (e.g. number of connection + requests, number of active users, etc). It might also be that the application + uses multiple libraries (Library X, Library Y, etc) and it is interested in the + statistics counters of Library Y, but not in those of Library X. In this case, + the application may decide to turn the collection of statistics counters off for + Library X and on for Library Y. + +The statistics collection consumes a certain amount of CPU resources (cycles, +cache bandwidth, memory bandwidth, etc) that depends on: + +* Number of libraries used by the current application that have statistics + counters collection turned on. + +* Number of statistics counters maintained by each library per object type + instance (e.g. per port, table, pipeline, thread, etc). + +* Number of instances created for each object type supported by each library. + +* Complexity of the statistics logic collection for each counter: when only + some occurrences of a specific event are valid, additional logic is typically + needed to decide whether the current occurrence of the event should be counted + or not. For example, in the event of packet reception, when only TCP packets + with destination port within a certain range should be recorded, conditional + branches are usually required. When processing a burst of packets that have been + validated for header integrity, counting the number of bits set in a bitmask + might be needed. diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst new file mode 100644 index 00000000..ba5c4dec --- /dev/null +++ b/doc/guides/contributing/documentation.rst @@ -0,0 +1,752 @@ +.. _doc_guidelines: + +DPDK Documentation Guidelines +============================= + +This document outlines the guidelines for writing the DPDK Guides and API documentation in RST and Doxygen format. + +It also explains the structure of the DPDK documentation and shows how to build the Html and PDF versions of the documents. + + +Structure of the Documentation +------------------------------ + +The DPDK source code repository contains input files to build the API documentation and User Guides. + +The main directories that contain files related to documentation are shown below:: + + lib + |-- librte_acl + |-- librte_cfgfile + |-- librte_cmdline + |-- librte_compat + |-- librte_eal + | |-- ... + ... + doc + |-- api + +-- guides + |-- freebsd_gsg + |-- linux_gsg + |-- prog_guide + |-- sample_app_ug + |-- guidelines + |-- testpmd_app_ug + |-- rel_notes + |-- nics + |-- xen + |-- ... + + +The API documentation is built from `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ comments in the header files. +These files are mainly in the ``lib/librte_*`` directories although some of the Poll Mode Drivers in ``drivers/net`` +are also documented with Doxygen. + +The configuration files that are used to control the Doxygen output are in the ``doc/api`` directory. + +The user guides such as *The Programmers Guide* and the *FreeBSD* and *Linux Getting Started* Guides are generated +from RST markup text files using the `Sphinx <http://sphinx-doc.org/index.html>`_ Documentation Generator. + +These files are included in the ``doc/guides/`` directory. +The output is controlled by the ``doc/guides/conf.py`` file. + + +Role of the Documentation +------------------------- + +The following items outline the roles of the different parts of the documentation and when they need to be updated or +added to by the developer. + +* **Release Notes** + + The Release Notes document which features have been added in the current and previous releases of DPDK and highlight + any known issues. + The Releases Notes also contain notifications of features that will change ABI compatibility in the next major release. + + Developers should include updates to the Release Notes with patch sets that relate to any of the following sections: + + * New Features + * Resolved Issues (see below) + * Known Issues + * API Changes + * ABI Changes + * Shared Library Versions + + Resolved Issues should only include issues from previous releases that have been resolved in the current release. + Issues that are introduced and then fixed within a release cycle do not have to be included here. + + Refer to the Release Notes from the previous DPDK release for the correct format of each section. + + +* **API documentation** + + The API documentation explains how to use the public DPDK functions. + The `API index page <http://dpdk.org/doc/api/>`_ shows the generated API documentation with related groups of functions. + + The API documentation should be updated via Doxygen comments when new functions are added. + +* **Getting Started Guides** + + The Getting Started Guides show how to install and configure DPDK and how to run DPDK based applications on different OSes. + + A Getting Started Guide should be added when DPDK is ported to a new OS. + +* **The Programmers Guide** + + The Programmers Guide explains how the API components of DPDK such as the EAL, Memzone, Rings and the Hash Library work. + It also explains how some higher level functionality such as Packet Distributor, Packet Framework and KNI work. + It also shows the build system and explains how to add applications. + + The Programmers Guide should be expanded when new functionality is added to DPDK. + +* **App Guides** + + The app guides document the DPDK applications in the ``app`` directory such as ``testpmd``. + + The app guides should be updated if functionality is changed or added. + +* **Sample App Guides** + + The sample app guides document the DPDK example applications in the examples directory. + Generally they demonstrate a major feature such as L2 or L3 Forwarding, Multi Process or Power Management. + They explain the purpose of the sample application, how to run it and step through some of the code to explain the + major functionality. + + A new sample application should be accompanied by a new sample app guide. + The guide for the Skeleton Forwarding app is a good starting reference. + +* **Network Interface Controller Drivers** + + The NIC Drivers document explains the features of the individual Poll Mode Drivers, such as software requirements, + configuration and initialization. + + New documentation should be added for new Poll Mode Drivers. + +* **Guidelines** + + The guideline documents record community process, expectations and design directions. + + They can be extended, amended or discussed by submitting a patch and getting community approval. + + +Building the Documentation +-------------------------- + +Dependencies +~~~~~~~~~~~~ + + +The following dependencies must be installed to build the documentation: + +* Doxygen. + +* Sphinx (also called python-sphinx). + +* TexLive (at least TexLive-core and the extra Latex support). + +* Inkscape. + +`Doxygen`_ generates documentation from commented source code. +It can be installed as follows: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install doxygen + + # Red Hat/Fedora. + sudo yum -y install doxygen + +`Sphinx`_ is a Python documentation tool for converting RST files to Html or to PDF (via LaTeX). +For full support with figure and table captioning the latest version of Sphinx can be installed as follows: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install python-pip + sudo pip install --upgrade sphinx + + # Red Hat/Fedora. + sudo yum -y install python-pip + sudo pip install --upgrade sphinx + +For further information on getting started with Sphinx see the `Sphinx Tutorial <http://sphinx-doc.org/tutorial.html>`_. + +.. Note:: + + To get full support for Figure and Table numbering it is best to install Sphinx 1.3.1 or later. + + +`Inkscape`_ is a vector based graphics program which is used to create SVG images and also to convert SVG images to PDF images. +It can be installed as follows: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install inkscape + + # Red Hat/Fedora. + sudo yum -y install inkscape + +`TexLive <http://www.tug.org/texlive/>`_ is an installation package for Tex/LaTeX. +It is used to generate the PDF versions of the documentation. +The main required packages can be installed as follows: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install texlive-latex-extra + + # Red Hat/Fedora, selective install. + sudo yum -y install texlive-collection-latexextra + + +Build commands +~~~~~~~~~~~~~~ + +The documentation is built using the standard DPDK build system. +Some examples are shown below: + +* Generate all the documentation targets:: + + make doc + +* Generate the Doxygen API documentation in Html:: + + make doc-api-html + +* Generate the guides documentation in Html:: + + make doc-guides-html + +* Generate the guides documentation in Pdf:: + + make doc-guides-pdf + +The output of these commands is generated in the ``build`` directory:: + + build/doc + |-- html + | |-- api + | +-- guides + | + +-- pdf + +-- guides + + +.. Note:: + + Make sure to fix any Sphinx or Doxygen warnings when adding or updating documentation. + +The documentation output files can be removed as follows:: + + make doc-clean + + +Document Guidelines +------------------- + +Here are some guidelines in relation to the style of the documentation: + +* Document the obvious as well as the obscure since it won't always be obvious to the reader. + For example an instruction like "Set up 64 2MB Hugepages" is better when followed by a sample commandline or a link to + the appropriate section of the documentation. + +* Use American English spellings throughout. + This can be checked using the ``aspell`` utility:: + + aspell --lang=en_US --check doc/guides/sample_app_ug/mydoc.rst + + +RST Guidelines +-------------- + +The RST (reStructuredText) format is a plain text markup format that can be converted to Html, PDF or other formats. +It is most closely associated with Python but it can be used to document any language. +It is used in DPDK to document everything apart from the API. + +The Sphinx documentation contains a very useful `RST Primer <http://sphinx-doc.org/rest.html#rst-primer>`_ which is a +good place to learn the minimal set of syntax required to format a document. + +The official `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ website contains the specification for the +RST format and also examples of how to use it. +However, for most developers the RST Primer is a better resource. + +The most common guidelines for writing RST text are detailed in the +`Documenting Python <https://docs.python.org/devguide/documenting.html>`_ guidelines. +The additional guidelines below reiterate or expand upon those guidelines. + + +Line Length +~~~~~~~~~~~ + +* The recommended style for the DPDK documentation is to put sentences on separate lines. + This allows for easier reviewing of patches. + Multiple sentences which are not separated by a blank line are joined automatically into paragraphs, for example:: + + Here is an example sentence. + Long sentences over the limit shown below can be wrapped onto + a new line. + These three sentences will be joined into the same paragraph. + + This is a new paragraph, since it is separated from the + previous paragraph by a blank line. + + This would be rendered as follows: + + *Here is an example sentence. + Long sentences over the limit shown below can be wrapped onto + a new line. + These three sentences will be joined into the same paragraph.* + + *This is a new paragraph, since it is separated from the + previous paragraph by a blank line.* + + +* Long sentences should be wrapped at 120 characters +/- 10 characters. They should be wrapped at words. + +* Lines in literal blocks must by less than 80 characters since they aren't wrapped by the document formatters + and can exceed the page width in PDF documents. + + +Whitespace +~~~~~~~~~~ + +* Standard RST indentation is 3 spaces. + Code can be indented 4 spaces, especially if it is copied from source files. + +* No tabs. + Convert tabs in embedded code to 4 or 8 spaces. + +* No trailing whitespace. + +* Add 2 blank lines before each section header. + +* Add 1 blank line after each section header. + +* Add 1 blank line between each line of a list. + + +Section Headers +~~~~~~~~~~~~~~~ + +* Section headers should use the use the following underline formats:: + + Level 1 Heading + =============== + + + Level 2 Heading + --------------- + + + Level 3 Heading + ~~~~~~~~~~~~~~~ + + + Level 4 Heading + ^^^^^^^^^^^^^^^ + + +* Level 4 headings should be used sparingly. + +* The underlines should match the length of the text. + +* In general, the heading should be less than 80 characters, for conciseness. + +* As noted above: + + * Add 2 blank lines before each section header. + + * Add 1 blank line after each section header. + + +Lists +~~~~~ + +* Bullet lists should be formatted with a leading ``*`` as follows:: + + * Item one. + + * Item two is a long line that is wrapped and then indented to match + the start of the previous line. + + * One space character between the bullet and the text is preferred. + +* Numbered lists can be formatted with a leading number but the preference is to use ``#.`` which will give automatic numbering. + This is more convenient when adding or removing items:: + + #. Item one. + + #. Item two is a long line that is wrapped and then indented + to match the start of the e first line. + + #. Item two is a long line that is wrapped and then indented to match + the start of the previous line. + +* Definition lists can be written with or without a bullet:: + + * Item one. + + Some text about item one. + + * Item two. + + Some text about item two. + +* All lists, and sub-lists, must be separated from the preceding text by a blank line. + This is a syntax requirement. + +* All list items should be separated by a blank line for readability. + + +Code and Literal block sections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Inline text that is required to be rendered with a fixed width font should be enclosed in backquotes like this: + \`\`text\`\`, so that it appears like this: ``text``. + +* Fixed width, literal blocks of texts should be indented at least 3 spaces and prefixed with ``::`` like this:: + + Here is some fixed width text:: + + 0x0001 0x0001 0x00FF 0x00FF + +* It is also possible to specify an encoding for a literal block using the ``.. code-block::`` directive so that syntax + highlighting can be applied. + Examples of supported highlighting are:: + + .. code-block:: console + .. code-block:: c + .. code-block:: python + .. code-block:: diff + .. code-block:: none + + That can be applied as follows:: + + .. code-block:: c + + #include<stdio.h> + + int main() { + + printf("Hello World\n"); + + return 0; + } + + Which would be rendered as: + + .. code-block:: c + + #include<stdio.h> + + int main() { + + printf("Hello World\n"); + + return 0; + } + + +* The default encoding for a literal block using the simplified ``::`` + directive is ``none``. + +* Lines in literal blocks must be less than 80 characters since they can exceed the page width when converted to PDF documentation. + For long literal lines that exceed that limit try to wrap the text at sensible locations. + For example a long command line could be documented like this and still work if copied directly from the docs:: + + build/app/testpmd -c7 -n3 --vdev=eth_pcap0,iface=eth0 \ + --vdev=eth_pcap1,iface=eth1 \ + -- -i --nb-cores=2 --nb-ports=2 \ + --total-num-mbufs=2048 + +* Long lines that cannot be wrapped, such as application output, should be truncated to be less than 80 characters. + + +Images +~~~~~~ + +* All images should be in SVG scalar graphics format. + They should be true SVG XML files and should not include binary formats embedded in a SVG wrapper. + +* The DPDK documentation contains some legacy images in PNG format. + These will be converted to SVG in time. + +* `Inkscape <http://inkscape.org>`_ is the recommended graphics editor for creating the images. + Use some of the older images in ``doc/guides/prog_guide/img/`` as a template, for example ``mbuf1.svg`` + or ``ring-enqueue.svg``. + +* The SVG images should include a copyright notice, as an XML comment. + +* Images in the documentation should be formatted as follows: + + * The image should be preceded by a label in the format ``.. _figure_XXXX:`` with a leading underscore and + where ``XXXX`` is a unique descriptive name. + + * Images should be included using the ``.. figure::`` directive and the file type should be set to ``*`` (not ``.svg``). + This allows the format of the image to be changed if required, without updating the documentation. + + * Images must have a caption as part of the ``.. figure::`` directive. + +* Here is an example of the previous three guidelines:: + + .. _figure_mempool: + + .. figure:: img/mempool.* + + A mempool in memory with its associated ring. + +.. _mock_label: + +* Images can then be linked to using the ``:numref:`` directive:: + + The mempool layout is shown in :numref:`figure_mempool`. + + This would be rendered as: *The mempool layout is shown in* :ref:`Fig 6.3 <mock_label>`. + + **Note**: The ``:numref:`` directive requires Sphinx 1.3.1 or later. + With earlier versions it will still be rendered as a link but won't have an automatically generated number. + +* The caption of the image can be generated, with a link, using the ``:ref:`` directive:: + + :ref:`figure_mempool` + + This would be rendered as: *A mempool in memory with its associated ring.* + +Tables +~~~~~~ + +* RST tables should be used sparingly. + They are hard to format and to edit, they are often rendered incorrectly in PDF format, and the same information + can usually be shown just as clearly with a definition or bullet list. + +* Tables in the documentation should be formatted as follows: + + * The table should be preceded by a label in the format ``.. _table_XXXX:`` with a leading underscore and where + ``XXXX`` is a unique descriptive name. + + * Tables should be included using the ``.. table::`` directive and must have a caption. + +* Here is an example of the previous two guidelines:: + + .. _table_qos_pipes: + + .. table:: Sample configuration for QOS pipes. + + +----------+----------+----------+ + | Header 1 | Header 2 | Header 3 | + | | | | + +==========+==========+==========+ + | Text | Text | Text | + +----------+----------+----------+ + | ... | ... | ... | + +----------+----------+----------+ + +* Tables can be linked to using the ``:numref:`` and ``:ref:`` directives, as shown in the previous section for images. + For example:: + + The QOS configuration is shown in :numref:`table_qos_pipes`. + +* Tables should not include merged cells since they are not supported by the PDF renderer. + + +.. _links: + +Hyperlinks +~~~~~~~~~~ + +* Links to external websites can be plain URLs. + The following is rendered as http://dpdk.org:: + + http://dpdk.org + +* They can contain alternative text. + The following is rendered as `Check out DPDK <http://dpdk.org>`_:: + + `Check out DPDK <http://dpdk.org>`_ + +* An internal link can be generated by placing labels in the document with the format ``.. _label_name``. + +* The following links to the top of this section: :ref:`links`:: + + .. _links: + + Hyperlinks + ~~~~~~~~~~ + + * The following links to the top of this section: :ref:`links`: + +.. Note:: + + The label must have a leading underscore but the reference to it must omit it. + This is a frequent cause of errors and warnings. + +* The use of a label is preferred since it works across files and will still work if the header text changes. + + +.. _doxygen_guidelines: + +Doxygen Guidelines +------------------ + +The DPDK API is documented using Doxygen comment annotations in the header files. +Doxygen is a very powerful tool, it is extremely configurable and with a little effort can be used to create expressive documents. +See the `Doxygen website <http://www.stack.nl/~dimitri/doxygen/>`_ for full details on how to use it. + +The following are some guidelines for use of Doxygen in the DPDK API documentation: + +* New libraries that are documented with Doxygen should be added to the Doxygen configuration file: ``doc/api/doxy-api.conf``. + It is only required to add the directory that contains the files. + It isn't necessary to explicitly name each file since the configuration matches all ``rte_*.h`` files in the directory. + +* Use proper capitalization and punctuation in the Doxygen comments since they will become sentences in the documentation. + This in particular applies to single line comments, which is the case the is most often forgotten. + +* Use ``@`` style Doxygen commands instead of ``\`` style commands. + +* Add a general description of each library at the head of the main header files: + + .. code-block:: c + + /** + * @file + * RTE Mempool. + * + * A memory pool is an allocator of fixed-size object. It is + * identified by its name, and uses a ring to store free objects. + * ... + */ + +* Document the purpose of a function, the parameters used and the return + value: + + .. code-block:: c + + /** + * Attach a new Ethernet device specified by arguments. + * + * @param devargs + * A pointer to a strings array describing the new device + * to be attached. The strings should be a pci address like + * `0000:01:00.0` or **virtual** device name like `eth_pcap0`. + * @param port_id + * A pointer to a port identifier actually attached. + * + * @return + * 0 on success and port_id is filled, negative on error. + */ + int rte_eth_dev_attach(const char *devargs, uint8_t *port_id); + +* Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists. + For example the second line in the ``devargs`` parameter in the previous example will be rendered as: + + The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``eth_pcap0``. + +* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter. + +* Add an empty line between the function description, the ``@params`` and ``@return`` for readability. + +* Place the ``@params`` description on separate line and indent it by 2 spaces. + (It would be better to use no indentation since this is more common and also because checkpatch complains about leading + whitespace in comments. + However this is the convention used in the existing DPDK code.) + +* Documented functions can be linked to simply by adding ``()`` to the function name: + + .. code-block:: c + + /** + * The functions exported by the application Ethernet API to setup + * a device designated by its port identifier must be invoked in + * the following order: + * - rte_eth_dev_configure() + * - rte_eth_tx_queue_setup() + * - rte_eth_rx_queue_setup() + * - rte_eth_dev_start() + */ + + In the API documentation the functions will be rendered as links, see the + `online section of the rte_ethdev.h docs <http://dpdk.org/doc/api/rte__ethdev_8h.html>`_ that contains the above text. + +* The ``@see`` keyword can be used to create a *see also* link to another file or library. + This directive should be placed on one line at the bottom of the documentation section. + + .. code-block:: c + + /** + * ... + * + * Some text that references mempools. + * + * @see eal_memzone.c + */ + +* Doxygen supports two types of comments for documenting variables, constants and members: prefix and postfix: + + .. code-block:: c + + /** This is a prefix comment. */ + #define RTE_FOO_ERROR 0x023. + + #define RTE_BAR_ERROR 0x024. /**< This is a postfix comment. */ + +* Postfix comments are preferred for struct members and constants if they can be documented in the same way: + + .. code-block:: c + + struct rte_eth_stats { + uint64_t ipackets; /**< Total number of received packets. */ + uint64_t opackets; /**< Total number of transmitted packets.*/ + uint64_t ibytes; /**< Total number of received bytes. */ + uint64_t obytes; /**< Total number of transmitted bytes. */ + uint64_t imissed; /**< Total of RX missed packets. */ + uint64_t ibadcrc; /**< Total of RX packets with CRC error. */ + uint64_t ibadlen; /**< Total of RX packets with bad length. */ + } + + Note: postfix comments should be aligned with spaces not tabs in accordance + with the :ref:`coding_style`. + +* If a single comment type can't be used, due to line length limitations then + prefix comments should be preferred. + For example this section of the code contains prefix comments, postfix comments on the same line and postfix + comments on a separate line: + + .. code-block:: c + + /** Number of elements in the elt_pa array. */ + uint32_t pg_num __rte_cache_aligned; + uint32_t pg_shift; /**< LOG2 of the physical pages. */ + uintptr_t pg_mask; /**< Physical page mask value. */ + uintptr_t elt_va_start; + /**< Virtual address of the first mempool object. */ + uintptr_t elt_va_end; + /**< Virtual address of the <size + 1> mempool object. */ + phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT]; + /**< Array of physical page addresses for the mempool buffer. */ + + This doesn't have an effect on the rendered documentation but it is confusing for the developer reading the code. + It this case it would be clearer to use prefix comments throughout: + + .. code-block:: c + + /** Number of elements in the elt_pa array. */ + uint32_t pg_num __rte_cache_aligned; + /** LOG2 of the physical pages. */ + uint32_t pg_shift; + /** Physical page mask value. */ + uintptr_t pg_mask; + /** Virtual address of the first mempool object. */ + uintptr_t elt_va_start; + /** Virtual address of the <size + 1> mempool object. */ + uintptr_t elt_va_end; + /** Array of physical page addresses for the mempool buffer. */ + phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT]; + +* Check for Doxygen warnings in new code by checking the API documentation build:: + + make doc-api-html >/dev/null + +* Read the rendered section of the documentation that you have added for correctness, clarity and consistency + with the surrounding text. diff --git a/doc/guides/contributing/img/patch_cheatsheet.svg b/doc/guides/contributing/img/patch_cheatsheet.svg new file mode 100644 index 00000000..85225923 --- /dev/null +++ b/doc/guides/contributing/img/patch_cheatsheet.svg @@ -0,0 +1,1484 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + version="1.1" + width="210mm" + height="297mm" + id="svg2985" + inkscape:version="0.48.4 r9939" + sodipodi:docname="patch_cheatsheet.svg"> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1184" + inkscape:window-height="1822" + id="namedview274" + showgrid="false" + inkscape:zoom="1.2685914" + inkscape:cx="289.93958" + inkscape:cy="509.84194" + inkscape:window-x="0" + inkscape:window-y="19" + inkscape:window-maximized="0" + inkscape:current-layer="g3272" /> + <defs + id="defs3"> + <linearGradient + x1="748.62079" + y1="-220.1862" + x2="849.99768" + y2="-220.1862" + id="SVGID_1_" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop16" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop18" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop20" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop22" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <linearGradient + x1="749.70099" + y1="-220.1864" + x2="848.91772" + y2="-220.1864" + id="SVGID_2_" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop27" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop29" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop31" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop33" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <linearGradient + x1="760.65948" + y1="-220.1864" + x2="899.29993" + y2="-220.1864" + id="SVGID_3_" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop40" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop42" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop44" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop46" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <linearGradient + x1="761.73969" + y1="-220.1864" + x2="898.21973" + y2="-220.1864" + id="SVGID_4_" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop51" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop53" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop55" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop57" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <linearGradient + x1="716.09821" + y1="-220.18649" + x2="874.64807" + y2="-220.18649" + id="SVGID_5_" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop64" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop66" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop68" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop70" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <linearGradient + x1="717.1781" + y1="-220.1864" + x2="873.56799" + y2="-220.1864" + id="SVGID_6_" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop75" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop77" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop79" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop81" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + </defs> + <metadata + id="metadata4"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + id="layer1"> + <switch + transform="matrix(0.46699142,0,0,0.41996015,9.9845875,-77.168919)" + id="switch3"> + <g + id="g7"> + <g + id="g9"> + <g + id="g11"> + <g + id="g13"> + <linearGradient + x1="748.62079" + y1="-220.1862" + x2="849.99768" + y2="-220.1862" + id="linearGradient3172" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop3174" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop3176" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop3178" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop3180" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <path + d="m 137.8,342.7 c -1.4,0 -2.5,-0.8 -3,-2.2 -1.2,-3.3 2.1,-4.5 3.3,-5 l 43.3,-17.7 c 5,-1.9 8.9,-5.6 11.1,-10.4 2.2,-4.8 2.4,-10.2 0.5,-15.2 -2.9,-7.7 -10.4,-12.9 -18.6,-12.9 -2.4,0 -4.7,0.4 -7,1.3 l -63.2,22.3 c -0.8,0.3 -1.8,0.6 -2.7,0.6 -1.4,0 -2.5,-0.8 -3,-2.2 -1.2,-3.3 2.1,-4.5 3.3,-5 L 164,271.5 c 3.4,-1.3 6.8,-1.9 10.4,-1.9 12.3,0 23.4,7.7 27.7,19.2 2.8,7.4 2.5,15.4 -0.8,22.6 -3.3,7.2 -9.1,12.7 -16.5,15.5 L 140.5,342 c -0.7,0.3 -1.7,0.7 -2.7,0.7 z" + id="path24" + style="fill:url(#SVGID_1_)" + inkscape:connector-curvature="0" /> + <linearGradient + x1="749.70099" + y1="-220.1864" + x2="848.91772" + y2="-220.1864" + id="linearGradient3183" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop3185" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop3187" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop3189" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop3191" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <path + d="M 184.5,325.9 140.2,341 c -1.9,0.7 -3.6,1 -4.4,-0.9 -0.7,-1.9 0.7,-2.8 2.7,-3.6 l 43.3,-17.7 c 10.8,-4.1 16.3,-16.2 12.3,-27 -4.1,-10.8 -16.2,-16.3 -27,-12.3 l -63.2,22.2 c -1.9,0.7 -3.6,1 -4.4,-0.9 -0.7,-1.9 0.7,-2.8 2.7,-3.6 l 62.2,-24.8 c 14.7,-5.5 31.2,2 36.7,16.7 5.5,14.8 -1.9,31.2 -16.6,36.8 z" + id="path35" + style="fill:url(#SVGID_2_)" + inkscape:connector-curvature="0" /> + </g> + <g + id="g37"> + <linearGradient + x1="760.65948" + y1="-220.1864" + x2="899.29993" + y2="-220.1864" + id="linearGradient3195" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop3197" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop3199" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop3201" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop3203" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <path + d="m 147.5,391.7 c -1.4,0 -2.5,-0.8 -3,-2.2 -1.2,-3.3 2.1,-4.5 3.3,-5 l 50.9,-20.6 c 35.7,-13.4 53.9,-53.4 40.5,-89.1 C 229.1,248 203.1,230 174.4,230 c -8.3,0 -16.4,1.5 -24.2,4.4 l -51.9,18 c -0.8,0.3 -1.8,0.6 -2.7,0.6 -1.4,0 -2.5,-0.8 -3,-2.2 -0.6,-1.6 0,-2.7 0.6,-3.4 0.7,-0.8 1.8,-1.2 2.8,-1.6 l 50.9,-20.6 c 8.9,-3.3 18.2,-5 27.7,-5 32.7,0 62.4,20.6 73.9,51.2 15.3,40.7 -5.4,86.3 -46.1,101.6 l -51.9,18 c -1,0.3 -2,0.7 -3,0.7 z" + id="path48" + style="fill:url(#SVGID_3_)" + inkscape:connector-curvature="0" /> + <linearGradient + x1="761.73969" + y1="-220.1864" + x2="898.21973" + y2="-220.1864" + id="linearGradient3206" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop3208" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop3210" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop3212" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop3214" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <path + d="m 201.8,372 -51.9,18 c -1.9,0.7 -3.6,1 -4.4,-0.9 -0.7,-1.9 0.7,-2.8 2.7,-3.6 l 50.9,-20.6 c 36.3,-13.6 54.7,-54.2 41.1,-90.5 -13.6,-36.3 -54.2,-54.7 -90.5,-41.1 l -51.9,18 c -1.9,0.7 -3.6,1 -4.4,-0.9 -0.7,-1.9 0.7,-2.8 2.7,-3.6 L 147,226.2 c 40.2,-15.1 85.1,5.3 100.2,45.5 15.1,40.3 -5.3,85.3 -45.4,100.3 z" + id="path59" + style="fill:url(#SVGID_4_)" + inkscape:connector-curvature="0" /> + </g> + <g + id="g61"> + <linearGradient + x1="716.09821" + y1="-220.18649" + x2="874.64807" + y2="-220.18649" + id="linearGradient3218" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop3220" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop3222" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop3224" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop3226" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <path + d="m 97.1,384.3 c -1.4,0 -2.5,-0.8 -3,-2.2 -1.2,-3.3 2.1,-4.5 3.3,-5 L 190,340.9 c 23,-8.6 34.7,-34.4 26.1,-57.3 -6.5,-17.3 -23.3,-28.9 -41.7,-28.9 -5.3,0 -10.6,1 -15.6,2.8 l -83.9,30 c -0.8,0.3 -1.8,0.6 -2.7,0.6 -1.4,0 -2.5,-0.8 -3,-2.2 -1.2,-3.3 2.1,-4.5 3.3,-5 l 82.9,-32.6 c 6.1,-2.3 12.5,-3.5 19,-3.5 22.5,0 42.9,14.1 50.8,35.2 5.1,13.5 4.6,28.3 -1.4,41.5 -6,13.2 -16.8,23.3 -30.3,28.4 l -93.6,33.7 c -0.8,0.3 -1.8,0.7 -2.8,0.7 z" + id="path72" + style="fill:url(#SVGID_5_)" + inkscape:connector-curvature="0" /> + <linearGradient + x1="717.1781" + y1="-220.1864" + x2="873.56799" + y2="-220.1864" + id="linearGradient3229" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.9362,-0.3514,0.3514,0.9362,-516.294,793.6274)"> + <stop + id="stop3231" + style="stop-color:#f04e23;stop-opacity:1" + offset="0.15000001" /> + <stop + id="stop3233" + style="stop-color:#782b90;stop-opacity:1" + offset="0.70130002" /> + <stop + id="stop3235" + style="stop-color:#8a2890;stop-opacity:1" + offset="0.8387" /> + <stop + id="stop3237" + style="stop-color:#9c258f;stop-opacity:1" + offset="1" /> + </linearGradient> + <path + d="m 193.1,348.9 -93.6,33.7 c -1.9,0.7 -3.6,1 -4.4,-0.9 -0.7,-1.9 0.7,-2.8 2.7,-3.6 l 92.7,-36.2 C 214,333.1 226,306.7 217.2,283.2 208.4,259.7 182,247.7 158.5,256.5 l -83.8,30 c -1.9,0.7 -3.6,1 -4.4,-0.9 -0.8,-1.9 0.7,-2.8 2.7,-3.6 l 82.9,-32.6 c 27.4,-10.3 58.1,3.6 68.4,31.1 10.2,27.5 -3.7,58.2 -31.2,68.4 z" + id="path83" + style="fill:url(#SVGID_6_)" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + id="g85"> + <g + id="g87"> + <path + d="m 300.7,235.7 h 33.5 c 30.7,0 51.8,19.4 51.8,47.5 0,28.1 -21.2,47.5 -51.8,47.5 h -33.5 v -95 z m 32.2,81.3 c 23.7,0 37.9,-13 37.9,-33.8 0,-20.8 -14.1,-33.8 -37.9,-33.8 H 315.7 V 317 h 17.2 z" + id="path89" + style="fill:#00233b" + inkscape:connector-curvature="0" /> + <path + d="m 419.8,235.7 h 40.8 c 20.1,0 31.8,11.5 31.8,27.5 0,16.3 -11.7,28.2 -31.8,28.2 h -25.9 v 39.2 h -14.9 v -94.9 z m 39.7,42 c 11.1,0 17.9,-5.2 17.9,-14.2 0,-9.2 -6.8,-14.1 -17.9,-14.1 h -24.7 v 28.4 h 24.7 z" + id="path91" + style="fill:#00233b" + inkscape:connector-curvature="0" /> + <path + d="m 523.2,235.7 h 33.5 c 30.7,0 51.8,19.4 51.8,47.5 0,28.1 -21.2,47.5 -51.8,47.5 h -33.5 v -95 z m 32.2,81.3 c 23.7,0 37.9,-13 37.9,-33.8 0,-20.8 -14.1,-33.8 -37.9,-33.8 H 538.2 V 317 h 17.2 z" + id="path93" + style="fill:#00233b" + inkscape:connector-curvature="0" /> + <path + d="m 642.4,235.7 h 14.9 v 38.8 l 38.9,-38.8 h 19.1 l -44,43.4 51,51.6 h -20.4 l -44.8,-45.6 v 45.6 h -14.9 v -95 z" + id="path95" + style="fill:#00233b" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + id="g97"> + <path + d="m 300.3,360 h 6.3 c 5.7,0 9.7,3.6 9.7,8.9 0,5.3 -4,8.9 -9.7,8.9 h -6.3 V 360 z m 6,15.2 c 4.4,0 7.1,-2.4 7.1,-6.3 0,-3.9 -2.6,-6.3 -7.1,-6.3 H 303 v 12.7 h 3.3 z" + id="path99" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 324.6,359.9 h 2.7 l 7.8,17.9 h -3 l -1.9,-4.4 h -8.4 l -1.9,4.4 h -3 l 7.7,-17.9 z m 4.6,11 -3.3,-7.5 -3.3,7.5 h 6.6 z" + id="path101" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 348.3,360 v 2.6 h -5.9 v 15.2 h -2.8 v -15.2 h -5.9 V 360 h 14.6 z" + id="path103" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 354.7,359.9 h 2.7 l 7.8,17.9 h -3 l -1.9,-4.4 h -8.4 l -1.9,4.4 h -3 l 7.7,-17.9 z m 4.6,11 -3.3,-7.5 -3.3,7.5 h 6.6 z" + id="path105" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 380.4,360 h 7.7 c 3.8,0 5.9,2.2 5.9,5.2 0,3.1 -2.2,5.3 -5.9,5.3 h -4.9 v 7.3 h -2.8 V 360 z m 7.4,7.8 c 2.1,0 3.4,-1 3.4,-2.7 0,-1.7 -1.3,-2.6 -3.4,-2.6 h -4.6 v 5.3 h 4.6 z" + id="path107" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 397,360 h 2.8 v 15.2 h 9.5 v 2.6 H 397 V 360 z" + id="path109" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 418.1,359.9 h 2.7 l 7.8,17.9 h -3 l -1.9,-4.4 h -8.4 l -1.9,4.4 h -3 l 7.7,-17.9 z m 4.6,11 -3.3,-7.5 -3.3,7.5 h 6.6 z" + id="path111" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 431.1,360 h 2.4 l 10,12.9 V 360 h 2.7 v 17.8 H 444 l -10.1,-12.9 v 12.9 h -2.7 V 360 z" + id="path113" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 450.5,360 h 12.7 v 2.6 h -9.9 v 4.4 h 8 v 2.6 h -8 v 5.6 h 10.2 v 2.6 h -13 V 360 z" + id="path115" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 479.3,360 h 6.3 c 5.7,0 9.7,3.6 9.7,8.9 0,5.3 -4,8.9 -9.7,8.9 h -6.3 V 360 z m 6,15.2 c 4.4,0 7.1,-2.4 7.1,-6.3 0,-3.9 -2.6,-6.3 -7.1,-6.3 h -3.2 v 12.7 h 3.2 z" + id="path117" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 498.8,360 h 12.7 v 2.6 h -9.9 v 4.4 h 8 v 2.6 h -8 v 5.6 h 10.2 v 2.6 h -13 V 360 z" + id="path119" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 513.3,360 h 3.1 l 5.9,14 5.9,-14 h 3 l -7.6,17.9 H 521 L 513.3,360 z" + id="path121" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 533.9,360 h 12.7 v 2.6 h -9.9 v 4.4 h 8 v 2.6 h -8 v 5.6 h 10.2 v 2.6 h -13 V 360 z" + id="path123" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 549.9,360 h 2.8 v 15.2 h 9.5 v 2.6 H 549.9 V 360 z" + id="path125" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 563,368.9 c 0,-5.2 3.8,-9.2 9.1,-9.2 5.3,0 9.1,4 9.1,9.2 0,5.2 -3.9,9.2 -9.1,9.2 -5.2,0 -9.1,-4.1 -9.1,-9.2 z m 15.3,0 c 0,-3.8 -2.7,-6.6 -6.2,-6.6 -3.5,0 -6.2,2.8 -6.2,6.6 0,3.8 2.7,6.6 6.2,6.6 3.5,0 6.2,-2.9 6.2,-6.6 z" + id="path127" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 584.7,360 h 7.7 c 3.8,0 5.9,2.2 5.9,5.2 0,3.1 -2.2,5.3 -5.9,5.3 h -4.9 v 7.3 h -2.8 V 360 z m 7.5,7.8 c 2.1,0 3.4,-1 3.4,-2.7 0,-1.7 -1.3,-2.6 -3.4,-2.6 h -4.6 v 5.3 h 4.6 z" + id="path129" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 601.3,360 h 2.8 l 5.8,8 5.7,-8 h 2.8 v 17.8 h -2.8 v -13.5 l -5,6.7 H 609 l -5,-6.7 v 13.5 h -2.8 V 360 z" + id="path131" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 622.6,360 h 12.7 v 2.6 h -9.9 v 4.4 h 8 v 2.6 h -8 v 5.6 h 10.2 v 2.6 h -13 V 360 z" + id="path133" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 638.7,360 h 2.4 l 10,12.9 V 360 h 2.7 v 17.8 h -2.4 l -10.1,-12.9 v 12.9 h -2.7 V 360 z" + id="path135" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 671.3,360 v 2.6 h -5.9 v 15.2 h -2.8 v -15.2 h -5.9 V 360 h 14.6 z" + id="path137" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 685.5,360 h 2.8 v 7.3 l 7.3,-7.3 h 3.6 l -8.2,8.1 9.6,9.7 h -3.8 l -8.4,-8.5 v 8.5 h -2.8 V 360 z" + id="path139" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 702.8,360 h 2.8 v 17.8 h -2.8 V 360 z" + id="path141" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + <path + d="m 723.1,360 v 2.6 h -5.9 v 15.2 h -2.8 v -15.2 h -5.9 V 360 h 14.6 z" + id="path143" + style="fill:#f04e23" + inkscape:connector-curvature="0" /> + </g> + </g> + </g> + </switch> + <g + transform="matrix(0.89980358,0,0,0.89980358,45.57817,-2.8793563)" + id="g4009"> + <text + x="325.02054" + y="107.5126" + id="text3212" + xml:space="preserve" + style="font-size:43.11383057px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%" + transform="scale(1.193782,0.83767389)"><tspan + x="325.02054" + y="107.5126" + id="tspan3214">CHEATSHEET</tspan></text> + <text + x="386.51117" + y="58.178116" + transform="scale(1.0054999,0.99453018)" + id="text3212-1" + xml:space="preserve" + style="font-size:42.11373901px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="386.51117" + y="58.178116" + id="tspan3214-7">PATCH SUBMIT</tspan></text> + </g> + <rect + width="714.94495" + height="88.618027" + rx="20.780111" + ry="15.96909" + x="14.574773" + y="7.0045133" + id="rect3239" + style="fill:none;stroke:#00233b;stroke-width:0.87678075;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <rect + width="713.28113" + height="887.29156" + rx="17.656931" + ry="17.280584" + x="15.406689" + y="104.73515" + id="rect3239-0" + style="fill:none;stroke:#00233b;stroke-width:1.00973284;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <rect + width="694.94904" + height="381.31" + rx="9.4761629" + ry="9.0904856" + x="24.336016" + y="601.75836" + id="rect3239-0-9-4" + style="fill:none;stroke:#00233b;stroke-width:1.02322531;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + d="m 386.3921,327.23442 323.14298,0" + id="path4088" + style="fill:none;stroke:#00233b;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + inkscape:connector-curvature="0" /> + <text + x="396.18015" + y="314.45731" + id="text4090" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="396.18015" + y="314.45731" + id="tspan4092" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Patch Pre-Checks</tspan></text> + <text + x="43.44949" + y="147.32129" + id="text4090-4" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="43.44949" + y="147.32129" + id="tspan4092-3" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Commit Pre-Checks</tspan></text> + <text + x="397.1235" + y="144.8549" + id="text4090-4-3" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="397.1235" + y="144.8549" + id="tspan4092-3-3" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Bugfix?</tspan></text> + <text + x="41.215897" + y="634.38617" + id="text4090-1" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="41.215897" + y="634.38617" + id="tspan4092-38" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Git send-email </tspan></text> + <path + d="m 31.232443,642.80575 376.113467,0" + id="path4088-7" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <rect + width="342.13785" + height="230.74609" + rx="10.411126" + ry="10.411126" + x="25.418407" + y="114.92036" + id="rect3239-0-9-4-2" + style="fill:none;stroke:#00233b;stroke-width:0.93674862;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + x="43.44949" + y="385.8045" + id="text4090-86" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="43.44949" + y="385.8045" + id="tspan4092-5" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Compile Pre-Checks</tspan></text> + <g + transform="translate(352.00486,-348.25973)" + id="g3295"> + <text + x="43.87738" + y="568.03088" + id="text4090-8-14" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="43.87738" + y="568.03088" + id="tspan4289" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Include warning/error</tspan></text> + <text + x="43.87738" + y="537.71906" + id="text4090-8-14-4" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="43.87738" + y="537.71906" + id="tspan4289-1" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Fixes: line</tspan></text> + <text + x="43.87738" + y="598.9939" + id="text4090-8-14-0" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="43.87738" + y="598.9939" + id="tspan4289-2" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ How to reproduce</tspan></text> + </g> + <g + transform="translate(-2.6258125,-26.708615)" + id="g4115"> + <g + id="g3272"> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1" + y="454.36987" + x="49.093246"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7" + y="454.36987" + x="49.093246">+ build gcc icc clang </tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-2" + y="516.59979" + x="49.093246"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-79" + y="516.59979" + x="49.093246">+ make test doc </tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-2-0-0" + y="544.71033" + x="49.093246"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-79-9-0" + y="544.71033" + x="49.093246">+ make examples</tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-2-0-07" + y="576.83533" + x="49.093246"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-79-9-3" + y="576.83533" + x="49.093246">+ make shared-lib</tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-2-0-07-4" + y="604.88947" + x="49.093246"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-79-9-3-9" + y="604.88947" + x="49.093246">+ library ABI version</tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-2-9" + y="486.56659" + x="49.093246"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-79-3" + y="486.56659" + x="49.093246">+ build 32 and 64 bits</tspan></text> + </g> + </g> + <text + x="74.388756" + y="914.65686" + id="text4090-8-1-8-65-9" + xml:space="preserve" + style="font-size:19px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan3268" + x="74.388756" + y="914.65686">git send-email *.patch --annotate --to <maintainer></tspan><tspan + sodipodi:role="line" + id="tspan3272" + x="74.388756" + y="938.40686"> --cc dev@dpdk.org [ --cc other@participants.com</tspan><tspan + sodipodi:role="line" + x="74.388756" + y="962.15686" + id="tspan3266"> --cover-letter -v[N] --in-reply-to <message ID> ]</tspan></text> + <text + x="543.47675" + y="1032.3459" + id="text4090-8-7-8-7-6-3-8-2-5" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="543.47675" + y="1032.3459" + id="tspan4092-8-6-3-1-8-4-4-5-3" + style="font-size:11px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace">harry.van.haaren@intel.com</tspan></text> + <rect + width="678.14105" + height="87.351799" + rx="6.7972355" + ry="6.7972355" + x="31.865864" + y="888.44696" + id="rect3239-0-9-4-3" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + x="543.29498" + y="1018.1843" + id="text4090-8-7-8-7-6-3-8-2-5-3" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="543.29498" + y="1018.1843" + id="tspan4092-8-6-3-1-8-4-4-5-3-7" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Suggestions / Updates?</tspan></text> + <g + id="g3268" + transform="translate(0,-6)"> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8" + y="704.07019" + x="41.658669"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6" + y="704.07019" + x="41.658669">+ Patch version ( eg: -v2 ) </tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8-0" + y="736.29175" + x="41.658669"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6-2" + y="736.29175" + x="41.658669">+ Patch version annotations</tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8-6" + y="766.70355" + x="41.911205"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6-1" + y="766.70355" + x="41.911205">+ Send --to maintainer </tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8-6-3" + y="795.30548" + x="41.658669"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6-1-8" + y="795.30548" + x="41.658669">+ Send --cc dev@dpdk.org </tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8-9" + y="675.25287" + x="41.658669"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6-9" + y="675.25287" + x="41.658669">+ Cover letter</tspan></text> + <g + id="g3303" + transform="translate(1.0962334,-40.034939)"> + <text + sodipodi:linespacing="125%" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8-65" + y="868.70337" + x="41.572586"><tspan + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6-10" + y="868.70337" + x="41.572586">+ Send --in-reply-to <message ID><tspan + style="font-size:20px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan3184" /></tspan></text> + <text + sodipodi:linespacing="125%" + style="font-size:25.6917057px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + xml:space="preserve" + id="text4090-8-1-8-9-1" + y="855.79816" + x="460.18405"><tspan + style="font-size:11.56126785px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + id="tspan4092-8-7-6-9-7" + y="855.79816" + x="460.18405">****</tspan></text> + </g> + </g> + <text + x="685.67828" + y="76.55056" + id="text4090-8-1-8-9-1-9" + xml:space="preserve" + style="font-size:20.20989037px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="685.67828" + y="76.55056" + id="tspan4092-8-7-6-9-7-4" + style="font-size:9.09445095px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">v1.0</tspan></text> + <rect + width="342.3053" + height="155.54948" + rx="9.2344503" + ry="9.2344503" + x="377.58942" + y="114.55766" + id="rect3239-0-9-4-2-1" + style="fill:none;stroke:#00233b;stroke-width:0.76930124;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <rect + width="342.12564" + height="236.79482" + rx="10.647112" + ry="9.584527" + x="25.642178" + y="356.86249" + id="rect3239-0-9-4-2-0" + style="fill:none;stroke:#00233b;stroke-width:0.9489302;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <rect + width="341.98428" + height="312.73181" + rx="8.5358429" + ry="8.5358429" + x="377.96762" + y="280.45331" + id="rect3239-0-9-4-2-1-9" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + d="m 387.02742,157.3408 323.14298,0" + id="path4088-8" + style="fill:none;stroke:#00233b;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + inkscape:connector-curvature="0" /> + <path + d="m 36.504486,397.33869 323.142974,0" + id="path4088-82" + style="fill:none;stroke:#00233b;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + inkscape:connector-curvature="0" /> + <path + d="m 35.494337,156.92238 323.142983,0" + id="path4088-4" + style="fill:none;stroke:#00233b;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + inkscape:connector-curvature="0" /> + <g + transform="translate(1.0962334,-30.749225)" + id="g3363"> + <text + x="45.371201" + y="214.1572" + id="text4090-8-11" + xml:space="preserve" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="45.371201" + y="214.1572" + id="tspan4092-8-52" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Signed-off-by: </tspan></text> + <text + x="45.371201" + y="243.81795" + id="text4090-8-7-8" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="45.371201" + y="243.81795" + id="tspan4092-8-6-3" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Suggested-by:</tspan></text> + <text + x="45.371201" + y="273.90939" + id="text4090-8-7-8-7" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="45.371201" + y="273.90939" + id="tspan4092-8-6-3-1" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Reported-by:</tspan></text> + <text + x="45.371201" + y="304.00082" + id="text4090-8-7-8-7-6" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="45.371201" + y="304.00082" + id="tspan4092-8-6-3-1-8" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Tested-by:</tspan></text> + <g + id="g3297" + transform="translate(1.1147904,-7.2461378)"> + <text + x="45.371201" + y="368.8187" + id="text4090-8-7-8-7-6-3" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="45.371201" + y="368.8187" + id="tspan4092-8-6-3-1-8-4" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Previous Acks</tspan></text> + <text + x="235.24362" + y="360.3028" + id="text4090-8-1-8-9-1-4" + xml:space="preserve" + style="font-size:25.6917057px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="235.24362" + y="360.3028" + id="tspan4092-8-7-6-9-7-0" + style="font-size:11.56126785px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + </g> + <text + x="45.371201" + y="334.52298" + id="text4090-8-7-8-7-6-3-4" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="45.371201" + y="334.52298" + id="tspan4092-8-6-3-1-8-4-0" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Commit message</tspan></text> + </g> + <rect + width="295.87207" + height="164.50136" + rx="7.3848925" + ry="4.489974" + x="414.80502" + y="611.47064" + id="rect3239-0-9-4-2-1-9-9" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + x="439.4429" + y="638.35608" + id="text4090-1-4" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="439.4429" + y="638.35608" + id="tspan4092-38-8" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Mailing List</tspan></text> + <text + x="431.55353" + y="675.59857" + id="text4090-8-5-6-9-4-6-6-8" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="431.55353" + y="675.59857" + id="tspan4092-8-5-5-3-4-0-6-2" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Acked-by:</tspan></text> + <text + x="431.39734" + y="734.18231" + id="text4090-8-5-6-9-4-6-6-8-5" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="431.39734" + y="734.18231" + id="tspan4092-8-5-5-3-4-0-6-2-1" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Reviewed-by:</tspan></text> + <text + x="450.8428" + y="766.5578" + id="text4090-8-5-6-9-4-6-6-8-7" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="450.8428" + y="766.5578" + id="tspan4092-8-5-5-3-4-0-6-2-11" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">Nack (refuse patch)</tspan></text> + <path + d="m 426.99385,647.80575 272.72607,0" + id="path4088-7-5" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <path + d="m 424.7332,742.35699 272.72607,0" + id="path4088-7-5-2" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <text + x="431.39734" + y="704.78278" + id="text4090-8-5-6-9-4-6-6-8-5-1" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="431.39734" + y="704.78278" + id="tspan4092-8-5-5-3-4-0-6-2-1-7" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Tested-by:</tspan></text> + <g + transform="translate(1.0962334,-2.7492248)" + id="g3613"> + <text + x="43.146141" + y="1007.5879" + id="text4090-8-7-8-7-6-3-8" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="43.146141" + y="1007.5879" + id="tspan4092-8-6-3-1-8-4-4" + style="font-size:11px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace">Previous Acks only when fixing typos, rebased, or checkpatch issues.</tspan></text> + <text + x="30.942892" + y="1011.3757" + id="text4090-8-7-8-7-6-3-8-4-1" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="30.942892" + y="1011.3757" + id="tspan4092-8-6-3-1-8-4-4-55-7" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + </g> + <g + transform="translate(1.0962334,-2.7492248)" + id="g3605"> + <text + x="42.176418" + y="1020.4383" + id="text4090-8-7-8-7-6-3-8-4" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="42.176418" + y="1020.4383" + id="tspan4092-8-6-3-1-8-4-4-55" + style="font-size:11px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace">The version.map function names must be in alphabetical order.</tspan></text> + <text + x="30.942892" + y="1024.2014" + id="text4090-8-7-8-7-6-3-8-4-1-5" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="30.942892" + y="1024.2014" + id="tspan4092-8-6-3-1-8-4-4-55-7-2" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="25.247679" + y="1024.2014" + id="text4090-8-7-8-7-6-3-8-4-1-5-6" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="25.247679" + y="1024.2014" + id="tspan4092-8-6-3-1-8-4-4-55-7-2-8" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + </g> + <g + transform="translate(1.0962334,-30.749225)" + id="g3275"> + <g + id="g3341"> + <text + x="394.78601" + y="390.17807" + id="text4090-8" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="390.17807" + id="tspan4092-8" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Rebase to git </tspan></text> + <text + x="394.78601" + y="420.24835" + id="text4090-8-5" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="420.24835" + id="tspan4092-8-5" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Checkpatch </tspan></text> + <text + x="394.78601" + y="450.53394" + id="text4090-8-5-6" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="450.53394" + id="tspan4092-8-5-5" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ ABI breakage </tspan></text> + <text + x="394.78601" + y="513.13031" + id="text4090-8-5-6-9-4" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="513.13031" + id="tspan4092-8-5-5-3-4" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Maintainers file</tspan></text> + <text + x="394.78601" + y="573.48621" + id="text4090-8-5-6-9-4-6" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="573.48621" + id="tspan4092-8-5-5-3-4-0" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Release notes</tspan></text> + <text + x="395.79617" + y="603.98718" + id="text4090-8-5-6-9-4-6-6" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="395.79617" + y="603.98718" + id="tspan4092-8-5-5-3-4-0-6" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Documentation</tspan></text> + <g + transform="translate(0,-0.83470152)" + id="g3334"> + <g + id="g3267" + transform="translate(-13.517932,3.1531035)"> + <text + x="660.46729" + y="468.01297" + id="text4090-8-1-8-9-1-4-1" + xml:space="preserve" + style="font-size:25.6917057px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="660.46729" + y="468.01297" + id="tspan4092-8-7-6-9-7-0-7" + style="font-size:11.56126785px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">**</tspan></text> + </g> + <text + x="394.78601" + y="483.59955" + id="text4090-8-5-6-9" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="483.59955" + id="tspan4092-8-5-5-3" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Update version.map</tspan></text> + </g> + <g + id="g3428" + transform="translate(0,0.88137813)"> + <text + x="394.78601" + y="541.38928" + id="text4090-8-5-6-9-4-6-1" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="394.78601" + y="541.38928" + id="tspan4092-8-5-5-3-4-0-7" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+ Doxygen</tspan></text> + <g + transform="translate(-119.92979,57.949844)" + id="g3267-9"> + <text + x="628.93628" + y="473.13675" + id="text4090-8-1-8-9-1-4-1-4" + xml:space="preserve" + style="font-size:25.6917057px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="628.93628" + y="473.13675" + id="tspan4092-8-7-6-9-7-0-7-8" + style="font-size:11.56126785px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">***</tspan></text> + </g> + </g> + </g> + </g> + <text + x="840.1828" + y="234.34692" + transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,0,0)" + id="text4090-8-5-6-9-4-6-6-8-7-4" + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + sodipodi:linespacing="125%"><tspan + x="840.1828" + y="234.34692" + id="tspan4092-8-5-5-3-4-0-6-2-11-0" + style="font-size:21px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">+</tspan></text> + <g + transform="translate(1.0962334,-2.7492248)" + id="g3595"> + <text + x="30.942892" + y="1037.0271" + id="text4090-8-7-8-7-6-3-8-4-1-2" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="30.942892" + y="1037.0271" + id="tspan4092-8-6-3-1-8-4-4-55-7-3" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="25.247679" + y="1037.0271" + id="text4090-8-7-8-7-6-3-8-4-1-2-5" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="25.247679" + y="1037.0271" + id="tspan4092-8-6-3-1-8-4-4-55-7-3-7" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="19.552465" + y="1037.0271" + id="text4090-8-7-8-7-6-3-8-4-1-2-7" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="19.552465" + y="1037.0271" + id="tspan4092-8-6-3-1-8-4-4-55-7-3-9" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="42.830166" + y="1033.2393" + id="text4090-8-7-8-7-6-3-8-4-8" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="42.830166" + y="1033.2393" + id="tspan4092-8-6-3-1-8-4-4-55-2" + style="font-size:11px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace">New header files must get a new page in the API docs.</tspan></text> + </g> + <g + transform="translate(1.0962334,-2.7492248)" + id="g3619"> + <text + x="42.212418" + y="1046.0962" + id="text4090-8-7-8-7-6-3-8-2" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold" + sodipodi:linespacing="125%"><tspan + x="42.212418" + y="1046.0962" + id="tspan4092-8-6-3-1-8-4-4-5" + style="font-size:11px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace">Available from patchwork, or email header. Reply to Cover letters.</tspan></text> + <text + x="31.140535" + y="1049.8527" + id="text4090-8-7-8-7-6-3-8-4-1-2-2" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="31.140535" + y="1049.8527" + id="tspan4092-8-6-3-1-8-4-4-55-7-3-3" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="25.445322" + y="1049.8527" + id="text4090-8-7-8-7-6-3-8-4-1-2-5-2" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="25.445322" + y="1049.8527" + id="tspan4092-8-6-3-1-8-4-4-55-7-3-7-2" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="19.750109" + y="1049.8527" + id="text4090-8-7-8-7-6-3-8-4-1-2-7-1" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="19.750109" + y="1049.8527" + id="tspan4092-8-6-3-1-8-4-4-55-7-3-9-6" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + <text + x="14.016749" + y="1049.8527" + id="text4090-8-7-8-7-6-3-8-4-1-2-7-1-8" + xml:space="preserve" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace Bold"><tspan + x="14.016749" + y="1049.8527" + id="tspan4092-8-6-3-1-8-4-4-55-7-3-9-6-5" + style="font-size:13px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace Bold">*</tspan></text> + </g> + <rect + width="196.44218" + height="45.785767" + rx="10.771052" + ry="10.771052" + x="531.44666" + y="998.50568" + id="rect3239-0-9-4-2-1-9-9-7" + style="fill:none;stroke:#00233b;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <rect + width="678.43036" + height="43.497677" + rx="7.8557949" + ry="6.7630997" + x="31.274473" + y="836.69745" + id="rect3239-0-9-4-3-6" + style="fill:none;stroke:#00233b;stroke-width:0.92794865;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + x="73.804535" + y="864.28137" + id="text4090-8-1-8-65-9-1" + xml:space="preserve" + style="font-size:19px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + x="73.804535" + y="864.28137" + id="tspan3266-8">git format-patch -[N]</tspan></text> + <text + x="342.70221" + y="862.83478" + id="text4090-8-1-8-65-9-1-7" + xml:space="preserve" + style="font-size:19px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + x="342.70221" + y="862.83478" + id="tspan3266-8-2" + style="font-size:14px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace;-inkscape-font-specification:Monospace">// creates .patch files for final review</tspan></text> + </g> +</svg> diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst new file mode 100644 index 00000000..f6af317f --- /dev/null +++ b/doc/guides/contributing/index.rst @@ -0,0 +1,13 @@ +Contributor's Guidelines +======================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + coding_style + design + versioning + documentation + patches + cheatsheet diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst new file mode 100644 index 00000000..06af91d6 --- /dev/null +++ b/doc/guides/contributing/patches.rst @@ -0,0 +1,395 @@ +.. submitting_patches: + +Contributing Code to DPDK +========================= + +This document outlines the guidelines for submitting code to DPDK. + +The DPDK development process is modelled (loosely) on the Linux Kernel development model so it is worth reading the +Linux kernel guide on submitting patches: +`How to Get Your Change Into the Linux Kernel <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_. +The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines. + + +The DPDK Development Process +----------------------------- + +The DPDK development process has the following features: + +* The code is hosted in a public git repository. +* There is a mailing list where developers submit patches. +* There are maintainers for hierarchical components. +* Patches are reviewed publicly on the mailing list. +* Successfully reviewed patches are merged to the master branch of the repository. + +The mailing list for DPDK development is `dev@dpkg.org <http://dpdk.org/ml/archives/dev/>`_. +Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches. +It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwxispork/project/dpdk/list/>`_ + +The development process requires some familiarity with the ``git`` version control system. +Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information. + + +Getting the Source Code +----------------------- + +The source code can be cloned using either of the following:: + + git clone git://dpdk.org/dpdk + + git clone http://dpdk.org/git/dpdk + + +Make your Changes +----------------- + +Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements: + +* Follow the :ref:`coding_style` guidelines. + +* If you add new files or directories you should add your name to the ``MAINTAINERS`` file. + +* New external functions should be added to the local ``version.map`` file. + See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`. + New external functions should also be added in alphabetical order. + +* Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``. + See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details. + +* Test the compilation works with different targets, compilers and options, see :ref:`contrib_check_compilation`. + +* Don't break compilation between commits with forward dependencies in a patchset. + Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing. + +* Add tests to the the ``app/test`` unit test framework where possible. + +* Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format. + See the :ref:`Documentation Guidelines <doc_guidelines>`. + +Once the changes have been made you should commit them to your local repo. + +For small changes, that do not require specific explanations, it is better to keep things together in the +same patch. +Larger changes that require different explanations should be separated into logical patches in a patchset. +A good way of thinking about whether a patch should be split is to consider whether the change could be +applied without dependencies as a backport. + +As a guide to how patches should be structured run ``git log`` on similar files. + + +Commit Messages: Subject Line +----------------------------- + +The first, summary, line of the git commit message becomes the subject line of the patch email. +Here are some guidelines for the summary line: + +* The summary line must capture the area and the impact of the change. + +* The summary line should be around 50 characters. + +* The summary line should be lowercase apart from acronyms. + +* It should be prefixed with the component name (use git log to check existing components). + For example:: + + ixgbe: fix offload config option name + + config: increase max queues per port + +* Use the imperative of the verb (like instructions to the code base). + +* Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``. + +The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1, +for example: ``PATCH v2``. +The is generally added by ``git send-email`` or ``git format-patch``, see below. + +If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``. +An RFC patch doesn't have to be complete. +It is intended as a way of getting early feedback. + + +Commit Messages: Body +--------------------- + +Here are some guidelines for the body of a commit message: + +* The body of the message should describe the issue being fixed or the feature being added. + It is important to provide enough information to allow a reviewer to understand the purpose of the patch. + +* When the change is obvious the body can be blank, apart from the signoff. + +* The commit message must end with a ``Signed-off-by:`` line which is added using:: + + git commit --signoff # or -s + + The purpose of the signoff is explained in the + `Developer's Certificate of Origin <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_ + section of the Linux kernel guidelines. + + .. Note:: + + All developers must ensure that they have read and understood the + Developer's Certificate of Origin section of the documentation prior + to applying the signoff and submitting a patch. + +* The signoff must be a real name and not an alias or nickname. + More than one signoff is allowed. + +* The text of the commit message should be wrapped at 72 characters. + +* When fixing a regression, it is a good idea to reference the id of the commit which introduced the bug. + You can generate the required text using the following git alias:: + + git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")'" + + The ``Fixes:`` line can then be added to the commit message:: + + doc: fix vhost sample parameter + + Update the docs to reflect removed dev-index. + + Fixes: 17b8320a3e11 ("vhost: remove index parameter") + + Signed-off-by: Alex Smith <alex.smith@example.com> + +* When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it. + +* Use correct capitalization, punctuation and spelling. + +In addition to the ``Signed-off-by:`` name the commit messages can also have one or more of the following: + +* ``Reported-by:`` The reporter of the issue. +* ``Tested-by:`` The tester of the change. +* ``Reviewed-by:`` The reviewer of the change. +* ``Suggested-by:`` The person who suggested the change. +* ``Acked-by:`` When a previous version of the patch was acked and the ack is still relevant. + + +Creating Patches +---------------- + +It is possible to send patches directly from git but for new contributors it is recommended to generate the +patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to +send them with ``git send-email``. + +Here are some examples of using ``git format-patch`` to generate patches: + +.. code-block:: console + + # Generate a patch from the last commit. + git format-patch -1 + + # Generate a patch from the last 3 commits. + git format-patch -3 + + # Generate the patches in a directory. + git format-patch -3 -o ~/patch/ + + # Add a cover letter to explain a patchset. + git format-patch -3 -o ~/patch/ --cover-letter + + # Add a prefix with a version number. + git format-patch -3 -o ~/patch/ -v 2 + + +Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches. +Smaller notes can be put inline in the patch after the ``---`` separator, for example:: + + Subject: [PATCH] fm10k/base: add FM10420 device ids + + Add the device ID for Boulder Rapids and Atwood Channel to enable + drivers to support those devices. + + Signed-off-by: Alex Smith <alex.smith@example.com> + --- + + ADD NOTES HERE. + + drivers/net/fm10k/base/fm10k_api.c | 6 ++++++ + drivers/net/fm10k/base/fm10k_type.h | 6 ++++++ + 2 files changed, 12 insertions(+) + ... + +Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed. +This can be added to the cover letter or the annotations. +For example:: + + --- + v3: + * Fixed issued with version.map. + + v2: + * Added i40e support. + * Renamed ethdev functions from rte_eth_ieee15888_*() to rte_eth_timesync_*() + since 802.1AS can be supported through the same interfaces. + + +.. _contrib_checkpatch: + +Checking the Patches +-------------------- + +Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``scripts`` +directory of the DPDK repo. +This uses the Linux kernel development tool ``checkpatch.pl`` which can be obtained by cloning, and periodically, +updating the Linux kernel sources. + +The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``. +This, and any other configuration variables required by the development tools, are loaded from the following +files, in order of preference:: + + .develconfig + ~/.config/dpdk/devel.config + /etc/dpdk/devel.config. + +Once the environment variable the script can be run as follows:: + + scripts/checkpatches.sh ~/patch/ + +The script usage is:: + + checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]" + +Where: + +* ``-h``: help, usage. +* ``-q``: quiet. Don't output anything for files without issues. +* ``-v``: verbose. +* ``patchX``: path to one or more patches. + +Then the git logs should be checked using the ``check-git-log.sh`` script. + +The script usage is:: + + check-git-log.sh [range] + +Where the range is a ``git log`` option. + + +.. _contrib_check_compilation: + +Checking Compilation +-------------------- + +Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``scripts`` +directory of the DPDK repo:: + + scripts/test-build.sh x86_64-native-linuxapp-gcc+next+shared + +The script usage is:: + + test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]] + +Where: + +* ``-h``: help, usage. +* ``-jX``: use X parallel jobs in "make". +* ``-s``: short test with only first config and without examples/doc. +* ``config``: default config name plus config switches delimited with a ``+`` sign. + +Examples of configs are:: + + x86_64-native-linuxapp-gcc + x86_64-native-linuxapp-gcc+next+shared + x86_64-native-linuxapp-clang+shared + +The builds can be modifies via the following environmental variables: + +* ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2) +* ``DPDK_DEP_CFLAGS`` +* ``DPDK_DEP_LDFLAGS`` +* ``DPDK_DEP_MOFED`` (y/[n]) +* ``DPDK_DEP_PCAP`` (y/[n]) +* ``DPDK_NOTIFY`` (notify-send) + +These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`. + +The recommended configurations and options to test compilation prior to submitting patches are:: + + x86_64-native-linuxapp-gcc+shared+next + x86_64-native-linuxapp-clang+shared + i686-native-linuxapp-gcc + + export DPDK_DEP_ZLIB=y + export DPDK_DEP_PCAP=y + export DPDK_DEP_SSL=y + + +Sending Patches +--------------- + +Patches should be sent to the mailing list using ``git send-email``. +You can configure an external SMTP with something like the following:: + + [sendemail] + smtpuser = name@domain.com + smtpserver = smtp.domain.com + smtpserverport = 465 + smtpencryption = ssl + +See the `Git send-email <https://git-scm.com/docs/git-send-email>`_ documentation for more details. + +The patches should be sent to ``dev@dpdk.org``. +If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``. +The appropriate maintainer can be found in the ``MAINTAINERS`` file:: + + git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch + +New additions can be sent without a maintainer:: + + git send-email --to dev@dpdk.org 000*.patch + +You can test the emails by sending it to yourself or with the ``--dry-run`` option. + +If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID:: + + git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch + +The Message ID can be found in the raw text of emails or at the top of each Patchwork patch, +`for example <http://dpdk.org/dev/patchwork/patch/7646/>`_. +Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series. + +Once submitted your patches will appear on the mailing list and in Patchwork. + +Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step. +The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending. + + +The Review Process +------------------ + +The more work you put into the previous steps the easier it will be to get a patch accepted. + +The general cycle for patch review and acceptance is: + +#. Submit the patch. + +#. Check the automatic test reports in the coming hours. + +#. Wait for review comments. While you are waiting review some other patches. + +#. Fix the review comments and submit a ``v n+1`` patchset:: + + git format-patch -3 -v 2 + +#. Update Patchwork to mark your previous patches as "Superseded". + +#. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack`` + the patch with an email that includes something like:: + + Acked-by: Alex Smith <alex.smith@example.com> + + **Note**: When acking patches please remove as much of the text of the patch email as possible. + It is generally best to delete everything after the ``Signed-off-by:`` line. + +#. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted. + +#. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality + it may receive a ``nack``. + In this case you will need to make a more convincing technical argument in favor of your patches. + +#. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or + valid arguments. + +#. Acked patches will be merged in the current or next merge window. diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst new file mode 100644 index 00000000..ae10a984 --- /dev/null +++ b/doc/guides/contributing/versioning.rst @@ -0,0 +1,494 @@ +Managing ABI updates +==================== + +Description +----------- + +This document details some methods for handling ABI management in the DPDK. +Note this document is not exhaustive, in that C library versioning is flexible +allowing multiple methods to achieve various goals, but it will provide the user +with some introductory methods + +General Guidelines +------------------ + +#. Whenever possible, ABI should be preserved +#. The libraries marked in experimental state may change without constraint. +#. The addition of symbols is generally not problematic +#. The modification of symbols can generally be managed with versioning +#. The removal of symbols generally is an ABI break and requires bumping of the + LIBABIVER macro + +What is an ABI +-------------- + +An ABI (Application Binary Interface) is the set of runtime interfaces exposed +by a library. It is similar to an API (Application Programming Interface) but +is the result of compilation. It is also effectively cloned when applications +link to dynamic libraries. That is to say when an application is compiled to +link against dynamic libraries, it is assumed that the ABI remains constant +between the time the application is compiled/linked, and the time that it runs. +Therefore, in the case of dynamic linking, it is critical that an ABI is +preserved, or (when modified), done in such a way that the application is unable +to behave improperly or in an unexpected fashion. + +The DPDK ABI policy +------------------- + +ABI versions are set at the time of major release labeling, and the ABI may +change multiple times, without warning, between the last release label and the +HEAD label of the git tree. + +ABI versions, once released, are available until such time as their +deprecation has been noted in the Release Notes for at least one major release +cycle. For example consider the case where the ABI for DPDK 2.0 has been +shipped and then a decision is made to modify it during the development of +DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1 +release and the modification will be made available in the DPDK 2.2 release. + +ABI versions may be deprecated in whole or in part as needed by a given +update. + +Some ABI changes may be too significant to reasonably maintain multiple +versions. In those cases ABI's may be updated without backward compatibility +being provided. The requirements for doing so are: + +#. At least 3 acknowledgments of the need to do so must be made on the + dpdk.org mailing list. + +#. The changes (including an alternative map file) must be gated with + the ``RTE_NEXT_ABI`` option, and provided with a deprecation notice at the + same time. + It will become the default ABI in the next release. + +#. A full deprecation cycle, as explained above, must be made to offer + downstream consumers sufficient warning of the change. + +#. At the beginning of the next release cycle, every ``RTE_NEXT_ABI`` + conditions will be removed, the ``LIBABIVER`` variable in the makefile(s) + where the ABI is changed will be incremented, and the map files will + be updated. + +Note that the above process for ABI deprecation should not be undertaken +lightly. ABI stability is extremely important for downstream consumers of the +DPDK, especially when distributed in shared object form. Every effort should +be made to preserve the ABI whenever possible. The ABI should only be changed +for significant reasons, such as performance enhancements. ABI breakage due to +changes such as reorganizing public structure fields for aesthetic or +readability purposes should be avoided. + +Examples of Deprecation Notices +------------------------------- + +The following are some examples of ABI deprecation notices which would be +added to the Release Notes: + +* The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0, + to be replaced with the inline function ``rte_foo()``. + +* The function ``rte_mbuf_grok()`` has been updated to include a new parameter + in version 2.0. Backwards compatibility will be maintained for this function + until the release of version 2.1 + +* The members of ``struct rte_foo`` have been reorganized in release 2.0 for + performance reasons. Existing binary applications will have backwards + compatibility in release 2.0, while newly built binaries will need to + reference the new structure variant ``struct rte_foo2``. Compatibility will + be removed in release 2.2, and all applications will require updating and + rebuilding to the new structure at that time, which will be renamed to the + original ``struct rte_foo``. + +* Significant ABI changes are planned for the ``librte_dostuff`` library. The + upcoming release 2.0 will not contain these changes, but release 2.1 will, + and no backwards compatibility is planned due to the extensive nature of + these changes. Binaries using this library built prior to version 2.1 will + require updating and recompilation. + +Versioning Macros +----------------- + +When a symbol is exported from a library to provide an API, it also provides a +calling convention (ABI) that is embodied in its name, return type and +arguments. Occasionally that function may need to change to accommodate new +functionality or behavior. When that occurs, it is desirable to allow for +backward compatibility for a time with older binaries that are dynamically +linked to the DPDK. + +To support backward compatibility the ``lib/librte_compat/rte_compat.h`` +header file provides macros to use when updating exported functions. These +macros are used in conjunction with the ``rte_<library>_version.map`` file for +a given library to allow multiple versions of a symbol to exist in a shared +library so that older binaries need not be immediately recompiled. + +The macros exported are: + +* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding + versioned symbol ``b@DPDK_n`` to the internal function ``b_e``. + +* ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing + the linker to bind references to symbol ``b`` to the internal symbol + ``b_e``. + +* ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the + fully qualified function ``p``, so that if a symbol becomes versioned, it + can still be mapped back to the public symbol name. + +Examples of ABI Macro use +------------------------- + +Updating a public API +~~~~~~~~~~~~~~~~~~~~~ + +Assume we have a function as follows + +.. code-block:: c + + /* + * Create an acl context object for apps to + * manipulate + */ + struct rte_acl_ctx * + rte_acl_create(const struct rte_acl_param *param) + { + ... + } + + +Assume that struct rte_acl_ctx is a private structure, and that a developer +wishes to enhance the acl api so that a debugging flag can be enabled on a +per-context basis. This requires an addition to the structure (which, being +private, is safe), but it also requires modifying the code as follows + +.. code-block:: c + + /* + * Create an acl context object for apps to + * manipulate + */ + struct rte_acl_ctx * + rte_acl_create(const struct rte_acl_param *param, int debug) + { + ... + } + + +Note also that, being a public function, the header file prototype must also be +changed, as must all the call sites, to reflect the new ABI footprint. We will +maintain previous ABI versions that are accessible only to previously compiled +binaries + +The addition of a parameter to the function is ABI breaking as the function is +public, and existing application may use it in its current form. However, the +compatibility macros in DPDK allow a developer to use symbol versioning so that +multiple functions can be mapped to the same public symbol based on when an +application was linked to it. To see how this is done, we start with the +requisite libraries version map file. Initially the version map file for the +acl library looks like this + +.. code-block:: none + + DPDK_2.0 { + global: + + rte_acl_add_rules; + rte_acl_build; + rte_acl_classify; + rte_acl_classify_alg; + rte_acl_classify_scalar; + rte_acl_create; + rte_acl_dump; + rte_acl_find_existing; + rte_acl_free; + rte_acl_ipv4vlan_add_rules; + rte_acl_ipv4vlan_build; + rte_acl_list_dump; + rte_acl_reset; + rte_acl_reset_rules; + rte_acl_set_ctx_classify; + + local: *; + }; + +This file needs to be modified as follows + +.. code-block:: none + + DPDK_2.0 { + global: + + rte_acl_add_rules; + rte_acl_build; + rte_acl_classify; + rte_acl_classify_alg; + rte_acl_classify_scalar; + rte_acl_create; + rte_acl_dump; + rte_acl_find_existing; + rte_acl_free; + rte_acl_ipv4vlan_add_rules; + rte_acl_ipv4vlan_build; + rte_acl_list_dump; + rte_acl_reset; + rte_acl_reset_rules; + rte_acl_set_ctx_classify; + + local: *; + }; + + DPDK_2.1 { + global: + rte_acl_create; + + } DPDK_2.0; + +The addition of the new block tells the linker that a new version node is +available (DPDK_2.1), which contains the symbol rte_acl_create, and inherits the +symbols from the DPDK_2.0 node. This list is directly translated into a list of +exported symbols when DPDK is compiled as a shared library + +Next, we need to specify in the code which function map to the rte_acl_create +symbol at which versions. First, at the site of the initial symbol definition, +we need to update the function so that it is uniquely named, and not in conflict +with the public symbol name + +.. code-block:: c + + struct rte_acl_ctx * + -rte_acl_create(const struct rte_acl_param *param) + +rte_acl_create_v20(const struct rte_acl_param *param) + { + size_t sz; + struct rte_acl_ctx *ctx; + ... + +Note that the base name of the symbol was kept intact, as this is conducive to +the macros used for versioning symbols. That is our next step, mapping this new +symbol name to the initial symbol name at version node 2.0. Immediately after +the function, we add this line of code + +.. code-block:: c + + VERSION_SYMBOL(rte_acl_create, _v20, 2.0); + +Remembering to also add the rte_compat.h header to the requisite c file where +these changes are being made. The above macro instructs the linker to create a +new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older +builds, but now points to the above newly named function. We have now mapped +the original rte_acl_create symbol to the original function (but with a new +name) + +Next, we need to create the 2.1 version of the symbol. We create a new function +name, with a different suffix, and implement it appropriately + +.. code-block:: c + + struct rte_acl_ctx * + rte_acl_create_v21(const struct rte_acl_param *param, int debug); + { + struct rte_acl_ctx *ctx = rte_acl_create_v20(param); + + ctx->debug = debug; + + return ctx; + } + +This code serves as our new API call. Its the same as our old call, but adds +the new parameter in place. Next we need to map this function to the symbol +``rte_acl_create@DPDK_2.1``. To do this, we modify the public prototype of the call +in the header file, adding the macro there to inform all including applications, +that on re-link, the default rte_acl_create symbol should point to this +function. Note that we could do this by simply naming the function above +rte_acl_create, and the linker would chose the most recent version tag to apply +in the version script, but we can also do this in the header file + +.. code-block:: c + + struct rte_acl_ctx * + -rte_acl_create(const struct rte_acl_param *param); + +rte_acl_create(const struct rte_acl_param *param, int debug); + +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1); + +The BIND_DEFAULT_SYMBOL macro explicitly tells applications that include this +header, to link to the rte_acl_create_v21 function and apply the DPDK_2.1 +version node to it. This method is more explicit and flexible than just +re-implementing the exact symbol name, and allows for other features (such as +linking to the old symbol version by default, when the new ABI is to be opt-in +for a period. + +One last thing we need to do. Note that we've taken what was a public symbol, +and duplicated it into two uniquely and differently named symbols. We've then +mapped each of those back to the public symbol ``rte_acl_create`` with different +version tags. This only applies to dynamic linking, as static linking has no +notion of versioning. That leaves this code in a position of no longer having a +symbol simply named ``rte_acl_create`` and a static build will fail on that +missing symbol. + +To correct this, we can simply map a function of our choosing back to the public +symbol in the static build with the ``MAP_STATIC_SYMBOL`` macro. Generally the +assumption is that the most recent version of the symbol is the one you want to +map. So, back in the C file where, immediately after ``rte_acl_create_v21`` is +defined, we add this + +.. code-block:: c + + struct rte_acl_create_v21(const struct rte_acl_param *param, int debug) + { + ... + } + MAP_STATIC_SYMBOL(struct rte_acl_create(const struct rte_acl_param *param, int debug), rte_acl_create_v21); + +That tells the compiler that, when building a static library, any calls to the +symbol ``rte_acl_create`` should be linked to ``rte_acl_create_v21`` + +That's it, on the next shared library rebuild, there will be two versions of +rte_acl_create, an old DPDK_2.0 version, used by previously built applications, +and a new DPDK_2.1 version, used by future built applications. + + +Deprecating part of a public API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lets assume that you've done the above update, and after a few releases have +passed you decide you would like to retire the old version of the function. +After having gone through the ABI deprecation announcement process, removal is +easy. Start by removing the symbol from the requisite version map file: + +.. code-block:: none + + DPDK_2.0 { + global: + + rte_acl_add_rules; + rte_acl_build; + rte_acl_classify; + rte_acl_classify_alg; + rte_acl_classify_scalar; + rte_acl_dump; + - rte_acl_create + rte_acl_find_existing; + rte_acl_free; + rte_acl_ipv4vlan_add_rules; + rte_acl_ipv4vlan_build; + rte_acl_list_dump; + rte_acl_reset; + rte_acl_reset_rules; + rte_acl_set_ctx_classify; + + local: *; + }; + + DPDK_2.1 { + global: + rte_acl_create; + } DPDK_2.0; + + +Next remove the corresponding versioned export. + +.. code-block:: c + + -VERSION_SYMBOL(rte_acl_create, _v20, 2.0); + + +Note that the internal function definition could also be removed, but its used +in our example by the newer version _v21, so we leave it in place. This is a +coding style choice. + +Lastly, we need to bump the LIBABIVER number for this library in the Makefile to +indicate to applications doing dynamic linking that this is a later, and +possibly incompatible library version: + +.. code-block:: c + + -LIBABIVER := 1 + +LIBABIVER := 2 + +Deprecating an entire ABI version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While removing a symbol from and ABI may be useful, it is often more practical +to remove an entire version node at once. If a version node completely +specifies an API, then removing part of it, typically makes it incomplete. In +those cases it is better to remove the entire node + +To do this, start by modifying the version map file, such that all symbols from +the node to be removed are merged into the next node in the map + +In the case of our map above, it would transform to look as follows + +.. code-block:: none + + DPDK_2.1 { + global: + + rte_acl_add_rules; + rte_acl_build; + rte_acl_classify; + rte_acl_classify_alg; + rte_acl_classify_scalar; + rte_acl_dump; + rte_acl_create + rte_acl_find_existing; + rte_acl_free; + rte_acl_ipv4vlan_add_rules; + rte_acl_ipv4vlan_build; + rte_acl_list_dump; + rte_acl_reset; + rte_acl_reset_rules; + rte_acl_set_ctx_classify; + + local: *; + }; + +Then any uses of BIND_DEFAULT_SYMBOL that pointed to the old node should be +updated to point to the new version node in any header files for all affected +symbols. + +.. code-block:: c + + -BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 2.0); + +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1); + +Lastly, any VERSION_SYMBOL macros that point to the old version node should be +removed, taking care to keep, where need old code in place to support newer +versions of the symbol. + +Running the ABI Validator +------------------------- + +The ``scripts`` directory in the DPDK source tree contains a utility program, +``validate-abi.sh``, for validating the DPDK ABI based on the Linux `ABI +Compliance Checker +<http://ispras.linuxbase.org/index.php/ABI_compliance_checker>`_. + +This has a dependency on the ``abi-compliance-checker`` and ``and abi-dumper`` +utilities which can be installed via a package manager. For example:: + + sudo yum install abi-compliance-checker + sudo yum install abi-dumper + +The syntax of the ``validate-abi.sh`` utility is:: + + ./scripts/validate-abi.sh <REV1> <REV2> <TARGET> + +Where ``REV1`` and ``REV2`` are valid gitrevisions(7) +https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html +on the local repo and target is the usual DPDK compilation target. + +For example: + + # Check between the previous and latest commit: + ./scripts/validate-abi.sh HEAD~1 HEAD x86_64-native-linuxapp-gcc + + # Check between two tags: + ./scripts/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linuxapp-gcc + + # Check between git master and local topic-branch "vhost-hacking": + ./scripts/validate-abi.sh master vhost-hacking x86_64-native-linuxapp-gcc + +After the validation script completes (it can take a while since it need to +compile both tags) it will create compatibility reports in the +``./compat_report`` directory. Listed incompatibilities can be found as +follows:: + + grep -lr Incompatible compat_reports/ |