dts: add API doc generation

The tool used to generate DTS API docs is Sphinx, which is already in
use in DPDK. The same configuration is used to preserve style with one
DTS-specific configuration (s

dts: add API doc generation

The tool used to generate DTS API docs is Sphinx, which is already in
use in DPDK. The same configuration is used to preserve style with one
DTS-specific configuration (so that the DPDK docs are unchanged) that
modifies how the sidebar displays the content. There's other Sphinx
configuration related to Python docstrings which doesn't affect DPDK doc
build. All new configuration is in a conditional block, applied only
when DTS API docs are built to not interfere with DPDK doc build.

Sphinx generates the documentation from Python docstrings. The docstring
format is the Google format [0] which requires the sphinx.ext.napoleon
extension. The other extension, sphinx.ext.intersphinx, enables linking
to objects in external documentations, such as the Python documentation.

There is one requirement for building DTS docs - the same Python version
as DTS or higher, because Sphinx's autodoc extension imports the code.

The dependencies needed to import the code don't have to be satisfied,
as the autodoc extension allows us to mock the imports. The missing
packages are taken from the DTS pyproject.toml file.

And finally, the DTS API docs can be accessed from the DPDK API doxygen
page.

[0] https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Reviewed-by: Jeremy Spewock <jspewock@iol.unh.edu>
Reviewed-by: Dean Marx <dmarx@iol.unh.edu>
Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>

show more ...

lib: use C11 alignment attribute on variables

The current location used for __rte_aligned(a) for alignment of
variables is not compatible with MSVC.

For variables, standard C11 offers alignas(a) su

lib: use C11 alignment attribute on variables

The current location used for __rte_aligned(a) for alignment of
variables is not compatible with MSVC.

For variables, standard C11 offers alignas(a) supported by conformant
compilers i.e. both MSVC and GCC.

Replace use of __rte_aligned(a) on variables/fields with alignas(a).

Signed-off-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
Acked-by: Morten Brørup <mb@smartsharesystems.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Konstantin Ananyev <konstantin.ananyev@huawei.com>
Signed-off-by: David Marchand <david.marchand@redhat.com>

show more ...

doc: update RST text-wrapping guidelines

Update and clarify the guidelines on how to wrap lines in our RST docs.
We no longer limit lines to just 80 characters, and what is more
important that line

doc: update RST text-wrapping guidelines

Update and clarify the guidelines on how to wrap lines in our RST docs.
We no longer limit lines to just 80 characters, and what is more
important that line length is the wrapping of sentences, starting a new
sentence on a new line, and wrapping at punctuation.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

show more ...

doc: build API manpages as well as HTML output

Doxygen can produce manpage output as well as HTML output for the DPDK
APIs. However, we need to do this as a separate task as the manpage
output needs

doc: build API manpages as well as HTML output

Doxygen can produce manpage output as well as HTML output for the DPDK
APIs. However, we need to do this as a separate task as the manpage
output needs to be placed in a different location post-install to the
html output (/usr/local/share/man vs /usr/local/share/doc/).

Changes required are:
* Add configurable options for manpage output and html output to the
doxygen config template. (Remove option for html output path as it's
always "html")
* Modify API meson.build file to configure two separate doxygen config
files, for HTML and manpages respectively.
* Change doxygen wrapper script to have separate output log files for
the manpage and HTML jobs, to avoid conflicts
* Add "custom_targets" to meson.build file to build the HTML pages and
the manpages, with individual install locations for each.
* Where supported by meson version, call "mandb" post-install to update
the man database to ensure the new manpages can be found. If the
manpages are not installed in system location i.e. one not in MANPATH,
then this update will have no effect, as only system locations are
scanned.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Morten Brørup <mb@smartsharesystems.com>

show more ...

remove KNI

The KNI driver had design flaws such as calling userspace with kernel
mutex held that made it prone to deadlock. The design also introduced
security risks because the kernel driver truste

remove KNI

The KNI driver had design flaws such as calling userspace with kernel
mutex held that made it prone to deadlock. The design also introduced
security risks because the kernel driver trusted the userspace
(DPDK) kni interface. The kernel driver was never reviewed by
the upstream kernel community and would never have been accepted.

And since the Linux kernel API is not stable, it was a continual
source of maintenance issues especially with distribution kernels.

There are better ways to inject packets into the kernel such as
virtio_user, tap and XDP drivers. All of these do not need out of
tree kernel drivers.

The deprecation was announced in 22.11 release (see links for the
the techboard discussions); and users were directed to alternatives
there.

Link: https://mails.dpdk.org/archives/dev/2021-January/197077.html
Link: https://mails.dpdk.org/archives/dev/2022-June/243596.html

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>

show more ...

mempool: deprecate unused physical page defines

MEMPOOL_PG_NUM_DEFAULT and MEMPOOL_PG_SHIFT_MAX are not used.

Fixes: fd943c764a63 ("mempool: deprecate xmem functions")

Signed-off-by: Andrew Rybche

mempool: deprecate unused physical page defines

MEMPOOL_PG_NUM_DEFAULT and MEMPOOL_PG_SHIFT_MAX are not used.

Fixes: fd943c764a63 ("mempool: deprecate xmem functions")

Signed-off-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
Acked-by: Olivier Matz <olivier.matz@6wind.com>

show more ...

doc: show how to include code in guides

Currently the documentation describes how to add code snippets to the
docs using code blocks. This can be problematic as the code snippets
in the docs may fal

doc: show how to include code in guides

Currently the documentation describes how to add code snippets to the
docs using code blocks. This can be problematic as the code snippets
in the docs may fall out of sync with the actual code it is referencing
within DPDK. This patch adds instructions to the contribution guide
about how to include code in the docs using literalinclude which will
dynamically get the code from source when the docs are generated. This
will help to ensure that the code within the docs is up to date and not
out of sync with the actual code.

Signed-off-by: Conor Walsh <conor.walsh@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: David Marchand <david.marchand@redhat.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

show more ...

doc: remove PDF requirements

The documentation is generated in HTML only.
The PDF format is abandoned since DPDK 20.11
while dropping support of the make-based build.

This decision has been mention

doc: remove PDF requirements

The documentation is generated in HTML only.
The PDF format is abandoned since DPDK 20.11
while dropping support of the make-based build.

This decision has been mentioned by the Technical Board:
https://mails.dpdk.org/archives/dev/2021-January/195549.html

Fixes: 3cc6ecfdfe85 ("build: remove makefiles")
Cc: stable@dpdk.org

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>

show more ...

lib: remove librte_ prefix from directory names

There is no reason for the DPDK libraries to all have 'librte_' prefix on
the directory names. This prefix makes the directory names longer and also
m

lib: remove librte_ prefix from directory names

There is no reason for the DPDK libraries to all have 'librte_' prefix on
the directory names. This prefix makes the directory names longer and also
makes it awkward to add features referring to individual libraries in the
build - should the lib names be specified with or without the prefix.
Therefore, we can just remove the library prefix and use the library's
unique name as the directory name, i.e. 'eal' rather than 'librte_eal'

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

show more ...

doc: remove references to make from contributing guide

Make is no longer supported for compiling DPDK, references are now
removed in the documentation.

Signed-off-by: Ciara Power <ciara.power@intel

doc: remove references to make from contributing guide

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>

show more ...

doc: remove references to python 2

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,
execut

doc: remove references to python 2

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>

show more ...

doc: prefer https when pointing to dpdk.org

for file in $(git grep -l http://.*dpdk.org doc/); do
sed -i -e 's#http://\(.*dpdk.org\)#https://\1#g' $file;
done

Cc: stable@dpdk.org

Signed-off-by:

doc: prefer https when pointing to dpdk.org

for file in $(git grep -l http://.*dpdk.org doc/); do
sed -i -e 's#http://\(.*dpdk.org\)#https://\1#g' $file;
done

Cc: stable@dpdk.org

Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Kevin Traynor <ktraynor@redhat.com>

show more ...

doc: remove major in designation of normal releases

The word "major" was used to differentiate with release candidates
or stable maintenance releases.
However the word "major" can be understood as "

doc: remove major in designation of normal releases

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>

show more ...

doc: fix PDF with greek letter

For an unknown reason, the sign "μ" is not accepted by some environments,
probably due to the version of some Latex packages or dependencies.

! Package inputenc Erro

doc: fix PDF with greek letter

For an unknown reason, the sign "μ" is not accepted by some environments,
probably due to the version of some Latex packages or dependencies.

! Package inputenc Error: Unicode character μ (U+03BC)
(inputenc) not set up for use with LaTeX.

It is fixed by installing texlive-langgreek.

Fixes: d0dff9ba445e ("doc: sample application user guide")
Cc: stable@dpdk.org

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>

show more ...

doc: fix links to doxygen and sphinx sites

Update broken links, replace with valid links.

Fixes: 7798f17a0d62 ("doc: add documentation guidelines")
Cc: stable@dpdk.org

Signed-off-by: Dekel Peled <

doc: fix links to doxygen and sphinx sites

Update broken links, replace with valid links.

Fixes: 7798f17a0d62 ("doc: add documentation guidelines")
Cc: stable@dpdk.org

Signed-off-by: Dekel Peled <dekelp@mellanox.com>

show more ...

compat: merge compat library into EAL

Since compat library is only a single header, we can easily move it into
the EAL common headers instead of tracking it separately. The downside of
this is that

compat: merge compat library into EAL

Since compat library is only a single header, we can easily move it into
the EAL common headers instead of tracking it separately. The downside of
this is that it becomes a little more difficult to have any libs that are
built before EAL depend on it. Thankfully, this is not a major problem as
the only library which uses rte_compat.h and is built before EAL (kvargs)
already has the path to the compat.h header file explicitly called out as
an include path.

However, to ensure that we don't hit problems later with this, we can add
EAL common headers folder to the global include list in the meson build
which means that all common headers can be safely used by all libraries, no
matter what their build order.

As a side-effect, this patch also fixes an issue with building on BSD using
meson, due to compat lib no longer needing to be listed as a dependency.

Fixes: a8499f65a1d1 ("log: add missing experimental tag")
Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
Tested-by: David Marchand <david.marchand@redhat.com>
Tested-by: Anatoly Burakov <anatoly.burakov@intel.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

show more ...

doc: add dependency for PDF in contributing guide

There is a missing depenency for building docs with "make doc-guides-pdf".
This causes it to break with "make[3]: latexmk: Command not found". This

doc: add dependency for PDF in contributing guide

There is a missing depenency for building docs with "make doc-guides-pdf".
This causes it to break with "make[3]: latexmk: Command not found". This
was observed and reported in https://bugs.dpdk.org/show_bug.cgi?id=182
This patch fixes this issue by adding the latexmk package dependency in
sub-section 4.3.1 of the contributing guide ("Dependencies").

Bugzilla ID: 182
Cc: stable@dpdk.org

Signed-off-by: Rami Rosen <ramirose@gmail.com>

show more ...

fix dpdk.org URLs

The DPDK website has a new URL scheme since June 2018.

Cc: stable@dpdk.org

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>

doc: replace doxygen example in contribution guide

The provided example of doxygen header is about a deprecated function.
It is replaced by rte_spinlock_trylock() which is small and
good enough for

doc: replace doxygen example in contribution guide

The provided example of doxygen header is about a deprecated function.
It is replaced by rte_spinlock_trylock() which is small and
good enough for the purpose.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>

show more ...

doc: update commands for virtio-user

Update the doc for virtio-user to use the latest testpmd
parameters and commands.

Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
Reviewed-by: Maxime Coquelin <m

doc: update commands for virtio-user

Update the doc for virtio-user to use the latest testpmd
parameters and commands.

Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>

show more ...

doc: add SPDX and copyright to contributing guide

Signed-off-by: Hemant Agrawal <hemant.agrawal@nxp.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

app/testpmd: disable Rx VLAN offloads by default

Removed the hardcoded preconfigured Rx VLAN offload configuration
from testpmd and changed the Rx offload command line parameters from
disable to ena

app/testpmd: disable Rx VLAN offloads by default

Removed the hardcoded preconfigured Rx VLAN offload configuration
from testpmd and changed the Rx offload command line parameters from
disable to enable.

It has been decided by the Technical Board that testers who wish to
use these offloads will now have to explicitly write them in the
command-line when running testpmd.
The agreement is to keep two exceptions enabled by default in 18.02:
Rx CRC strip and Tx fast free.

Motivation:
Some PMDs such at the mlx4 may not implement all the offloads.
After the offload API rework assuming no offload is enabled by default,
commit ce17eddefc20 ("ethdev: introduce Rx queue offloads API")
commit cba7f53b717d ("ethdev: introduce Tx queue offloads API") trying
to enable a not supported offload is clearly an error which will cause
configuration failing.

Considering that testpmd is an application to test the PMD, it should
not fail on a configuration which was not explicitly requested.
The behavior of this test application is then turned to an opt-in
model.

Signed-off-by: Moti Haimovsky <motih@mellanox.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

show more ...

eal: remove Xen dom0 support

We remove xen-specific code in EAL, including the option --xen-dom0,
memory initialization code, compiling dependency, etc.

Related documents are removed or updated, an

eal: remove Xen dom0 support

We remove xen-specific code in EAL, including the option --xen-dom0,
memory initialization code, compiling dependency, etc.

Related documents are removed or updated, and bump the eal library
version.

Signed-off-by: Jianfeng Tan <jianfeng.tan@intel.com>

show more ...

doc: change line length limit in contributors guide

The DPDK documentation guidelines state that lines should be wrapped as
follows:

* The recommended style for the DPDK documentation is to put sen

doc: change line length limit in contributors guide

The DPDK documentation guidelines state that lines should be wrapped as
follows:

* The recommended style for the DPDK documentation is to put sentences on
separate lines. This allows for easier reviewing of patches. ...
* Long sentences should be wrapped at 120 characters +/- 10 characters.
They should be wrapped at words.

http://dpdk.org/doc/guides/contributing/documentation.html#line-length

However, in practice, users almost never submit doc patches in this format.
Instead most users wrap their doc patches at 80 characters.

This patch updates the documentation contributors guide to reflect this
as the recommended guideline.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
Reviewed-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>
Reviewed-by: Shreyansh Jain <shreyansh.jain@nxp.com>

show more ...

doc: use corelist instead of coremask

The coremask option in DPDK is difficult to use and we should be
promoting the use of the corelist (-l) option. The patch
adjusts the docs to use -l EAL option

doc: use corelist instead of coremask

The coremask option in DPDK is difficult to use and we should be
promoting the use of the corelist (-l) option. The patch
adjusts the docs to use -l EAL option instead of the -c option.

The patch only changes the docs and not the code as the -c option
will continue to exist unless it is removed in the future. The -c
option should be kept to maintain backward compatibility.

Signed-off-by: Keith Wiles <keith.wiles@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>

show more ...