Updated references to abi versions in the contributors guide.
Fixed an inaccurate reference to a symbol in the policy.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Reviewed-by: David Marchand <david.marchand@redhat.com>
With 'make' being removed, the patch cheatsheet needs to be updated to
remove any references to 'make'. These references have been replaced with
meson alternatives in this patch.
Signed-off-by: Kevin Laatz <kevin.laatz@intel.com>
Make is no longer supported for compiling DPDK, references are now
removed in the documentation.
Signed-off-by: Ciara Power <ciara.power@intel.com>
Signed-off-by: Louise Kilheeney <louise.kilheeney@intel.com>
A lot of drivers export headers, reproduce the same facility than for
libraries.
Note: this change fixes an issue with the crypto scheduler headers which
were not installed properly. A separate backport will be sent to stable
branches.
Suggested-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Fixes: 63b3907833d8 ("build: remove library name from version map file name")
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Replace master lcore with main lcore and
replace slave lcore with worker lcore.
Keep the old functions and macros but mark them as deprecated
for this release.
The "--master-lcore" command line option is also deprecated
and any usage will print a warning and use "--main-lcore"
as replacement.
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
Update the coding style document to include a policy against
introducing new master/slave usage. This is taken from the similar
place in the Linux kernel coding style.
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
Python 2 support has now been dropped. Remove references to it in the
documentation.
Since all python scripts now have a proper shebang that calls python3,
execute the scripts directly without specifying the interpreter.
Sphinx version from most Linux distros is OK in 2020, do not encourage
people to break their system by installing with pip. Use the distros
official packages.
Signed-off-by: Robin Jarry <robin.jarry@6wind.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Kevin Laatz <kevin.laatz@intel.com>
Changed scripts to explicitly use Python 3 only, to avoid
maintaining Python 2.
Removed deprecation notices.
Signed-off-by: Louise Kilheeney <louise.kilheeney@intel.com>
Signed-off-by: Kevin Laatz <kevin.laatz@intel.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Robin Jarry <robin.jarry@6wind.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Acked-by: Ray Kinsella <mdr@ashroe.eu>
A decision was made [1] to no longer support Make in DPDK, this patch
removes all Makefiles that do not make use of pkg-config, along with
the mk directory previously used by make.
[1] https://mails.dpdk.org/archives/dev/2020-April/162839.html
Signed-off-by: Ciara Power <ciara.power@intel.com>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
The default git branch of the main DPDK repository has been renamed
from master to main.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Added a section describing new ABI versions, this provides pointers to
the relevant amended rules that apply during the abi breakage window.
Also remove the large note at the head of the ABI policy describing the
ABI stability process that has taken place over the previous year.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
To help managing patch dependencies, both for maintainers or automation
tasks, document a syntax for commit logs or cover letters to express
their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]
Depends-on: series-NNNNN ("Title of the series")
OR
Depends-on: patch-NNNNN ("Title of the patch")
Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
This patch modifies the arguments expected by the check-git-log script,
to match the format of arguments for the checkpatches script. Both
scripts now take certain argument options in the same format, making
them easier to use.
e.g. Both now take a commit ID range by "-r <range>"
The checkpatches help print is also updated to include the "-h" option.
The contributor's guide includes the usage of both the checkpatches and
check-git-log scripts, which needed to be updated to reflect the now
standardised format.
Signed-off-by: Ciara Power <ciara.power@intel.com>
Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
Reviewed-by: Thomas Monjalon <thomas@monjalon.net>
Clarify retention period for aliases to experimental.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Reviewed-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
The following libraries are experimental, all of their functions can
be changed or removed:
- librte_bbdev
- librte_bpf
- librte_compressdev
- librte_fib
- librte_flow_classify
- librte_graph
- librte_ipsec
- librte_node
- librte_rcu
- librte_rib
- librte_stack
- librte_telemetry
Their status is properly announced in MAINTAINERS.
Remind this status in their headers in a common fashion (aligned to ABI
docs).
Cc: stable@dpdk.org
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Having a special versioning for experimental/internal libraries put a
additional maintenance cost while this status is already announced in
MAINTAINERS and the library headers/documentation.
Following discussions and vote at 05/20 TB meeting [1], use a single
versioning for all libraries in DPDK.
Note: for the ABI check, an exception [2] had been added when tweaking
this special versioning [3].
Prefer explicit libabigail rules (which will be dropped in 20.11).
1: https://mails.dpdk.org/archives/dev/2020-May/168450.html
2: https://git.dpdk.org/dpdk/commit/?id=23d7ad5db41c
3: https://git.dpdk.org/dpdk/commit/?id=ec2b8cd7ed69
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Since dynamic fields and flags were added in 19.11,
the idea was to use them for new features, not only PMD-specific.
The guideline is made more explicit in doxygen, in the mbuf guide,
and in the contribution design guidelines.
For more information about the original design, see the presentation
https://www.dpdk.org/wp-content/uploads/sites/35/2019/10/DynamicMbuf.pdf
This decision was discussed in the Technical Board:
http://mails.dpdk.org/archives/dev/2020-June/169667.html
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Olivier Matz <olivier.matz@6wind.com>
Acked-by: Jerin Jacob <jerinj@marvell.com>
Explicitly note that experimental APIs also part of security process.
Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Clarify that a fixed date will be used for end of embargo (public
disclosure) date while communicating with downstream stakeholders.
Initial document got a review that it gives an impression that
communicated embargo date can be a range like 'less than a week' which
is not the case. The range applies when defining the end of the embargo
date but a fix date will be communicated.
Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Bugzilla ID: 422
Fixes: 9e0e4a00df77 ("doc: suggest to keep doc and code in same patch")
Cc: stable@dpdk.org
Signed-off-by: Muhammad Bilal <m.bilal@emumba.com>
Since we've moved away from our initial validate-abi.sh script,
in favor of check-abi.sh, which uses libabigail,
remove the old script from the tree, and update the docs accordingly.
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
The versions currently listed as maintained have gone stale.
Rather than having to keep updating this doc, point to the
dpdk.org stable roadmap.
Signed-off-by: Kevin Traynor <ktraynor@redhat.com>
Acked-by: David Marchand <david.marchand@redhat.com>
Some errors in the document:
* API instead of ABI once.
Some typos:
* __rte_depreciated instead of __rte_deprecated.
* missing ```` around value.
* inconsistent reference to major ABI version, most
of the time described without the minor appended, except once.
Verbosity and grammar:
* Long sentences that would be better cut short.
* Comma abuse.
* 'May' used where 'can' seems more fitting.
I'm not a native speaker though, so grain of salt applies.
Fixes: fdf7471cccb8 ("doc: introduce major ABI versions")
Cc: stable@dpdk.org
Signed-off-by: Gaetan Rivet <grive@u256.net>
Acked-by: Ray Kinsella <mdr@ashroe.eu>
On v20.02 some APIs matured and symbols moved from EXPERIMENTAL to
DPDK_20.0.1 block.
This had the affect of breaking the applications that were using these
APIs on v19.11. Although there is no modification of the APIs and the
action is positive and matures the APIs, the affect can be negative to
applications.
When a maintainer is promoting an API to become part of the next major
ABI version by removing the experimental tag. The maintainer may
choose to offer an alias to the experimental tag, to prevent these
breakages in future.
The following changes are made to enabling aliasing:
Updated to the ABI policy and ABI versioning documents.
Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
Updated the 'check-symbols.sh' tool, which was complaining that the
symbol is in EXPERIMENTAL tag in .map file but it is not in the
.experimental section (__rte_experimental tag is missing).
Updated tool in a way it won't complain if the symbol in the
EXPERIMENTAL tag duplicated in some other block in .map file (versioned)
Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Neil Horman <nhorman@tuxdriver.com>
The document abi_versioning.rst incorrectly instructs the developer to
add BIND_DEFAULT_SYMBOL to the public header, not the source file. This
commit fixes the issue and adds some clarifications.
The commit also clarifies the use of use_function_versioning in the
meson/ninja build system, and does some minor re-organization of the
document.
Fixes: f1ef9794f9bd ("doc: add ABI guidelines")
Cc: stable@dpdk.org
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Clarify the reasons behind the three part version numbering scheme.
Documents the fixes made in f26c2b3.
Fixes: f26c2b39b271 ("build: fix soname info for 19.11 compatibility")
Cc: stable@dpdk.org
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Remove setting ALLOW_EXPERIMENTAL_API individually for each Makefile and
meson.build. Instead, enable ALLOW_EXPERIMENTAL_API flag across app, lib
and drivers.
This changes reduces the clutter across the project while still
maintaining the functionality of ALLOW_EXPERIMENTAL_API i.e. warning
external applications about experimental API usage.
Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com>
Acked-by: Hemant Agrawal <hemant.agrawal@nxp.com>
Signed-off-by: David Marchand <david.marchand@redhat.com>
The word "major" was used to differentiate with release candidates
or stable maintenance releases.
However the word "major" can be understood as "LTS",
so it is less confusing to avoid this word.
Reported-by: Ori Kam <orika@mellanox.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
For normal developers, those checks are disabled.
Enabling them requires a configuration that will trigger the ABI dumps
generation as part of the existing devtools/test-build.sh and
devtools/test-meson-builds.sh scripts.
Those checks are enabled in the CI for the default meson options on x86
and aarch64 so that proposed patches are validated via our CI robot.
A cache of the ABI is stored in travis jobs to avoid rebuilding too
often.
Checks can be informational only, by setting ABI_CHECKS_WARN_ONLY when
breaking the ABI in a future release.
Explicit suppression rules have been added on internal structures
exposed to crypto drivers as the current ABI policy does not apply to
them.
This could be improved in the future by carefully splitting the headers
content with application and driver "users" in mind.
We currently have issues reported for librte_crypto recent changes for
which suppression rules have been added too.
Mellanox glue libraries are explicitly skipped as they are not part of
the application ABI.
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Luca Boccassi <bluca@debian.org>
By default, both test-build.sh and test-meson-builds.sh scripts create the
builds they generate in the current working directory, leading to a large
number of build directories being present when testing patches. This
patchset modifies both scripts to use a DPDK_BUILD_TEST_DIR environment
variable to control where the build outputs are put.
For example, doing:
export DPDK_BUILD_TEST_DIR=__builds
./devtools/test-meson-builds.sh && ./devtools/test-build.sh \
x86_64-native-linux-clang+shared i686-native-linux-gcc
gives a "__builds" directory with 14 meson and 2 make builds (with the
meson build count depending on compiler availability)
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: David Marchand <david.marchand@redhat.com>
As per new ABI policy [1], all of the libraries are now versioned using
one global ABI version. Stable libraries use the MAJOR.MINOR ABI
version for their shared objects, while experimental libraries
use the 0.MAJORMINOR convention for their versioning.
Experimental library versioning is managed globally. Changes in this
patch implement the necessary steps to enable that.
The CONFIG_RTE_MAJOR_ABI option was introduced to permit multiple
DPDK versions installed side by side. The problem is now addressed
through the new ABI policy, and thus can be removed.
[David] For external libraries relying on Makefile, LIBABIVER is
preserved to avoid using DPDK global ABI version.
[1] https://doc.dpdk.org/guides/contributing/abi_policy.html
Signed-off-by: Marcin Baran <marcinx.baran@intel.com>
Signed-off-by: Pawel Modrak <pawelx.modrak@intel.com>
Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Shoot repeated words in all our guides.
Cc: stable@dpdk.org
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
The OSS-security project functions as a single point of contact for
pre-release, embargoed security notifications. Distributions and major
vendors are subscribed to this private list, so that they can be warned
in advance and schedule the work required to fix the vulnerability.
List and link this process in the DPDK security process document.
Signed-off-by: Luca Boccassi <luca.boccassi@microsoft.com>
Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>
Updates to the ABI versioning guide, to account for the changes to the DPDK
ABI/API policy. Fixes for references to abi versioning and policy guides.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
This policy change introduces major ABI versions, these are
declared every year, typically aligned with the LTS release
and are supported by subsequent releases in the following year.
This change is intended to improve ABI stabilty for those projects
consuming DPDK.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Separate versioning.rst into abi versioning and abi policy guidance, in
preparation for adding more detail to the abi policy. Add an entry to the
maintainer file for the abi policy.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Every implementation of a particular version of given symbol needs to be
marked in its declaration as such (using `__vsym` macro). This patch
fixes this and also clarifies the documentation about that.
Signed-off-by: Andrzej Ostruszka <aostruszka@marvell.com>
Acked-by: Neil Horman <nhorman@tuxdriver.com>
This patch fixes documentation of versioning macros so that they are
aligned with their implementation (no underscore is added by macros).
Fixes: f1ef9794f9bd ("doc: add ABI guidelines")
Cc: stable@dpdk.org
Signed-off-by: Andrzej Ostruszka <aostruszka@marvell.com>
Acked-by: Neil Horman <nhorman@tuxdriver.com>
Any file with ABI versioned functions needs different macros for shared and
static builds, so we need to accommodate that. Rather than building
everything twice, we just flag to the build system which libraries need
that handling, by setting use_function_versioning in the meson.build files.
To ensure we don't get silent errors at build time due to this meson flag
being missed, we add an explicit error to the function versioning header
file if a known C macro is not defined. Since "make" builds always only
build one of shared or static libraries, this define can be always set, and
so is added to the global CFLAGS. For meson, the build flag - and therefore
the C define - is set for the three libraries that need the function
versioning: "distributor", "lpm" and "timer".
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Tested-by: Andrzej Ostruszka <amo@semihalf.com>
Reviewed-by: Andrzej Ostruszka <amo@semihalf.com>
The compat.h header file provided macros for two purposes:
1. it provided the macros for marking functions as rte_experimental
2. it provided the macros for doing function versioning
Although these were in the same file, #1 is something that is for use by
public header files, which #2 is for internal use only. Therefore, we can
split these into two headers, keeping #1 in rte_compat.h and #2 in a new
file rte_function_versioning.h. For "make" builds, since internal objects
pick up the headers from the "include/" folder, we need to add the new
header to the installation list, but for "meson" builds it does not need to
be installed as it's not for public use.
The rework also serves to allow the use of the function versioning macros
to files that actually need them, so the use of experimental functions does
not need including of the versioning code.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Reviewed-by: Andrzej Ostruszka <amo@semihalf.com>
This patch for DPDK Contributor's Guidelines indicates the repos
against which a new PMD should be prepared; for example, for new
network ethernet PMDs it should be dpdk-next-net, and for new crypto
PMDs it should be dpdk-next-crypto. For other new PMDs, the
contributor should refer to the MAINTAINERS file. Though this may seem
obvious, it is not mentioned in DPDK documentation.
Signed-off-by: Rami Rosen <ramirose@gmail.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Last contribution, last commit closing the release.
Thank you Rami, you will be missed.
The backup maintainer role is not explicitly used in the file MAINTAINERS.
Listing names in a priority order is preferred and more flexible
than explicit named roles.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Reviewed-by: David Marchand <david.marchand@redhat.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
The command "make doc-guides-pdf" is failing because
there are more than 1500 lines in the file MAINTAINERS
which is included in the contributing guide.
We are facing the issue mentioned in this comment:
https://github.com/sphinx-doc/sphinx/issues/3099#issuecomment-256440704
Anyway the file MAINTAINERS is mentioned several times in the guide.
So the "literalinclude" is removed from the guide to fix the build
of the PDF.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Tested-by: Ferruh Yigit <ferruh.yigit@intel.com>
