[dpdk-dev] [PATCH 0/8] GSG Documentation updates

[dpdk-dev] [PATCH 0/8] GSG Documentation updates

[Bruce Richardson]

This patchset includes documentation updates for both the Linux and
FreeBSD Getting Started Guide Docs. The majority of changes are to add
information on building using meson and ninja, with some additional
cleanups being performed at the same time.

Bruce Richardson (8):
  doc: update Linux GSG system requirements section
  doc: add building with meson to linux GSG
  doc: reorder meson and make build instructions for arm
  doc: remove reference to old versions of FreeBSD
  doc: update examples output in FreeBSD GSG
  doc: add meson install instructions for FreeBSD
  doc: update documentation on build and running FreeBSD apps
  doc: drop EAL command-line reference from FreeBSD GSG

 doc/guides/freebsd_gsg/build_dpdk.rst         | 164 +++++-------------
 doc/guides/freebsd_gsg/build_sample_apps.rst  | 118 +++----------
 .../freebsd_gsg/freebsd_eal_parameters.rst    |  20 ---
 doc/guides/freebsd_gsg/index.rst              |   1 -
 doc/guides/freebsd_gsg/install_from_ports.rst |  62 +++----
 doc/guides/linux_gsg/build_dpdk.rst           |  94 +++++++++-
 .../linux_gsg/cross_build_dpdk_for_arm64.rst  |  32 ++--
 doc/guides/linux_gsg/sys_reqs.rst             |  64 +++----
 8 files changed, 228 insertions(+), 327 deletions(-)
 delete mode 100644 doc/guides/freebsd_gsg/freebsd_eal_parameters.rst

-- 
2.21.0

[dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Bruce Richardson]

Update the system requirements section of the doc to cover builds with
meson and ninja. This involves updating the package dependencies to include
meson, ninja and python 3.5, and also updating the optional dependencies
section to explain that the components are enabled/disabled automatically
by meson.

As part of this update, the relevant sections were simplified to keep the
document shorter. For mandatory requirements, we can refer to the various
distro's development tools package groups rather than requiring gcc, core
tools etc. individually. The optional package list was very incomplete, and
if complete would duplicate information in the individual driver's guides.
Therefore we can simplify it by listing only the library optional
requirements and referring users to the driver docs to find details on
their dependencies.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 64 +++++++++++++++----------------
 1 file changed, 32 insertions(+), 32 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index d2359058b..c0b696069 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -37,32 +37,22 @@ Compilation of the DPDK
     The setup commands and installed packages needed on various systems may be different.
     For details on Linux distributions and the versions tested, please consult the DPDK Release Notes.
 
-*   GNU ``make``.
+*   General development tools including ``make``, and a supported C compiler such as ``gcc`` or ``clang``.
 
-*   coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc.
+    * For Red Hat/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
 
-*   gcc: versions 4.9 or later is recommended for all platforms.
-    On some distributions, some specific compiler flags and linker flags are enabled by
-    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
-    of your distribution and to ``gcc -dumpspecs``.
+    * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
 
-*   libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``;
-    ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture;
-    ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;)
+*   Python, recommended version 3.5+.
 
-*   Linux kernel headers or sources required to build kernel modules. (kernel - devel.x86_64;
-    kernel - devel.ppc64)
+    * Python v3.5+ is needed to build DPDK using meson and ninja
 
-*   Additional packages required for 32-bit compilation on 64-bit systems are:
+    * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
 
-    * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64;
+*   Meson (v0.47.1+) and ninja
 
-    * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64;
-
-    .. note::
-
-       x86_x32 ABI is currently supported with distribution packages only on Ubuntu
-       higher than 13.10 or recent Debian distribution. The only supported  compiler is gcc 4.9+.
+    * Recommended to use the latest versions from Python's "pip" repository:
+      ``pip3 install meson ninja``
 
 *   Library for handling NUMA (Non Uniform Memory Access).
 
@@ -70,16 +60,7 @@ Compilation of the DPDK
 
     * libnuma-dev in Debian/Ubuntu;
 
-    .. note::
-
-        On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`)
-        is a recommended dependency when `--legacy-mem` switch is used,
-        and a *required* dependency if default memory mode is used.
-        While DPDK will compile and run without `libnuma`
-        even on NUMA-enabled systems,
-        both usability and performance will be degraded.
-
-*   Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
+*   Linux kernel headers or sources required to build kernel modules.
 
 .. note::
 
@@ -96,10 +77,29 @@ Compilation of the DPDK
     which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
     it, see the IBM official installation document.
 
-*   libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
-    This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file.
+**Additional Libraries**
+
+A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
+For DPDK builds using meson, the presence or absence of these dependencies will be
+automatically detected enabling or disabling the relevant components appropriately.
+
+For builds using make, these components are disabled in the default configuration and
+need to be enabled manually my changing the relevant setting to "y" in the build configuration file
+i.e. the ``.config`` file in the build folder.
+
+In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
+
+For libraries the additional dependencies include:
+
+*   libarchive: for some unit tests using tar to get their resources.
+
+*   jansson: to compile and use the telemetry library.
+
+*   libelf: to compile and use the bpf library.
 
-*   libarchive headers and library are needed for some unit tests using tar to get their resources.
+For poll-mode drivers, the additional dependencies for each driver can be
+found in that driver's documentation in the relevant DPDK guide document,
+e.g. Network Interface Controller Drivers Guide
 
 
 Running DPDK Applications
-- 
2.21.0

Re: [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Thomas Monjalon]

22/11/2019 17:03, Bruce Richardson:
> Update the system requirements section of the doc to cover builds with
> meson and ninja. This involves updating the package dependencies to include
> meson, ninja and python 3.5, and also updating the optional dependencies
> section to explain that the components are enabled/disabled automatically
> by meson.
> 
> As part of this update, the relevant sections were simplified to keep the
> document shorter. For mandatory requirements, we can refer to the various
> distro's development tools package groups rather than requiring gcc, core
> tools etc. individually. The optional package list was very incomplete, and
> if complete would duplicate information in the individual driver's guides.
> Therefore we can simplify it by listing only the library optional
> requirements and referring users to the driver docs to find details on
> their dependencies.

I agree with the intent.

[...]
> -*   GNU ``make``.
> +*   General development tools including ``make``, and a supported C compiler such as ``gcc`` or ``clang``.

Why referring to make and not meson?

> -*   coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc.
> +    * For Red Hat/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
> +    * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``

OK, this is very basic :)

> -*   gcc: versions 4.9 or later is recommended for all platforms.
> -    On some distributions, some specific compiler flags and linker flags are enabled by
> -    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
> -    of your distribution and to ``gcc -dumpspecs``.

I think we need to keep some compiler requirement somewhere.
What do you suggest?

> -*   libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``;
> -    ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture;
> -    ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;)
[...]
> -*   Additional packages required for 32-bit compilation on 64-bit systems are:
> -    * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64;
> -    * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64;

OK to drop libc requirements.

> -    .. note::
> -
> -       x86_x32 ABI is currently supported with distribution packages only on Ubuntu
> -       higher than 13.10 or recent Debian distribution. The only supported  compiler is gcc 4.9+.

No note at all about x32?
Do we know how it is supported?

> +*   Python, recommended version 3.5+.
> +    * Python v3.5+ is needed to build DPDK using meson and ninja

We cannot use meson at all with older Python?

> -*   Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
> +    * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.

I didn't know about 3.2 for scripts. Any special reason?

> +*   Meson (v0.47.1+) and ninja
>  
> +    * Recommended to use the latest versions from Python's "pip" repository:
> +      ``pip3 install meson ninja``

Why recommending pip? Is 0.47.1 enough?

> -    .. note::
> -
> -        On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`)
> -        is a recommended dependency when `--legacy-mem` switch is used,
> -        and a *required* dependency if default memory mode is used.
> -        While DPDK will compile and run without `libnuma`
> -        even on NUMA-enabled systems,
> -        both usability and performance will be degraded.

I think libnuma is worth to be mentioned here as it is an EAL dependency.

> +*   Linux kernel headers or sources required to build kernel modules.

This one is obvious, OK.

> -*   libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
> -    This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file.

OK to drop PMD-specific requirement.

> +**Additional Libraries**
> +
> +A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
> +For DPDK builds using meson, the presence or absence of these dependencies will be
> +automatically detected enabling or disabling the relevant components appropriately.
> +
> +For builds using make, these components are disabled in the default configuration and
> +need to be enabled manually my changing the relevant setting to "y" in the build configuration file

typo: s/my/by/

> +i.e. the ``.config`` file in the build folder.
> +
> +In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
> +
> +For libraries the additional dependencies include:
> +
> +*   libarchive: for some unit tests using tar to get their resources.
> +
> +*   jansson: to compile and use the telemetry library.
> +
> +*   libelf: to compile and use the bpf library.

I think these optional dependencies could go away, thanks to the text
you added above and below.

> +For poll-mode drivers, the additional dependencies for each driver can be
> +found in that driver's documentation in the relevant DPDK guide document,
> +e.g. Network Interface Controller Drivers Guide

Please use a link here.
You could also link the prog guide if talking about libraries.

Re: [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Bruce Richardson]

On Thu, Nov 28, 2019 at 12:51:27PM +0100, Thomas Monjalon wrote:
> 22/11/2019 17:03, Bruce Richardson:
> > Update the system requirements section of the doc to cover builds with
> > meson and ninja. This involves updating the package dependencies to include
> > meson, ninja and python 3.5, and also updating the optional dependencies
> > section to explain that the components are enabled/disabled automatically
> > by meson.
> > 
> > As part of this update, the relevant sections were simplified to keep the
> > document shorter. For mandatory requirements, we can refer to the various
> > distro's development tools package groups rather than requiring gcc, core
> > tools etc. individually. The optional package list was very incomplete, and
> > if complete would duplicate information in the individual driver's guides.
> > Therefore we can simplify it by listing only the library optional
> > requirements and referring users to the driver docs to find details on
> > their dependencies.
> 
> I agree with the intent.
> 

And thanks for the review.

> [...]
> > -*   GNU ``make``.
> > +*   General development tools including ``make``, and a supported C compiler such as ``gcc`` or ``clang``.
> 
> Why referring to make and not meson?

Because even with meson build we still use make for building kernel
modules, and this first bullet item is all about getting the basic build
packages which come from build-essential etc. Make is part of that build
tools group on distros, meson and ninja are not.

> 
> > -*   coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc.
> > +    * For Red Hat/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
> > +    * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
> 
> OK, this is very basic :)

That's the intent. No point in asking the user to get gcc and coreutils
etc. individually when packagers give us a shortcut :-)

> 
> > -*   gcc: versions 4.9 or later is recommended for all platforms.
> > -    On some distributions, some specific compiler flags and linker flags are enabled by
> > -    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
> > -    of your distribution and to ``gcc -dumpspecs``.
> 
> I think we need to keep some compiler requirement somewhere.
> What do you suggest?

I'm happy to keep this compiler requirements in here. Is 4.9 still
regularly tested with DPDK to ensure it works? Also, if we put in a GCC
requirement, do we not also need to put in a clang one? For recent distros
is this really something most users need to worry about?

> 
> > -*   libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``;
> > -    ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture;
> > -    ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;)
> [...]
> > -*   Additional packages required for 32-bit compilation on 64-bit systems are:
> > -    * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64;
> > -    * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64;
> 
> OK to drop libc requirements.
> 
> > -    .. note::
> > -
> > -       x86_x32 ABI is currently supported with distribution packages only on Ubuntu
> > -       higher than 13.10 or recent Debian distribution. The only supported  compiler is gcc 4.9+.
> 
> No note at all about x32?
> Do we know how it is supported?
> 

I'm not sure myself, and I'm also not certain if it is still used. However,
even if it is used/supported, I'm not sure references belong in a getting
started guide, which should only cover the basics really.

> > +*   Python, recommended version 3.5+.
> > +    * Python v3.5+ is needed to build DPDK using meson and ninja
> 
> We cannot use meson at all with older Python?
> 

Definitly not with python2, and I believe python 3.5 is the minimum
supported version.

> > -*   Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
> > +    * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
> 
> I didn't know about 3.2 for scripts. Any special reason?
> 

No idea. It is what was in the doc, so I just left it. Happy to take
updates to this. When python 2 EOLs next year, we should probably drop all
support and references to it.

> > +*   Meson (v0.47.1+) and ninja
> >  
> > +    * Recommended to use the latest versions from Python's "pip" repository:
> > +      ``pip3 install meson ninja``
> 
> Why recommending pip? Is 0.47.1 enough?
> 

It is enough, this was done again in the interests of simplification -
rather than worry about what versions are in what distro and having the
user check, it simplifies things if everyone just uses pip, which is why I
recommend it.

> > -    .. note::
> > -
> > -        On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`)
> > -        is a recommended dependency when `--legacy-mem` switch is used,
> > -        and a *required* dependency if default memory mode is used.
> > -        While DPDK will compile and run without `libnuma`
> > -        even on NUMA-enabled systems,
> > -        both usability and performance will be degraded.
> 
> I think libnuma is worth to be mentioned here as it is an EAL dependency.

It is mentioned. This just takes out the note about mandatory vs optional
for different memory systems. After this patch the output still includes in
the mandatory dependencies section:

	Library for handling NUMA (Non Uniform Memory Access).
	* numactl-devel in Red Hat/Fedora;
	* libnuma-dev in Debian/Ubuntu;

So again we simplify to just saying to get libnuma rather that having the
user worry about different memory systems.

> 
> > +*   Linux kernel headers or sources required to build kernel modules.
> 
> This one is obvious, OK.
> 
> > -*   libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
> > -    This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file.
> 
> OK to drop PMD-specific requirement.
> 
> > +**Additional Libraries**
> > +
> > +A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
> > +For DPDK builds using meson, the presence or absence of these dependencies will be
> > +automatically detected enabling or disabling the relevant components appropriately.
> > +
> > +For builds using make, these components are disabled in the default configuration and
> > +need to be enabled manually my changing the relevant setting to "y" in the build configuration file
> 
> typo: s/my/by/
> 
> > +i.e. the ``.config`` file in the build folder.
> > +
> > +In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
> > +
> > +For libraries the additional dependencies include:
> > +
> > +*   libarchive: for some unit tests using tar to get their resources.
> > +
> > +*   jansson: to compile and use the telemetry library.
> > +
> > +*   libelf: to compile and use the bpf library.
> 
> I think these optional dependencies could go away, thanks to the text
> you added above and below.
> 

I'd actually rather keep them here. While we could refer to the programmers
guide, there are a lot of libraries and only 3 optional dependencies, so
I'd rather explicitly list them here.

For drivers, the dependency list would be huge, so I'm just going to refer
to the PMD guide for that.

> > +For poll-mode drivers, the additional dependencies for each driver can be
> > +found in that driver's documentation in the relevant DPDK guide document,
> > +e.g. Network Interface Controller Drivers Guide
> 
> Please use a link here.

Ok.

> You could also link the prog guide if talking about libraries.
> 

I can add one, but I still think it's worth listing the 3 additional deps.
:-)

/Bruce

Re: [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Thomas Monjalon]

28/11/2019 15:11, Bruce Richardson:
> On Thu, Nov 28, 2019 at 12:51:27PM +0100, Thomas Monjalon wrote:
> > 22/11/2019 17:03, Bruce Richardson:
> > [...]
> > > -*   GNU ``make``.
> > > +*   General development tools including ``make``, and a supported C compiler such as ``gcc`` or ``clang``.
> > 
> > Why referring to make and not meson?
> 
> Because even with meson build we still use make for building kernel
> modules, and this first bullet item is all about getting the basic build
> packages which come from build-essential etc. Make is part of that build
> tools group on distros, meson and ninja are not.

OK

> > > -*   gcc: versions 4.9 or later is recommended for all platforms.
> > > -    On some distributions, some specific compiler flags and linker flags are enabled by
> > > -    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
> > > -    of your distribution and to ``gcc -dumpspecs``.
> > 
> > I think we need to keep some compiler requirement somewhere.
> > What do you suggest?
> 
> I'm happy to keep this compiler requirements in here. Is 4.9 still
> regularly tested with DPDK to ensure it works? Also, if we put in a GCC
> requirement, do we not also need to put in a clang one? For recent distros
> is this really something most users need to worry about?

It allows us to know which compiler we must support.
And for distributions, it can help.
I think we should have clang version too.

> > > -    .. note::
> > > -
> > > -       x86_x32 ABI is currently supported with distribution packages only on Ubuntu
> > > -       higher than 13.10 or recent Debian distribution. The only supported  compiler is gcc 4.9+.
> > 
> > No note at all about x32?
> > Do we know how it is supported?
> > 
> 
> I'm not sure myself, and I'm also not certain if it is still used. However,
> even if it is used/supported, I'm not sure references belong in a getting
> started guide, which should only cover the basics really.

OK to drop note about x32.

> > > +*   Python, recommended version 3.5+.
> > > +    * Python v3.5+ is needed to build DPDK using meson and ninja
> > 
> > We cannot use meson at all with older Python?
> > 
> 
> Definitly not with python2, and I believe python 3.5 is the minimum
> supported version.

OK

> > > -*   Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
> > > +    * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
> > 
> > I didn't know about 3.2 for scripts. Any special reason?
> > 
> 
> No idea. It is what was in the doc, so I just left it. Happy to take
> updates to this. When python 2 EOLs next year, we should probably drop all
> support and references to it.

OK

> > > +*   Meson (v0.47.1+) and ninja
> > >  
> > > +    * Recommended to use the latest versions from Python's "pip" repository:
> > > +      ``pip3 install meson ninja``
> > 
> > Why recommending pip? Is 0.47.1 enough?
> 
> It is enough, this was done again in the interests of simplification -
> rather than worry about what versions are in what distro and having the
> user check, it simplifies things if everyone just uses pip, which is why I
> recommend it.

I think we should let users take the responsibility of using their distro
package or pip.
Recommending pip is a little pushy.

> > > -    .. note::
> > > -
> > > -        On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`)
> > > -        is a recommended dependency when `--legacy-mem` switch is used,
> > > -        and a *required* dependency if default memory mode is used.
> > > -        While DPDK will compile and run without `libnuma`
> > > -        even on NUMA-enabled systems,
> > > -        both usability and performance will be degraded.
> > 
> > I think libnuma is worth to be mentioned here as it is an EAL dependency.
> 
> It is mentioned. This just takes out the note about mandatory vs optional
> for different memory systems. After this patch the output still includes in
> the mandatory dependencies section:
> 
> 	Library for handling NUMA (Non Uniform Memory Access).
> 	* numactl-devel in Red Hat/Fedora;
> 	* libnuma-dev in Debian/Ubuntu;
> 
> So again we simplify to just saying to get libnuma rather that having the
> user worry about different memory systems.

OK I missed it.

> > > +**Additional Libraries**
> > > +
> > > +A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
> > > +For DPDK builds using meson, the presence or absence of these dependencies will be
> > > +automatically detected enabling or disabling the relevant components appropriately.
> > > +
> > > +For builds using make, these components are disabled in the default configuration and
> > > +need to be enabled manually my changing the relevant setting to "y" in the build configuration file
> > 
> > typo: s/my/by/
> > 
> > > +i.e. the ``.config`` file in the build folder.
> > > +
> > > +In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
> > > +
> > > +For libraries the additional dependencies include:
> > > +
> > > +*   libarchive: for some unit tests using tar to get their resources.
> > > +
> > > +*   jansson: to compile and use the telemetry library.
> > > +
> > > +*   libelf: to compile and use the bpf library.
> > 
> > I think these optional dependencies could go away, thanks to the text
> > you added above and below.
> 
> I'd actually rather keep them here. While we could refer to the programmers
> guide, there are a lot of libraries and only 3 optional dependencies, so
> I'd rather explicitly list them here.
> 
> For drivers, the dependency list would be huge, so I'm just going to refer
> to the PMD guide for that.
> 
> > > +For poll-mode drivers, the additional dependencies for each driver can be
> > > +found in that driver's documentation in the relevant DPDK guide document,
> > > +e.g. Network Interface Controller Drivers Guide
> > 
> > Please use a link here.
> 
> Ok.
> 
> > You could also link the prog guide if talking about libraries.
> > 
> 
> I can add one, but I still think it's worth listing the 3 additional deps.
> :-)

OK, no strong opinion.

Re: [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Bruce Richardson]

On Thu, Nov 28, 2019 at 03:22:05PM +0100, Thomas Monjalon wrote:
> 28/11/2019 15:11, Bruce Richardson:
> > On Thu, Nov 28, 2019 at 12:51:27PM +0100, Thomas Monjalon wrote:
> > > 22/11/2019 17:03, Bruce Richardson:
> > > [...]
> > > > -*   GNU ``make``.
> > > > +*   General development tools including ``make``, and a supported C compiler such as ``gcc`` or ``clang``.
> > > 
> > > Why referring to make and not meson?
> > 
> > Because even with meson build we still use make for building kernel
> > modules, and this first bullet item is all about getting the basic build
> > packages which come from build-essential etc. Make is part of that build
> > tools group on distros, meson and ninja are not.
> 
> OK
> 
> > > > -*   gcc: versions 4.9 or later is recommended for all platforms.
> > > > -    On some distributions, some specific compiler flags and linker flags are enabled by
> > > > -    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
> > > > -    of your distribution and to ``gcc -dumpspecs``.
> > > 
> > > I think we need to keep some compiler requirement somewhere.
> > > What do you suggest?
> > 
> > I'm happy to keep this compiler requirements in here. Is 4.9 still
> > regularly tested with DPDK to ensure it works? Also, if we put in a GCC
> > requirement, do we not also need to put in a clang one? For recent distros
> > is this really something most users need to worry about?
> 
> It allows us to know which compiler we must support.
> And for distributions, it can help.
> I think we should have clang version too.
> 

Ok, I'll add 4.9 recommendation in V2. If we have a minimum clang version
you want included, I can add that too, if someone gets it to me in time :-)

<snip>
> > > > +*   Meson (v0.47.1+) and ninja
> > > >  
> > > > +    * Recommended to use the latest versions from Python's "pip" repository:
> > > > +      ``pip3 install meson ninja``
> > > 
> > > Why recommending pip? Is 0.47.1 enough?
> > 
> > It is enough, this was done again in the interests of simplification -
> > rather than worry about what versions are in what distro and having the
> > user check, it simplifies things if everyone just uses pip, which is why I
> > recommend it.
> 
> I think we should let users take the responsibility of using their distro
> package or pip.
> Recommending pip is a little pushy.
> 

Ok, will add possibility of using distro packages in V2.

<snip>

Re: [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Thomas Monjalon]

28/11/2019 15:30, Bruce Richardson:
> On Thu, Nov 28, 2019 at 03:22:05PM +0100, Thomas Monjalon wrote:
> > 28/11/2019 15:11, Bruce Richardson:
> > > On Thu, Nov 28, 2019 at 12:51:27PM +0100, Thomas Monjalon wrote:
> > > > 22/11/2019 17:03, Bruce Richardson:
> > > > > -*   gcc: versions 4.9 or later is recommended for all platforms.
> > > > > -    On some distributions, some specific compiler flags and linker flags are enabled by
> > > > > -    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
> > > > > -    of your distribution and to ``gcc -dumpspecs``.
> > > > 
> > > > I think we need to keep some compiler requirement somewhere.
> > > > What do you suggest?
> > > 
> > > I'm happy to keep this compiler requirements in here. Is 4.9 still
> > > regularly tested with DPDK to ensure it works? Also, if we put in a GCC
> > > requirement, do we not also need to put in a clang one? For recent distros
> > > is this really something most users need to worry about?
> > 
> > It allows us to know which compiler we must support.
> > And for distributions, it can help.
> > I think we should have clang version too.
> > 
> 
> Ok, I'll add 4.9 recommendation in V2. If we have a minimum clang version
> you want included, I can add that too, if someone gets it to me in time :-)

I don't know for clang.
Ali, any clue about minimal version?

> <snip>
> > > > > +*   Meson (v0.47.1+) and ninja
> > > > >  
> > > > > +    * Recommended to use the latest versions from Python's "pip" repository:
> > > > > +      ``pip3 install meson ninja``
> > > > 
> > > > Why recommending pip? Is 0.47.1 enough?
> > > 
> > > It is enough, this was done again in the interests of simplification -
> > > rather than worry about what versions are in what distro and having the
> > > user check, it simplifies things if everyone just uses pip, which is why I
> > > recommend it.
> > 
> > I think we should let users take the responsibility of using their distro
> > package or pip.
> > Recommending pip is a little pushy.
> > 
> 
> Ok, will add possibility of using distro packages in V2.

I think removing the pip recommendation is enough.
Or reword to make it not warmly recommended.

Re: [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section

[Bruce Richardson]

On Thu, Nov 28, 2019 at 03:34:54PM +0100, Thomas Monjalon wrote:
> 28/11/2019 15:30, Bruce Richardson:
> > On Thu, Nov 28, 2019 at 03:22:05PM +0100, Thomas Monjalon wrote:
> > > 28/11/2019 15:11, Bruce Richardson:
> > > > On Thu, Nov 28, 2019 at 12:51:27PM +0100, Thomas Monjalon wrote:
> > > > > 22/11/2019 17:03, Bruce Richardson:
> > > > > > -*   gcc: versions 4.9 or later is recommended for all platforms.
> > > > > > -    On some distributions, some specific compiler flags and linker flags are enabled by
> > > > > > -    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
> > > > > > -    of your distribution and to ``gcc -dumpspecs``.
> > > > > 
> > > > > I think we need to keep some compiler requirement somewhere.
> > > > > What do you suggest?
> > > > 
> > > > I'm happy to keep this compiler requirements in here. Is 4.9 still
> > > > regularly tested with DPDK to ensure it works? Also, if we put in a GCC
> > > > requirement, do we not also need to put in a clang one? For recent distros
> > > > is this really something most users need to worry about?
> > > 
> > > It allows us to know which compiler we must support.
> > > And for distributions, it can help.
> > > I think we should have clang version too.
> > > 
> > 
> > Ok, I'll add 4.9 recommendation in V2. If we have a minimum clang version
> > you want included, I can add that too, if someone gets it to me in time :-)
> 
> I don't know for clang.
> Ali, any clue about minimal version?
> 

I just tested with a CentOS VM and got a clean build with clang 3.4.2, so
I'll put 3.4 as minimum then.

[dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Bruce Richardson]

Add instructions on building DPDK and using the pkg-config file to the
linux GSG.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/build_dpdk.rst | 94 +++++++++++++++++++++++++++--
 1 file changed, 90 insertions(+), 4 deletions(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 7c0329fcc..5710effbc 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -11,8 +11,8 @@ Compiling the DPDK Target from Source
     Parts of this process can also be done using the setup script described in
     the :ref:`linux_setup_script` section of this document.
 
-Install the DPDK and Browse Sources
------------------------------------
+Uncompress DPDK and Browse Sources
+----------------------------------
 
 First, uncompress the archive and move to the uncompressed DPDK source directory:
 
@@ -33,8 +33,94 @@ The DPDK is composed of several directories:
 
 *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
 
-Installation of DPDK Target Environments
-----------------------------------------
+Compiling and Installing DPDK System-wide
+-----------------------------------------
+
+DPDK can be configured, built and installed on your system using the tools
+``meson`` and ``ninja``.
+
+.. note::
+
+  The older makefile-based build system used in older DPDK releases is
+  still present and it's use is described in section
+  `Installation of DPDK Target Environment using Make`_.
+
+DPDK Configuration
+~~~~~~~~~~~~~~~~~~
+
+To configure a DPDK build use:
+
+.. code-block:: console
+
+     meson <options> build
+
+where "build" is the desired output build directory, and "<options>" can be
+empty or one of a number of meson or DPDK-specific build options, described
+later in this section. The configuration process will finish with a summary
+of what DPDK libraries and drivers are to be built and installed, and for
+each item disabled, a reason why that is the case. This information can be
+used, for example, to identify any missing required packages for a driver.
+
+Once configured, to build and then install DPDK system-wide use:
+
+.. code-block:: console
+
+        cd build
+        ninja
+        ninja install
+
+Adjusting Build Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+DPDK has a number of options that can be adjusted as part of the build configuration process.
+These options can be listed by running ``meson configure`` inside a configured build folder.
+Many of these options come from the "meson" tool itself and can be seen documented on the
+`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
+
+For example, to change the build-type from the default, "debugoptimized",
+to a regular "debug" build, you can either:
+
+* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
+
+Other options are specific to the DPDK project but can be adjusted similarly.
+To set the "max_lcores" value to 256, for example, you can either:
+
+* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
+
+Building Applications Using Installed DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
+It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
+for DPDK into the application build process.
+
+An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
+A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
+and the sources for that build are stored in ``$(SRCS-y)``.
+
+.. code-block:: makefile
+
+        PKGCONF = pkg-config
+
+        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
+        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
+
+        $(APP): $(SRCS-y) Makefile
+                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
+
+
+Installation of DPDK Target Environment using Make
+--------------------------------------------------
+
+.. note::
+
+   The building of DPDK using make will be deprecated in a future release. It
+   is therefore recommended that DPDK installation is done using meson and
+   ninja as described above.
 
 The format of a DPDK target is::
 
-- 
2.21.0

Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Burakov, Anatoly]

On 22-Nov-19 4:03 PM, Bruce Richardson wrote:
> Add instructions on building DPDK and using the pkg-config file to the
> linux GSG.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>   doc/guides/linux_gsg/build_dpdk.rst | 94 +++++++++++++++++++++++++++--
>   1 file changed, 90 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
> index 7c0329fcc..5710effbc 100644
> --- a/doc/guides/linux_gsg/build_dpdk.rst
> +++ b/doc/guides/linux_gsg/build_dpdk.rst
> @@ -11,8 +11,8 @@ Compiling the DPDK Target from Source
>       Parts of this process can also be done using the setup script described in
>       the :ref:`linux_setup_script` section of this document.
>   
> -Install the DPDK and Browse Sources
> ------------------------------------
> +Uncompress DPDK and Browse Sources
> +----------------------------------
>   
>   First, uncompress the archive and move to the uncompressed DPDK source directory:
>   
> @@ -33,8 +33,94 @@ The DPDK is composed of several directories:
>   
>   *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
>   
> -Installation of DPDK Target Environments
> -----------------------------------------
> +Compiling and Installing DPDK System-wide
> +-----------------------------------------
> +
> +DPDK can be configured, built and installed on your system using the tools
> +``meson`` and ``ninja``.
> +
> +.. note::
> +
> +  The older makefile-based build system used in older DPDK releases is
> +  still present and it's use is described in section

*its

> +  `Installation of DPDK Target Environment using Make`_.
> +
> +DPDK Configuration
> +~~~~~~~~~~~~~~~~~~
> +
> +To configure a DPDK build use:
> +
> +.. code-block:: console
> +
> +     meson <options> build
> +
> +where "build" is the desired output build directory, and "<options>" can be
> +empty or one of a number of meson or DPDK-specific build options, described
> +later in this section. The configuration process will finish with a summary
> +of what DPDK libraries and drivers are to be built and installed, and for
> +each item disabled, a reason why that is the case. This information can be
> +used, for example, to identify any missing required packages for a driver.
> +
> +Once configured, to build and then install DPDK system-wide use:
> +
> +.. code-block:: console
> +
> +        cd build
> +        ninja
> +        ninja install
> +
> +Adjusting Build Options
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +DPDK has a number of options that can be adjusted as part of the build configuration process.
> +These options can be listed by running ``meson configure`` inside a configured build folder.
> +Many of these options come from the "meson" tool itself and can be seen documented on the
> +`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
> +
> +For example, to change the build-type from the default, "debugoptimized",
> +to a regular "debug" build, you can either:
> +
> +* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
> +
> +* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
> +
> +Other options are specific to the DPDK project but can be adjusted similarly.
> +To set the "max_lcores" value to 256, for example, you can either:
> +
> +* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
> +
> +* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.

This *very* welcome. It's a pity it's not possible to run these /before/ 
creating a build directory, but i'll take it!

A common source of confusion for people building example apps with meson 
is that, unlike with make, you don't build DPDK first and then build 
examples, you build them all at once. Perhaps it would be worth calling 
this out explicitly?

Also, kinda unrelated to this, but can we add an "all" target that 
actually fails if one of the examples doesn't build? IIRC currently 
it'll just skip through any that don't build, which is not ideal for 
quick compile testing. I mean, obviously apps that don't have their 
dependencies met shouldn't be attempted, but if any /buildable/ examples 
fail to build, i think there should be a way to communicate this without 
having to explicitly call out all example apps in the -Dexamples option. 
(if it currently works that way, disregard!)

> +
> +Building Applications Using Installed DPDK
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
> +It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
> +for DPDK into the application build process.
> +
> +An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
> +A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
> +and the sources for that build are stored in ``$(SRCS-y)``.
> +
> +.. code-block:: makefile
> +
> +        PKGCONF = pkg-config
> +
> +        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
> +        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
> +
> +        $(APP): $(SRCS-y) Makefile
> +                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)

What about a meson-based example?

Also, i think it's worth calling out the fact that (at least as far as i 
know) it's not possible to use DPDK built with meson without installing 
it. With make, it's possible to have RTE_SDK/RTE_TARGET defined, and 
that will work without installing DPDK systemwide, but not with meson.

> +
> +
> +Installation of DPDK Target Environment using Make
> +--------------------------------------------------
> +
> +.. note::
> +
> +   The building of DPDK using make will be deprecated in a future release. It
> +   is therefore recommended that DPDK installation is done using meson and
> +   ninja as described above.
>   
>   The format of a DPDK target is::
>   
> 


-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Bruce Richardson]

On Mon, Nov 25, 2019 at 01:19:13PM +0000, Burakov, Anatoly wrote:
> On 22-Nov-19 4:03 PM, Bruce Richardson wrote:
> > Add instructions on building DPDK and using the pkg-config file to the
> > linux GSG.
> > 
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> >   doc/guides/linux_gsg/build_dpdk.rst | 94 +++++++++++++++++++++++++++--
> >   1 file changed, 90 insertions(+), 4 deletions(-)
> > 
> > diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
> > index 7c0329fcc..5710effbc 100644
> > --- a/doc/guides/linux_gsg/build_dpdk.rst
> > +++ b/doc/guides/linux_gsg/build_dpdk.rst
> > @@ -11,8 +11,8 @@ Compiling the DPDK Target from Source
> >       Parts of this process can also be done using the setup script described in
> >       the :ref:`linux_setup_script` section of this document.
> > -Install the DPDK and Browse Sources
> > ------------------------------------
> > +Uncompress DPDK and Browse Sources
> > +----------------------------------
> >   First, uncompress the archive and move to the uncompressed DPDK source directory:
> > @@ -33,8 +33,94 @@ The DPDK is composed of several directories:
> >   *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
> > -Installation of DPDK Target Environments
> > -----------------------------------------
> > +Compiling and Installing DPDK System-wide
> > +-----------------------------------------
> > +
> > +DPDK can be configured, built and installed on your system using the tools
> > +``meson`` and ``ninja``.
> > +
> > +.. note::
> > +
> > +  The older makefile-based build system used in older DPDK releases is
> > +  still present and it's use is described in section
> 
> *its
> 
Thanks.

> > +  `Installation of DPDK Target Environment using Make`_.
> > +
> > +DPDK Configuration
> > +~~~~~~~~~~~~~~~~~~
> > +
> > +To configure a DPDK build use:
> > +
> > +.. code-block:: console
> > +
> > +     meson <options> build
> > +
> > +where "build" is the desired output build directory, and "<options>" can be
> > +empty or one of a number of meson or DPDK-specific build options, described
> > +later in this section. The configuration process will finish with a summary
> > +of what DPDK libraries and drivers are to be built and installed, and for
> > +each item disabled, a reason why that is the case. This information can be
> > +used, for example, to identify any missing required packages for a driver.
> > +
> > +Once configured, to build and then install DPDK system-wide use:
> > +
> > +.. code-block:: console
> > +
> > +        cd build
> > +        ninja
> > +        ninja install
> > +
> > +Adjusting Build Options
> > +~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +DPDK has a number of options that can be adjusted as part of the build configuration process.
> > +These options can be listed by running ``meson configure`` inside a configured build folder.
> > +Many of these options come from the "meson" tool itself and can be seen documented on the
> > +`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
> > +
> > +For example, to change the build-type from the default, "debugoptimized",
> > +to a regular "debug" build, you can either:
> > +
> > +* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
> > +
> > +* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
> > +
> > +Other options are specific to the DPDK project but can be adjusted similarly.
> > +To set the "max_lcores" value to 256, for example, you can either:
> > +
> > +* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
> > +
> > +* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
> 
> This *very* welcome. It's a pity it's not possible to run these /before/
> creating a build directory, but i'll take it!
> 

Can you clarify what you mean here? Passing max_lcores to the initial meson
run isn't sufficient, you think?

> A common source of confusion for people building example apps with meson is
> that, unlike with make, you don't build DPDK first and then build examples,
> you build them all at once. Perhaps it would be worth calling this out
> explicitly?
> 
I was actually thinking that that functionality was primarily targeted at
developers rather than at end users. However, I can include the -Dexamples
flag for reference here for people.

> Also, kinda unrelated to this, but can we add an "all" target that actually
> fails if one of the examples doesn't build? IIRC currently it'll just skip
> through any that don't build, which is not ideal for quick compile testing.
> I mean, obviously apps that don't have their dependencies met shouldn't be
> attempted, but if any /buildable/ examples fail to build, i think there
> should be a way to communicate this without having to explicitly call out
> all example apps in the -Dexamples option. (if it currently works that way,
> disregard!)

This should indeed be the way it currently works. The examples to be built
depends upon the detected dependencies at configure time, but thereafter on
compile, ninja knows nothing about examples or otherwise, it just sees code
to be compiled and linked and should error out if anything fails. If this
is not the case, it's a bug we need to fix.

> 
> > +
> > +Building Applications Using Installed DPDK
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
> > +It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
> > +for DPDK into the application build process.
> > +
> > +An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
> > +A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
> > +and the sources for that build are stored in ``$(SRCS-y)``.
> > +
> > +.. code-block:: makefile
> > +
> > +        PKGCONF = pkg-config
> > +
> > +        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
> > +        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
> > +
> > +        $(APP): $(SRCS-y) Makefile
> > +                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
> 
> What about a meson-based example?
> 
I didn't think such a thing would be work including, since the number of
end-user apps using meson is likely fairly small. We'd also then need to
include an example using cmake or other build systems too, for
completeness.

> Also, i think it's worth calling out the fact that (at least as far as i
> know) it's not possible to use DPDK built with meson without installing it.
> With make, it's possible to have RTE_SDK/RTE_TARGET defined, and that will
> work without installing DPDK systemwide, but not with meson.
> 
It's probably possible, but I've never looked into the details of it. I'll
add a note requiring installation of DPDK for linking to the documentation.

> > +
> > +
> > +Installation of DPDK Target Environment using Make
> > +--------------------------------------------------
> > +
> > +.. note::
> > +
> > +   The building of DPDK using make will be deprecated in a future release. It
> > +   is therefore recommended that DPDK installation is done using meson and
> > +   ninja as described above.
> >   The format of a DPDK target is::
> > 
> 

Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Burakov, Anatoly]

On 25-Nov-19 1:27 PM, Bruce Richardson wrote:
> On Mon, Nov 25, 2019 at 01:19:13PM +0000, Burakov, Anatoly wrote:
>> On 22-Nov-19 4:03 PM, Bruce Richardson wrote:
>>> Add instructions on building DPDK and using the pkg-config file to the
>>> linux GSG.
>>>
>>> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
>>> ---
>>>    doc/guides/linux_gsg/build_dpdk.rst | 94 +++++++++++++++++++++++++++--
>>>    1 file changed, 90 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
>>> index 7c0329fcc..5710effbc 100644
>>> --- a/doc/guides/linux_gsg/build_dpdk.rst
>>> +++ b/doc/guides/linux_gsg/build_dpdk.rst
>>> @@ -11,8 +11,8 @@ Compiling the DPDK Target from Source
>>>        Parts of this process can also be done using the setup script described in
>>>        the :ref:`linux_setup_script` section of this document.
>>> -Install the DPDK and Browse Sources
>>> ------------------------------------
>>> +Uncompress DPDK and Browse Sources
>>> +----------------------------------
>>>    First, uncompress the archive and move to the uncompressed DPDK source directory:
>>> @@ -33,8 +33,94 @@ The DPDK is composed of several directories:
>>>    *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
>>> -Installation of DPDK Target Environments
>>> -----------------------------------------
>>> +Compiling and Installing DPDK System-wide
>>> +-----------------------------------------
>>> +
>>> +DPDK can be configured, built and installed on your system using the tools
>>> +``meson`` and ``ninja``.
>>> +
>>> +.. note::
>>> +
>>> +  The older makefile-based build system used in older DPDK releases is
>>> +  still present and it's use is described in section
>>
>> *its
>>
> Thanks.
> 
>>> +  `Installation of DPDK Target Environment using Make`_.
>>> +
>>> +DPDK Configuration
>>> +~~~~~~~~~~~~~~~~~~
>>> +
>>> +To configure a DPDK build use:
>>> +
>>> +.. code-block:: console
>>> +
>>> +     meson <options> build
>>> +
>>> +where "build" is the desired output build directory, and "<options>" can be
>>> +empty or one of a number of meson or DPDK-specific build options, described
>>> +later in this section. The configuration process will finish with a summary
>>> +of what DPDK libraries and drivers are to be built and installed, and for
>>> +each item disabled, a reason why that is the case. This information can be
>>> +used, for example, to identify any missing required packages for a driver.
>>> +
>>> +Once configured, to build and then install DPDK system-wide use:
>>> +
>>> +.. code-block:: console
>>> +
>>> +        cd build
>>> +        ninja
>>> +        ninja install
>>> +
>>> +Adjusting Build Options
>>> +~~~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +DPDK has a number of options that can be adjusted as part of the build configuration process.
>>> +These options can be listed by running ``meson configure`` inside a configured build folder.
>>> +Many of these options come from the "meson" tool itself and can be seen documented on the
>>> +`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
>>> +
>>> +For example, to change the build-type from the default, "debugoptimized",
>>> +to a regular "debug" build, you can either:
>>> +
>>> +* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
>>> +
>>> +* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
>>> +
>>> +Other options are specific to the DPDK project but can be adjusted similarly.
>>> +To set the "max_lcores" value to 256, for example, you can either:
>>> +
>>> +* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
>>> +
>>> +* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
>>
>> This *very* welcome. It's a pity it's not possible to run these /before/
>> creating a build directory, but i'll take it!
>>
> 
> Can you clarify what you mean here? Passing max_lcores to the initial meson
> run isn't sufficient, you think?

No, i mean showing the available options. I don't think there's a way to 
show configuration options without creating a build directory first.

> 
>> A common source of confusion for people building example apps with meson is
>> that, unlike with make, you don't build DPDK first and then build examples,
>> you build them all at once. Perhaps it would be worth calling this out
>> explicitly?
>>
> I was actually thinking that that functionality was primarily targeted at
> developers rather than at end users. However, I can include the -Dexamples
> flag for reference here for people.

I'm speaking of "developer used to building DPDK with make" target 
audience. It has been my experience (of pushing people to use meson) 
that this is a major point of confusion when it comes to using meson for 
DPDK development.

> 
>> Also, kinda unrelated to this, but can we add an "all" target that actually
>> fails if one of the examples doesn't build? IIRC currently it'll just skip
>> through any that don't build, which is not ideal for quick compile testing.
>> I mean, obviously apps that don't have their dependencies met shouldn't be
>> attempted, but if any /buildable/ examples fail to build, i think there
>> should be a way to communicate this without having to explicitly call out
>> all example apps in the -Dexamples option. (if it currently works that way,
>> disregard!)
> 
> This should indeed be the way it currently works. The examples to be built
> depends upon the detected dependencies at configure time, but thereafter on
> compile, ninja knows nothing about examples or otherwise, it just sees code
> to be compiled and linked and should error out if anything fails. If this
> is not the case, it's a bug we need to fix.

Then disregard :)

> 
>>
>>> +
>>> +Building Applications Using Installed DPDK
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
>>> +It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
>>> +for DPDK into the application build process.
>>> +
>>> +An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
>>> +A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
>>> +and the sources for that build are stored in ``$(SRCS-y)``.
>>> +
>>> +.. code-block:: makefile
>>> +
>>> +        PKGCONF = pkg-config
>>> +
>>> +        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
>>> +        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
>>> +
>>> +        $(APP): $(SRCS-y) Makefile
>>> +                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
>>
>> What about a meson-based example?
>>
> I didn't think such a thing would be work including, since the number of
> end-user apps using meson is likely fairly small. We'd also then need to
> include an example using cmake or other build systems too, for
> completeness.

That's a bit of a false equivalence though, because DPDK doesn't support 
CMake, while it does support meson - so it makes sense to provide 
instructions for meson as well. If you only provide instructions for 
make, people will end up using make just because it's less effort to 
"use what you know" than switching to build DPDK using meson *and* 
figuring out how to use meson for your app development as well.

For example, whenever i need to build a quick-n-dirty DPDK app outside 
of DPDK tree, i use meson because it's the thing i now know that is 
better than make (syntax-wise at least), but it took me a while to 
figure out how to build a DPDK app using meson outside of DPDK build 
tree. The process would've been much easier if there was a ready-made 
example of how to do that.

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Richardson, Bruce]

> >>> +.. code-block:: makefile
> >>> +
> >>> +        PKGCONF = pkg-config
> >>> +
> >>> +        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
> >>> +        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
> >>> +
> >>> +        $(APP): $(SRCS-y) Makefile
> >>> +                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
> >>
> >> What about a meson-based example?
> >>
> > I didn't think such a thing would be work including, since the number of
> > end-user apps using meson is likely fairly small. We'd also then need to
> > include an example using cmake or other build systems too, for
> > completeness.
> 
> That's a bit of a false equivalence though, because DPDK doesn't support
> CMake, while it does support meson - so it makes sense to provide
> instructions for meson as well. If you only provide instructions for
> make, people will end up using make just because it's less effort to
> "use what you know" than switching to build DPDK using meson *and*
> figuring out how to use meson for your app development as well.
> 
> For example, whenever i need to build a quick-n-dirty DPDK app outside
> of DPDK tree, i use meson because it's the thing i now know that is
> better than make (syntax-wise at least), but it took me a while to
> figure out how to build a DPDK app using meson outside of DPDK build
> tree. The process would've been much easier if there was a ready-made
> example of how to do that.
> 
Ok, it's only a few lines of example, so I'll add in V2.

Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Burakov, Anatoly]

On 22-Nov-19 4:03 PM, Bruce Richardson wrote:
> Add instructions on building DPDK and using the pkg-config file to the
> linux GSG.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

<snip>

> +
> +Building Applications Using Installed DPDK
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
> +It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
> +for DPDK into the application build process.
> +
> +An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
> +A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
> +and the sources for that build are stored in ``$(SRCS-y)``.
> +
> +.. code-block:: makefile
> +
> +        PKGCONF = pkg-config
> +
> +        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
> +        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
> +
> +        $(APP): $(SRCS-y) Makefile
> +                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)

Also, as we have recently discovered, enabling DPDK libraries 
system-wide may not be so trivial after all, and may involve running 
ldconfig and/or modifying the /etc/ld.so.conf.d/ to include the locally 
built libraries. Should we include this as well? An argument can be made 
that this is distro-specific and shouldn't be in this guide, but these 
problems happen on distros that are common enough and are explicitly 
supported by DPDK, so perhaps /some/ note on possible issues with 
library search paths should be present?

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG

[Richardson, Bruce]

> -----Original Message-----
> From: Burakov, Anatoly <anatoly.burakov@intel.com>
> Sent: Monday, November 25, 2019 1:23 PM
> To: Richardson, Bruce <bruce.richardson@intel.com>; Mcnamara, John
> <john.mcnamara@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux
> GSG
> 
> On 22-Nov-19 4:03 PM, Bruce Richardson wrote:
> > Add instructions on building DPDK and using the pkg-config file to the
> > linux GSG.
> >
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> 
> <snip>
> 
> > +
> > +Building Applications Using Installed DPDK
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +When installed system-wide, DPDK provides a pkg-config file
> ``libdpdk.pc`` for applications to query as part of their build.
> > +It's recommended that the pkg-config file be used, rather than
> > +hard-coding the parameters (cflags/ldflags) for DPDK into the
> application build process.
> > +
> > +An example of how to query and use the pkg-config file can be found in
> the ``Makefile`` of each of the example applications included with DPDK.
> > +A simplified example snippet is shown below, where the target binary
> > +name has been stored in the variable ``$(APP)`` and the sources for
> that build are stored in ``$(SRCS-y)``.
> > +
> > +.. code-block:: makefile
> > +
> > +        PKGCONF = pkg-config
> > +
> > +        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
> > +        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
> > +
> > +        $(APP): $(SRCS-y) Makefile
> > +                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
> 
> Also, as we have recently discovered, enabling DPDK libraries system-wide
> may not be so trivial after all, and may involve running ldconfig and/or
> modifying the /etc/ld.so.conf.d/ to include the locally built libraries.
> Should we include this as well? An argument can be made that this is
> distro-specific and shouldn't be in this guide, but these problems happen
> on distros that are common enough and are explicitly supported by DPDK, so
> perhaps /some/ note on possible issues with library search paths should be
> present?
> 
Agreed. I'll add a note in V2.

[dpdk-dev] [PATCH 3/8] doc: reorder meson and make build instructions for arm

[Bruce Richardson]

Since the meson instructions are the simpler of the two sets, and also the
ones most future-proof, put those first in the user documentation with make
instructions following them.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 .../linux_gsg/cross_build_dpdk_for_arm64.rst  | 32 ++++++++++---------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
index e799b0ba4..8c87a595e 100644
--- a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
+++ b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
@@ -77,8 +77,23 @@ Copy the NUMA header files and lib to the cross compiler's directories:
 
 .. _configure_and_cross_compile_dpdk_build:
 
-Configure and cross compile DPDK Build
---------------------------------------
+Cross Compiling DPDK using Meson
+--------------------------------
+
+To cross-compile DPDK on a desired target machine we can use the following
+command::
+
+	meson cross-build --cross-file <target_machine_configuration>
+	ninja -C cross-build
+
+For example if the target machine is arm64 we can use the following
+command::
+
+	meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
+	ninja -C arm64-build
+
+Configure and Cross Compile DPDK using Make
+-------------------------------------------
 To configure a build, choose one of the target configurations, like arm64-dpaa-linux-gcc and arm64-thunderx-linux-gcc.
 
 .. code-block:: console
@@ -119,17 +134,4 @@ To compile for non-NUMA targets, without compiling the kernel modules, use the f
 
       make -j CROSS=aarch64-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n EXTRA_CFLAGS="-isystem <numa_install_dir>/include" EXTRA_LDFLAGS="-L<numa_install_dir>/lib -lnuma"
 
-Meson Cross Compiling DPDK
---------------------------
-
-To cross-compile DPDK on a desired target machine we can use the following
-command::
-
-	meson cross-build --cross-file <target_machine_configuration>
-	ninja -C cross-build
-
-For example if the target machine is arm64 we can use the following
-command::
 
-	meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
-	ninja -C arm64-build
-- 
2.21.0

Re: [dpdk-dev] [PATCH 3/8] doc: reorder meson and make build instructions for arm

[Gavin Hu (Arm Technology China)]

Acked-by: Gavin Hu <gavin.hu@arm.com>

[dpdk-dev] [PATCH 4/8] doc: remove reference to old versions of FreeBSD

[Bruce Richardson]

FreeBSD 10 is now EOL and all testing with DPDK takes place on BSD versions
11 and 12, so we can just remove the note. The BSD ports are supported on
all non-EOL versions of BSD.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/install_from_ports.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
index a895d6180..4b0447584 100644
--- a/doc/guides/freebsd_gsg/install_from_ports.rst
+++ b/doc/guides/freebsd_gsg/install_from_ports.rst
@@ -11,12 +11,6 @@ install it from the ports collection. Details of getting and using the ports
 collection are documented in the
 `FreeBSD Handbook <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html>`_.
 
-.. note::
-
-    Testing has been performed using FreeBSD 10.0-RELEASE (x86_64) and requires the
-    installation of the kernel sources, which should be included during the
-    installation of FreeBSD.
-
 Installing the DPDK FreeBSD Port
 --------------------------------
 
-- 
2.21.0

[dpdk-dev] [PATCH 5/8] doc: update examples output in FreeBSD GSG

[Bruce Richardson]

The output of running the helloworld example on FreeBSD was a little
out-of-date and can be shortened by using the latest version of DPDK.
Update appropriately.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/install_from_ports.rst | 56 ++++++++-----------
 1 file changed, 22 insertions(+), 34 deletions(-)

diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
index 4b0447584..29f16cc6c 100644
--- a/doc/guides/freebsd_gsg/install_from_ports.rst
+++ b/doc/guides/freebsd_gsg/install_from_ports.rst
@@ -84,48 +84,36 @@ compiled and run as below:
       INSTALL-APP helloworld
       INSTALL-MAP helloworld.map
 
-    sudo ./build/helloworld -l 0-3 -n 2
-
-    EAL: Contigmem driver has 2 buffers, each of size 1GB
+    sudo ./build//helloworld -l 0-3
     EAL: Sysctl reports 8 cpus
-    EAL: Detected lcore 0
-    EAL: Detected lcore 1
-    EAL: Detected lcore 2
-    EAL: Detected lcore 3
-    EAL: Support maximum 64 logical core(s) by configuration.
-    EAL: Detected 4 lcore(s)
-    EAL: Setting up physically contiguous memory...
-    EAL: Mapped memory segment 1 @ 0x802400000: len 1073741824
-    EAL: Mapped memory segment 2 @ 0x842400000: len 1073741824
-    EAL: WARNING: clock_gettime cannot use CLOCK_MONOTONIC_RAW and HPET
-         is not available - clock timings may be less accurate.
-    EAL: TSC frequency is ~3569023 KHz
-    EAL: PCI scan found 24 devices
-    EAL: Master core 0 is ready (tid=0x802006400)
-    EAL: Core 1 is ready (tid=0x802006800)
-    EAL: Core 3 is ready (tid=0x802007000)
-    EAL: Core 2 is ready (tid=0x802006c00)
+    EAL: Detected 8 lcore(s)
+    EAL: Detected 1 NUMA nodes
+    EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
+    EAL: Selected IOVA mode 'PA'
+    EAL: Contigmem driver has 2 buffers, each of size 1GB
+    EAL: Mapped memory segment 0 @ 0x1040000000: physaddr:0x180000000, len 1073741824
+    EAL: Mapped memory segment 1 @ 0x1080000000: physaddr:0x1c0000000, len 1073741824
+    EAL: PCI device 0000:00:19.0 on NUMA socket 0
+    EAL:   probe driver: 8086:153b net_e1000_em
+    EAL:   0000:00:19.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.0 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x80074a000
-    EAL:   PCI memory mapped at 0x8007ca000
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.1 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x8007ce000
-    EAL:   PCI memory mapped at 0x80084e000
-    EAL: PCI device 0000:02:00.0 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x800852000
-    EAL:   PCI memory mapped at 0x8008d2000
-    EAL: PCI device 0000:02:00.1 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x801b3f000
-    EAL:   PCI memory mapped at 0x8008d6000
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.1 not managed by UIO driver, skipping
+    EAL: PCI device 0000:01:00.2 on NUMA socket 0
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.2 not managed by UIO driver, skipping
+    EAL: PCI device 0000:01:00.3 on NUMA socket 0
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.3 not managed by UIO driver, skipping
     hello from core 1
     hello from core 2
     hello from core 3
     hello from core 0
 
+
 .. note::
 
    To run a DPDK process as a non-root user, adjust the permissions on
-- 
2.21.0

[dpdk-dev] [PATCH 6/8] doc: add meson install instructions for FreeBSD

[Bruce Richardson]

Update the FreeBSD GSG doc with instructions for installing using meson and
ninja rather than make.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/build_dpdk.rst | 164 +++++++-------------------
 1 file changed, 40 insertions(+), 124 deletions(-)

diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst
index 7abd85aa5..c5d5379f6 100644
--- a/doc/guides/freebsd_gsg/build_dpdk.rst
+++ b/doc/guides/freebsd_gsg/build_dpdk.rst
@@ -6,147 +6,63 @@
 Compiling the DPDK Target from Source
 =====================================
 
-System Requirements
--------------------
+Prerequisites
+-------------
 
-The DPDK and its applications require the GNU make system (gmake)
-to build on FreeBSD. Optionally, gcc may also be used in place of clang
-to build the DPDK, in which case it too must be installed prior to
-compiling the DPDK. The installation of these tools is covered in this
-section.
+The following FreeBSD packages are required to build DPDK:
 
-Compiling the DPDK requires the FreeBSD kernel sources, which should be
-included during the installation of FreeBSD on the development platform.
-The DPDK also requires the use of FreeBSD ports to compile and function.
+* meson
+* ninja
+* pkgconf
 
-To use the FreeBSD ports system, it is required to update and extract the FreeBSD
-ports tree by issuing the following commands:
+These can be installed using (as root)::
 
-.. code-block:: console
-
-    portsnap fetch
-    portsnap extract
-
-If the environment requires proxies for external communication, these can be set
-using:
-
-.. code-block:: console
-
-    setenv http_proxy <my_proxy_host>:<port>
-    setenv ftp_proxy <my_proxy_host>:<port>
-
-The FreeBSD ports below need to be installed prior to building the DPDK.
-In general these can be installed using the following set of commands::
-
-   cd /usr/ports/<port_location>
-
-   make config-recursive
-
-   make install
-
-   make clean
-
-Each port location can be found using::
-
-   whereis <port_name>
-
-The ports required and their locations are as follows:
-
-* dialog4ports: ``/usr/ports/ports-mgmt/dialog4ports``
-
-* GNU make(gmake): ``/usr/ports/devel/gmake``
-
-* coreutils: ``/usr/ports/sysutils/coreutils``
-
-For compiling and using the DPDK with gcc, the compiler must be installed
-from the ports collection:
-
-* gcc: version 4.9 is recommended ``/usr/ports/lang/gcc49``.
-  Ensure that ``CPU_OPTS`` is selected (default is OFF).
-
-When running the make config-recursive command, a dialog may be presented to the
-user. For the installation of the DPDK, the default options were used.
-
-.. note::
+  pkg install meson pkgconf
 
-    To avoid multiple dialogs being presented to the user during make install,
-    it is advisable before running the make install command to re-run the
-    make config-recursive command until no more dialogs are seen.
+To compile the required kernel modules for memory management and working
+with physical NIC devices, the kernel sources for FreeBSD also
+need to be installed. If not already present on the system, these can be
+installed via commands like the following, for FreeBSD 12.1 on x86_64::
 
+  fetch http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/12.1-RELEASE/src.txz
+  tar -C / -xJvf src.txz
 
-Install the DPDK and Browse Sources
------------------------------------
+To enable the telemetry library in DPDK, the jansson library also needs to
+be installed, and can be installed via::
 
-First, uncompress the archive and move to the DPDK source directory:
+  pkg install jansson
 
-.. code-block:: console
-
-    unzip DPDK-<version>.zip
-    cd DPDK-<version>
-
-The DPDK is composed of several directories:
-
-*   lib: Source code of DPDK libraries
-
-*   app: Source code of DPDK applications (automatic tests)
-
-*   examples: Source code of DPDK applications
-
-*   config, buildtools, mk: Framework-related makefiles, scripts and configuration
-
-Installation of the DPDK Target Environments
---------------------------------------------
-
-The format of a DPDK target is::
-
-   ARCH-MACHINE-EXECENV-TOOLCHAIN
-
-Where:
+Individual drivers may have additional requirements. Consult the relevant
+driver guide for any driver-specific requirements of interest.
 
-* ``ARCH`` is: ``x86_64``
+Building DPDK
+-------------
 
-* ``MACHINE`` is: ``native``
+The following commands can be used to build and install DPDK on a system.
+The final, install, step generally needs to be run as root::
 
-* ``EXECENV`` is: ``freebsd``
+  meson build
+  cd build
+  ninja
+  ninja install
 
-* ``TOOLCHAIN`` is: ``gcc`` | ``clang``
-
-The configuration files for the DPDK targets can be found in the DPDK/config
-directory in the form of::
-
-    defconfig_ARCH-MACHINE-EXECENV-TOOLCHAIN
+This will install the DPDK libraries and drivers to `/usr/local/lib` with a
+pkg-config file `libdpdk.pc` installed to `/usr/local/lib/pkgconfig`. The
+DPDK test applications, such as `dpdk-testpmd` are installed to
+`/usr/local/bin`. To use these applications, it is recommended that the
+`contigmem` and `nic_uio` kernel modules be loaded first, as described in
+the next section.
 
 .. note::
 
-   Configuration files are provided with the ``RTE_MACHINE`` optimization level set.
-   Within the configuration files, the ``RTE_MACHINE`` configuration value is set
-   to native, which means that the compiled software is tuned for the platform
-   on which it is built.  For more information on this setting, and its
-   possible values, see the *DPDK Programmers Guide*.
-
-To make the target, use ``gmake install T=<target>``.
-
-For example to compile for FreeBSD use:
-
-.. code-block:: console
-
-    gmake install T=x86_64-native-freebsd-clang
-
-.. note::
-
-   If the compiler binary to be used does not correspond to that given in the
-   TOOLCHAIN part of the target, the compiler command may need to be explicitly
-   specified. For example, if compiling for gcc, where the gcc binary is called
-   gcc4.9, the command would need to be ``gmake install T=<target> CC=gcc4.9``.
-
-Browsing the Installed DPDK Environment Target
-----------------------------------------------
+        It is recommended that pkg-config be used to query information
+        about the compiler and linker flags needed to build applications
+        against DPDK.  In some cases, the path `/usr/local/lib/pkgconfig`
+        may not be in the default search paths for `.pc` files, which means
+        that queries for DPDK information may fail. This can be fixed by
+        setting the appropriate path in `PKG_CONFIG_PATH` environment
+        variable.
 
-Once a target is created, it contains all the libraries and header files for the
-DPDK environment that are required to build customer applications.
-In addition, the test and testpmd applications are built under the build/app
-directory, which may be used for testing.  A kmod directory is also present that
-contains the kernel modules to install.
 
 .. _loading_contigmem:
 
-- 
2.21.0

[dpdk-dev] [PATCH 7/8] doc: update documentation on build and running FreeBSD apps

[Bruce Richardson]

Update the documentation on building and running apps on FreeBSD, taking
account of having used meson for building. We can also update the section
on the command-line parameters, rather than claiming to be a complete list
of parameters, it should describe how to get the complete list and only
cover a few important ones.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/build_sample_apps.rst | 118 +++++--------------
 1 file changed, 27 insertions(+), 91 deletions(-)

diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst
index 0c1b9cb79..2a68f5fc3 100644
--- a/doc/guides/freebsd_gsg/build_sample_apps.rst
+++ b/doc/guides/freebsd_gsg/build_sample_apps.rst
@@ -12,68 +12,37 @@ environment. It also provides a pointer to where sample applications are stored.
 Compiling a Sample Application
 ------------------------------
 
-Once a DPDK target environment directory has been created (such as
-``x86_64-native-freebsd-clang``), it contains all libraries and header files required
-to build an application.
+The DPDK example applications make use of the pkg-config file installed on
+the system when DPDK is installed, and so can be built using GNU make.
 
-When compiling an application in the FreeBSD environment on the DPDK,
-the following variables must be exported:
-
-*   ``RTE_SDK`` - Points to the DPDK installation directory.
-
-*   ``RTE_TARGET`` - Points to the DPDK target environment directory.
-    For FreeBSD, this is the ``x86_64-native-freebsd-clang`` or
-    ``x86_64-native-freebsd-gcc`` directory.
-
-The following is an example of creating the ``helloworld`` application, which runs
-in the DPDK FreeBSD environment. While the example demonstrates compiling
-using gcc version 4.9, compiling with clang will be similar, except that the ``CC=``
-parameter can probably be omitted. The ``helloworld`` example may be found in the
-``${RTE_SDK}/examples`` directory.
-
-The directory contains the ``main.c`` file. This file, when combined with the
-libraries in the DPDK target environment, calls the various functions to
-initialize the DPDK environment, then launches an entry point (dispatch
-application) for each core to be utilized. By default, the binary is generated
-in the build directory.
-
-.. code-block:: console
-
-    setenv RTE_SDK /home/user/DPDK
-    cd $(RTE_SDK)
-    cd examples/helloworld/
-    setenv RTE_SDK $HOME/DPDK
-    setenv RTE_TARGET x86_64-native-freebsd-gcc
-
-    gmake CC=gcc49
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
+.. note::
 
-    ls build/app
-      helloworld helloworld.map
+   BSD make cannot be used to compile the DPDK example applications. GNU
+   make can be installed using `pkg install gmake` if not already installed
+   on the FreeBSD system.
 
-.. note::
+The following shows how to compile the helloworld example app, following
+the installation of DPDK using `ninja install` as described previously::
 
-    In the above example, ``helloworld`` was in the directory structure of the
-    DPDK. However, it could have been located outside the directory
-    structure to keep the DPDK structure intact.  In the following case,
-    the ``helloworld`` application is copied to a new directory as a new starting
-    point.
+        $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 
-.. code-block:: console
+        $ cd examples/helloworld/
 
-    setenv RTE_SDK /home/user/DPDK
-    cp -r $(RTE_SDK)/examples/helloworld my_rte_app
-    cd my_rte_app/
-    setenv RTE_TARGET x86_64-native-freebsd-gcc
+        $ gmake
+        cc -O3 -I/usr/local/include -include rte_config.h -march=native
+        -D__BSD_VISIBLE  main.c -o build/helloworld-shared
+        -L/usr/local/lib -lrte_telemetry -lrte_bpf -lrte_flow_classify
+        -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec
+        -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib
+        -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm
+        -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro
+        -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev
+        -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev
+        -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline
+        -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf
+        -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs
+        ln -sf helloworld-shared build/helloworld
 
-    gmake CC=gcc49
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
 
 .. _running_sample_app:
 
@@ -88,29 +57,15 @@ Running a Sample Application
     Abstraction Layer (EAL) library, which provides some options that are generic
     to every DPDK application.
 
-The following is the list of options that can be given to the EAL:
-
-.. code-block:: console
-
-    ./rte-app -l CORELIST [-n NUM] [-b <domain:bus:devid.func>] \
-              [-r NUM] [-v] [--proc-type <primary|secondary|auto>]
-
-.. note::
-
-    EAL has a common interface between all operating systems and is based on the
-    Linux notation for PCI devices. For example, a FreeBSD device selector of
-    ``pci0:2:0:1`` is referred to as ``02:00.1`` in EAL.
-
-The EAL options for FreeBSD are as follows:
+A large number of options can be given to the EAL when running an
+application. A full list of options can be got by passing `--help` to a
+DPDK application. Some of the EAL options for FreeBSD are as follows:
 
 *   ``-c COREMASK`` or ``-l CORELIST``:
     A hexadecimal bit mask of the cores to run on.  Note that core numbering
     can change between platforms and should be determined beforehand. The corelist
     is a list of cores to use instead of a core mask.
 
-*   ``-n NUM``:
-    Number of memory channels per processor socket.
-
 *   ``-b <domain:bus:devid.func>``:
     Blacklisting of ports; prevent EAL from using specified PCI device
     (multiple ``-b`` options are allowed).
@@ -119,15 +74,9 @@ The EAL options for FreeBSD are as follows:
     Use the specified Ethernet device(s) only.  Use comma-separate
     ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
 
-*   ``-r NUM``:
-    Number of memory ranks.
-
 *   ``-v``:
     Display version information on startup.
 
-*   ``--proc-type``:
-    The type of process instance.
-
 *   ``-m MB``:
     Memory to allocate from hugepages, regardless of processor socket.
 
@@ -147,19 +96,6 @@ Other options, specific to Linux and are not supported under FreeBSD are as foll
 
 The ``-c`` or ``-l`` option is mandatory; the others are optional.
 
-Copy the DPDK application binary to your target, then run the application
-as follows (assuming the platform has four memory channels, and that cores 0-3
-are present and are to be used for running the application)::
-
-    ./helloworld -l 0-3 -n 4
-
-.. note::
-
-    The ``--proc-type`` and ``--file-prefix`` EAL options are used for running multiple
-    DPDK processes.  See the "Multi-process Sample Application" chapter
-    in the *DPDK Sample Applications User Guide and the DPDK
-    Programmers Guide* for more details.
-
 .. _running_non_root:
 
 Running DPDK Applications Without Root Privileges
-- 
2.21.0

[dpdk-dev] [PATCH 8/8] doc: drop EAL command-line reference from FreeBSD GSG

[Bruce Richardson]

The EAL command-line reference section duplicated material covered in a
previous chapter, was out of date, and generally is unnecessary as options
are best queried directly by passing "--help" to a DPDK binary. Therefore
we can drop this section to avoid having to try and keep it up-to-date in
the future.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 .../freebsd_gsg/freebsd_eal_parameters.rst    | 20 -------------------
 doc/guides/freebsd_gsg/index.rst              |  1 -
 2 files changed, 21 deletions(-)
 delete mode 100644 doc/guides/freebsd_gsg/freebsd_eal_parameters.rst

diff --git a/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
deleted file mode 100644
index fba467a2c..000000000
--- a/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2018 Intel Corporation.
-
-EAL parameters
-==============
-
-This document contains a list of all EAL parameters. These parameters can be
-used by any DPDK application running on FreeBSD.
-
-Common EAL parameters
----------------------
-
-The following EAL parameters are common to all platforms supported by DPDK.
-
-.. include:: ../linux_gsg/eal_args.include.rst
-
-FreeBSD-specific EAL parameters
--------------------------------
-
-There are currently no FreeBSD-specific EAL command-line parameters available.
diff --git a/doc/guides/freebsd_gsg/index.rst b/doc/guides/freebsd_gsg/index.rst
index 9af5988dc..fdb4df32e 100644
--- a/doc/guides/freebsd_gsg/index.rst
+++ b/doc/guides/freebsd_gsg/index.rst
@@ -14,4 +14,3 @@ Getting Started Guide for FreeBSD
     install_from_ports
     build_dpdk
     build_sample_apps
-    freebsd_eal_parameters
-- 
2.21.0

[dpdk-dev] [PATCH v2 0/8] GSG Documentation updates

[Bruce Richardson]

This patchset includes documentation updates for both the Linux and
FreeBSD Getting Started Guide Docs. The majority of changes are to add
information on building using meson and ninja, with some additional
cleanups being performed at the same time.

V2: Updated patch 2 following feedback from Anatoly

Bruce Richardson (8):
  doc: update Linux GSG system requirements section
  doc: add building with meson to linux GSG
  doc: reorder meson and make build instructions for arm
  doc: remove reference to old versions of FreeBSD
  doc: update examples output in FreeBSD GSG
  doc: add meson install instructions for FreeBSD
  doc: update documentation on build and running FreeBSD apps
  doc: drop EAL command-line reference from FreeBSD GSG

 doc/guides/freebsd_gsg/build_dpdk.rst         | 164 +++++-------------
 doc/guides/freebsd_gsg/build_sample_apps.rst  | 118 +++----------
 .../freebsd_gsg/freebsd_eal_parameters.rst    |  20 ---
 doc/guides/freebsd_gsg/index.rst              |   1 -
 doc/guides/freebsd_gsg/install_from_ports.rst |  62 +++----
 doc/guides/linux_gsg/build_dpdk.rst           | 139 ++++++++++++++-
 .../linux_gsg/cross_build_dpdk_for_arm64.rst  |  32 ++--
 doc/guides/linux_gsg/sys_reqs.rst             |  64 +++----
 8 files changed, 273 insertions(+), 327 deletions(-)
 delete mode 100644 doc/guides/freebsd_gsg/freebsd_eal_parameters.rst

-- 
2.21.0

[dpdk-dev] [PATCH v2 1/8] doc: update Linux GSG system requirements section

[Bruce Richardson]

Update the system requirements section of the doc to cover builds with
meson and ninja. This involves updating the package dependencies to include
meson, ninja and python 3.5, and also updating the optional dependencies
section to explain that the components are enabled/disabled automatically
by meson.

As part of this update, the relevant sections were simplified to keep the
document shorter. For mandatory requirements, we can refer to the various
distro's development tools package groups rather than requiring gcc, core
tools etc. individually. The optional package list was very incomplete, and
if complete would duplicate information in the individual driver's guides.
Therefore we can simplify it by listing only the library optional
requirements and referring users to the driver docs to find details on
their dependencies.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 64 +++++++++++++++----------------
 1 file changed, 32 insertions(+), 32 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index d2359058b..e18f43116 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -37,32 +37,22 @@ Compilation of the DPDK
     The setup commands and installed packages needed on various systems may be different.
     For details on Linux distributions and the versions tested, please consult the DPDK Release Notes.
 
-*   GNU ``make``.
+*   General development tools including ``make``, and a supported C compiler such as ``gcc`` or ``clang``.
 
-*   coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc.
+    * For Red Hat/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
 
-*   gcc: versions 4.9 or later is recommended for all platforms.
-    On some distributions, some specific compiler flags and linker flags are enabled by
-    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
-    of your distribution and to ``gcc -dumpspecs``.
+    * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
 
-*   libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``;
-    ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture;
-    ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;)
+*   Python, recommended version 3.5+.
 
-*   Linux kernel headers or sources required to build kernel modules. (kernel - devel.x86_64;
-    kernel - devel.ppc64)
+    * Python v3.5+ is needed to build DPDK using meson and ninja
 
-*   Additional packages required for 32-bit compilation on 64-bit systems are:
+    * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
 
-    * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64;
+*   Meson (v0.47.1+) and ninja
 
-    * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64;
-
-    .. note::
-
-       x86_x32 ABI is currently supported with distribution packages only on Ubuntu
-       higher than 13.10 or recent Debian distribution. The only supported  compiler is gcc 4.9+.
+    * Recommended to use the latest versions from Python's "pip" repository:
+      ``pip3 install meson ninja``
 
 *   Library for handling NUMA (Non Uniform Memory Access).
 
@@ -70,16 +60,7 @@ Compilation of the DPDK
 
     * libnuma-dev in Debian/Ubuntu;
 
-    .. note::
-
-        On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`)
-        is a recommended dependency when `--legacy-mem` switch is used,
-        and a *required* dependency if default memory mode is used.
-        While DPDK will compile and run without `libnuma`
-        even on NUMA-enabled systems,
-        both usability and performance will be degraded.
-
-*   Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
+*   Linux kernel headers or sources required to build kernel modules.
 
 .. note::
 
@@ -96,10 +77,29 @@ Compilation of the DPDK
     which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
     it, see the IBM official installation document.
 
-*   libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
-    This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file.
+**Additional Libraries**
+
+A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
+For DPDK builds using meson, the presence or absence of these dependencies will be
+automatically detected enabling or disabling the relevant components appropriately.
+
+For builds using make, these components are disabled in the default configuration and
+need to be enabled manually my changing the relevant setting to "y" in the build configuration file
+i.e. the ``.config`` file in the build folder.
+
+In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
+
+For libraries the additional dependencies include:
+
+*   libarchive: for some unit tests using tar to get their resources.
+
+*   jansson: to compile and use the telemetry library.
+
+*   libelf: to compile and use the bpf library.
 
-*   libarchive headers and library are needed for some unit tests using tar to get their resources.
+For poll-mode drivers, the additional dependencies for each driver can be
+found in that driver's documentation in the relevant DPDK guide document,
+e.g. Network Interface Controller Drivers Guide
 
 
 Running DPDK Applications
-- 
2.21.0

[dpdk-dev] [PATCH v2 2/8] doc: add building with meson to linux GSG

[Bruce Richardson]

Add instructions on building DPDK and using the pkg-config file to the
linux GSG.

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

V2: Changes following Anatoly's review:
* minor grammar fix
* added ldconfig call to instructions and note about needing to add
  /usr/local/lib* to loader paths on RHEL/Fedora
* added description of -Dexamples option
* added example of using libdpdk from an app meson.build file

---
 doc/guides/linux_gsg/build_dpdk.rst | 139 +++++++++++++++++++++++++++-
 1 file changed, 135 insertions(+), 4 deletions(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 7c0329fcc..4aeb4697d 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -11,8 +11,8 @@ Compiling the DPDK Target from Source
     Parts of this process can also be done using the setup script described in
     the :ref:`linux_setup_script` section of this document.
 
-Install the DPDK and Browse Sources
------------------------------------
+Uncompress DPDK and Browse Sources
+----------------------------------
 
 First, uncompress the archive and move to the uncompressed DPDK source directory:
 
@@ -33,8 +33,139 @@ The DPDK is composed of several directories:
 
 *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
 
-Installation of DPDK Target Environments
-----------------------------------------
+Compiling and Installing DPDK System-wide
+-----------------------------------------
+
+DPDK can be configured, built and installed on your system using the tools
+``meson`` and ``ninja``.
+
+.. note::
+
+  The older makefile-based build system used in older DPDK releases is
+  still present and its use is described in section
+  `Installation of DPDK Target Environment using Make`_.
+
+DPDK Configuration
+~~~~~~~~~~~~~~~~~~
+
+To configure a DPDK build use:
+
+.. code-block:: console
+
+     meson <options> build
+
+where "build" is the desired output build directory, and "<options>" can be
+empty or one of a number of meson or DPDK-specific build options, described
+later in this section. The configuration process will finish with a summary
+of what DPDK libraries and drivers are to be built and installed, and for
+each item disabled, a reason why that is the case. This information can be
+used, for example, to identify any missing required packages for a driver.
+
+Once configured, to build and then install DPDK system-wide use:
+
+.. code-block:: console
+
+        cd build
+        ninja
+        ninja install
+        ldconfig
+
+The last two commands above generally need to be run as root,
+with the `ninja install` step copying the built objects to their final system-wide locations,
+and the last step causing the dynamic loader `ld.so` to update its cache to take account of the new objects.
+
+.. note::
+
+   On some linux distributions, such as Fedora or Redhat, paths in `/usr/local` are
+   not in the default paths for the loader. Therefore, on these
+   distributions, `/usr/local/lib` and `/usr/local/lib64` should be added
+   to a file in `/etc/ld.so.conf.d/` before running `ldconfig`.
+
+
+Adjusting Build Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+DPDK has a number of options that can be adjusted as part of the build configuration process.
+These options can be listed by running ``meson configure`` inside a configured build folder.
+Many of these options come from the "meson" tool itself and can be seen documented on the
+`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
+
+For example, to change the build-type from the default, "debugoptimized",
+to a regular "debug" build, you can either:
+
+* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
+
+Other options are specific to the DPDK project but can be adjusted similarly.
+To set the "max_lcores" value to 256, for example, you can either:
+
+* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
+
+Some of the DPDK sample applications in the `examples` directory can be
+automatically built as part of a meson build too.
+To do so, pass a comma-separated list of the examples to build to the
+`-Dexamples` meson option as below::
+
+  meson -Dexamples=l2fwd,l3fwd build
+
+As with other meson options, this can also be set post-initial-config using `meson configure` in the build directory.
+There is also a special value "all" to request that all example applications whose
+dependencies are met on the current system are built.
+When `-Dexamples=all` is set as a meson option, meson will check each example application to see if it can be built,
+and add all which can be built to the list of tasks in the ninja build configuration file.
+
+Building Applications Using Installed DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
+It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
+for DPDK into the application build process.
+
+An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
+A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
+and the sources for that build are stored in ``$(SRCS-y)``.
+
+.. code-block:: makefile
+
+        PKGCONF = pkg-config
+
+        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
+        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
+
+        $(APP): $(SRCS-y) Makefile
+                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
+
+.. note::
+
+   Unlike with the older make build system, the meson system is not
+   designed to be used directly from a build directory. Instead it is
+   recommended that it be installed either system-wide or to a known
+   location in the user's home directory. The install location can be set
+   using the `--prefix` meson option (default: `/usr/local`).
+
+an equivalent build recipe for a simple DPDK application using meson as a
+build system is shown below:
+
+.. code-block:: python
+
+   project('dpdk-app', 'c')
+
+   dpdk = dependency('libdpdk')
+   sources = files('main.c')
+   executable('dpdk-app', sources, dependencies: dpdk)
+
+
+Installation of DPDK Target Environment using Make
+--------------------------------------------------
+
+.. note::
+
+   The building of DPDK using make will be deprecated in a future release. It
+   is therefore recommended that DPDK installation is done using meson and
+   ninja as described above.
 
 The format of a DPDK target is::
 
-- 
2.21.0

Re: [dpdk-dev] [PATCH v2 2/8] doc: add building with meson to linux GSG

[Burakov, Anatoly]

On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> Add instructions on building DPDK and using the pkg-config file to the
> linux GSG.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

-- 
Thanks,
Anatoly

[dpdk-dev] [PATCH v2 3/8] doc: reorder meson and make build instructions for arm

[Bruce Richardson]

Since the meson instructions are the simpler of the two sets, and also the
ones most future-proof, put those first in the user documentation with make
instructions following them.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Gavin Hu <gavin.hu@arm.com>
---
 .../linux_gsg/cross_build_dpdk_for_arm64.rst  | 32 ++++++++++---------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
index e799b0ba4..8c87a595e 100644
--- a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
+++ b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
@@ -77,8 +77,23 @@ Copy the NUMA header files and lib to the cross compiler's directories:
 
 .. _configure_and_cross_compile_dpdk_build:
 
-Configure and cross compile DPDK Build
---------------------------------------
+Cross Compiling DPDK using Meson
+--------------------------------
+
+To cross-compile DPDK on a desired target machine we can use the following
+command::
+
+	meson cross-build --cross-file <target_machine_configuration>
+	ninja -C cross-build
+
+For example if the target machine is arm64 we can use the following
+command::
+
+	meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
+	ninja -C arm64-build
+
+Configure and Cross Compile DPDK using Make
+-------------------------------------------
 To configure a build, choose one of the target configurations, like arm64-dpaa-linux-gcc and arm64-thunderx-linux-gcc.
 
 .. code-block:: console
@@ -119,17 +134,4 @@ To compile for non-NUMA targets, without compiling the kernel modules, use the f
 
       make -j CROSS=aarch64-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n EXTRA_CFLAGS="-isystem <numa_install_dir>/include" EXTRA_LDFLAGS="-L<numa_install_dir>/lib -lnuma"
 
-Meson Cross Compiling DPDK
---------------------------
-
-To cross-compile DPDK on a desired target machine we can use the following
-command::
-
-	meson cross-build --cross-file <target_machine_configuration>
-	ninja -C cross-build
-
-For example if the target machine is arm64 we can use the following
-command::
 
-	meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
-	ninja -C arm64-build
-- 
2.21.0

[dpdk-dev] [PATCH v2 4/8] doc: remove reference to old versions of FreeBSD

[Bruce Richardson]

FreeBSD 10 is now EOL and all testing with DPDK takes place on BSD versions
11 and 12, so we can just remove the note. The BSD ports are supported on
all non-EOL versions of BSD.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/install_from_ports.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
index a895d6180..4b0447584 100644
--- a/doc/guides/freebsd_gsg/install_from_ports.rst
+++ b/doc/guides/freebsd_gsg/install_from_ports.rst
@@ -11,12 +11,6 @@ install it from the ports collection. Details of getting and using the ports
 collection are documented in the
 `FreeBSD Handbook <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html>`_.
 
-.. note::
-
-    Testing has been performed using FreeBSD 10.0-RELEASE (x86_64) and requires the
-    installation of the kernel sources, which should be included during the
-    installation of FreeBSD.
-
 Installing the DPDK FreeBSD Port
 --------------------------------
 
-- 
2.21.0

Re: [dpdk-dev] [PATCH v2 4/8] doc: remove reference to old versions of FreeBSD

[Burakov, Anatoly]

On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> FreeBSD 10 is now EOL and all testing with DPDK takes place on BSD versions
> 11 and 12, so we can just remove the note. The BSD ports are supported on
> all non-EOL versions of BSD.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

-- 
Thanks,
Anatoly

[dpdk-dev] [PATCH v2 5/8] doc: update examples output in FreeBSD GSG

[Bruce Richardson]

The output of running the helloworld example on FreeBSD was a little
out-of-date and can be shortened by using the latest version of DPDK.
Update appropriately.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/install_from_ports.rst | 56 ++++++++-----------
 1 file changed, 22 insertions(+), 34 deletions(-)

diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
index 4b0447584..29f16cc6c 100644
--- a/doc/guides/freebsd_gsg/install_from_ports.rst
+++ b/doc/guides/freebsd_gsg/install_from_ports.rst
@@ -84,48 +84,36 @@ compiled and run as below:
       INSTALL-APP helloworld
       INSTALL-MAP helloworld.map
 
-    sudo ./build/helloworld -l 0-3 -n 2
-
-    EAL: Contigmem driver has 2 buffers, each of size 1GB
+    sudo ./build//helloworld -l 0-3
     EAL: Sysctl reports 8 cpus
-    EAL: Detected lcore 0
-    EAL: Detected lcore 1
-    EAL: Detected lcore 2
-    EAL: Detected lcore 3
-    EAL: Support maximum 64 logical core(s) by configuration.
-    EAL: Detected 4 lcore(s)
-    EAL: Setting up physically contiguous memory...
-    EAL: Mapped memory segment 1 @ 0x802400000: len 1073741824
-    EAL: Mapped memory segment 2 @ 0x842400000: len 1073741824
-    EAL: WARNING: clock_gettime cannot use CLOCK_MONOTONIC_RAW and HPET
-         is not available - clock timings may be less accurate.
-    EAL: TSC frequency is ~3569023 KHz
-    EAL: PCI scan found 24 devices
-    EAL: Master core 0 is ready (tid=0x802006400)
-    EAL: Core 1 is ready (tid=0x802006800)
-    EAL: Core 3 is ready (tid=0x802007000)
-    EAL: Core 2 is ready (tid=0x802006c00)
+    EAL: Detected 8 lcore(s)
+    EAL: Detected 1 NUMA nodes
+    EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
+    EAL: Selected IOVA mode 'PA'
+    EAL: Contigmem driver has 2 buffers, each of size 1GB
+    EAL: Mapped memory segment 0 @ 0x1040000000: physaddr:0x180000000, len 1073741824
+    EAL: Mapped memory segment 1 @ 0x1080000000: physaddr:0x1c0000000, len 1073741824
+    EAL: PCI device 0000:00:19.0 on NUMA socket 0
+    EAL:   probe driver: 8086:153b net_e1000_em
+    EAL:   0000:00:19.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.0 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x80074a000
-    EAL:   PCI memory mapped at 0x8007ca000
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.1 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x8007ce000
-    EAL:   PCI memory mapped at 0x80084e000
-    EAL: PCI device 0000:02:00.0 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x800852000
-    EAL:   PCI memory mapped at 0x8008d2000
-    EAL: PCI device 0000:02:00.1 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x801b3f000
-    EAL:   PCI memory mapped at 0x8008d6000
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.1 not managed by UIO driver, skipping
+    EAL: PCI device 0000:01:00.2 on NUMA socket 0
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.2 not managed by UIO driver, skipping
+    EAL: PCI device 0000:01:00.3 on NUMA socket 0
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.3 not managed by UIO driver, skipping
     hello from core 1
     hello from core 2
     hello from core 3
     hello from core 0
 
+
 .. note::
 
    To run a DPDK process as a non-root user, adjust the permissions on
-- 
2.21.0

Re: [dpdk-dev] [PATCH v2 5/8] doc: update examples output in FreeBSD GSG

[Burakov, Anatoly]

On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> The output of running the helloworld example on FreeBSD was a little
> out-of-date and can be shortened by using the latest version of DPDK.
> Update appropriately.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>   doc/guides/freebsd_gsg/install_from_ports.rst | 56 ++++++++-----------
>   1 file changed, 22 insertions(+), 34 deletions(-)
> 
> diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
> index 4b0447584..29f16cc6c 100644
> --- a/doc/guides/freebsd_gsg/install_from_ports.rst
> +++ b/doc/guides/freebsd_gsg/install_from_ports.rst
> @@ -84,48 +84,36 @@ compiled and run as below:
>         INSTALL-APP helloworld
>         INSTALL-MAP helloworld.map
>   
> -    sudo ./build/helloworld -l 0-3 -n 2
> -
> -    EAL: Contigmem driver has 2 buffers, each of size 1GB
> +    sudo ./build//helloworld -l 0-3
>       EAL: Sysctl reports 8 cpus
> -    EAL: Detected lcore 0
> -    EAL: Detected lcore 1
> -    EAL: Detected lcore 2
> -    EAL: Detected lcore 3
> -    EAL: Support maximum 64 logical core(s) by configuration.
> -    EAL: Detected 4 lcore(s)
> -    EAL: Setting up physically contiguous memory...
> -    EAL: Mapped memory segment 1 @ 0x802400000: len 1073741824
> -    EAL: Mapped memory segment 2 @ 0x842400000: len 1073741824
> -    EAL: WARNING: clock_gettime cannot use CLOCK_MONOTONIC_RAW and HPET
> -         is not available - clock timings may be less accurate.
> -    EAL: TSC frequency is ~3569023 KHz
> -    EAL: PCI scan found 24 devices
> -    EAL: Master core 0 is ready (tid=0x802006400)
> -    EAL: Core 1 is ready (tid=0x802006800)
> -    EAL: Core 3 is ready (tid=0x802007000)
> -    EAL: Core 2 is ready (tid=0x802006c00)
> +    EAL: Detected 8 lcore(s)
> +    EAL: Detected 1 NUMA nodes
> +    EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
> +    EAL: Selected IOVA mode 'PA'
> +    EAL: Contigmem driver has 2 buffers, each of size 1GB
> +    EAL: Mapped memory segment 0 @ 0x1040000000: physaddr:0x180000000, len 1073741824
> +    EAL: Mapped memory segment 1 @ 0x1080000000: physaddr:0x1c0000000, len 1073741824
> +    EAL: PCI device 0000:00:19.0 on NUMA socket 0
> +    EAL:   probe driver: 8086:153b net_e1000_em
> +    EAL:   0000:00:19.0 not managed by UIO driver, skipping
>       EAL: PCI device 0000:01:00.0 on NUMA socket 0
> -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> -    EAL:   PCI memory mapped at 0x80074a000
> -    EAL:   PCI memory mapped at 0x8007ca000
> +    EAL:   probe driver: 8086:1572 net_i40e
> +    EAL:   0000:01:00.0 not managed by UIO driver, skipping
>       EAL: PCI device 0000:01:00.1 on NUMA socket 0
> -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> -    EAL:   PCI memory mapped at 0x8007ce000
> -    EAL:   PCI memory mapped at 0x80084e000
> -    EAL: PCI device 0000:02:00.0 on NUMA socket 0
> -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> -    EAL:   PCI memory mapped at 0x800852000
> -    EAL:   PCI memory mapped at 0x8008d2000
> -    EAL: PCI device 0000:02:00.1 on NUMA socket 0
> -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> -    EAL:   PCI memory mapped at 0x801b3f000
> -    EAL:   PCI memory mapped at 0x8008d6000
> +    EAL:   probe driver: 8086:1572 net_i40e
> +    EAL:   0000:01:00.1 not managed by UIO driver, skipping
> +    EAL: PCI device 0000:01:00.2 on NUMA socket 0
> +    EAL:   probe driver: 8086:1572 net_i40e
> +    EAL:   0000:01:00.2 not managed by UIO driver, skipping
> +    EAL: PCI device 0000:01:00.3 on NUMA socket 0
> +    EAL:   probe driver: 8086:1572 net_i40e
> +    EAL:   0000:01:00.3 not managed by UIO driver, skipping
>       hello from core 1
>       hello from core 2
>       hello from core 3
>       hello from core 0
>   
> +
>   .. note::

Accidental whitespace?

>   
>      To run a DPDK process as a non-root user, adjust the permissions on
> 

Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH v2 5/8] doc: update examples output in FreeBSD GSG

[Bruce Richardson]

On Wed, Nov 27, 2019 at 12:11:41PM +0000, Burakov, Anatoly wrote:
> On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> > The output of running the helloworld example on FreeBSD was a little
> > out-of-date and can be shortened by using the latest version of DPDK.
> > Update appropriately.
> > 
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> >   doc/guides/freebsd_gsg/install_from_ports.rst | 56 ++++++++-----------
> >   1 file changed, 22 insertions(+), 34 deletions(-)
> > 
> > diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
> > index 4b0447584..29f16cc6c 100644
> > --- a/doc/guides/freebsd_gsg/install_from_ports.rst
> > +++ b/doc/guides/freebsd_gsg/install_from_ports.rst
> > @@ -84,48 +84,36 @@ compiled and run as below:
> >         INSTALL-APP helloworld
> >         INSTALL-MAP helloworld.map
> > -    sudo ./build/helloworld -l 0-3 -n 2
> > -
> > -    EAL: Contigmem driver has 2 buffers, each of size 1GB
> > +    sudo ./build//helloworld -l 0-3
> >       EAL: Sysctl reports 8 cpus
> > -    EAL: Detected lcore 0
> > -    EAL: Detected lcore 1
> > -    EAL: Detected lcore 2
> > -    EAL: Detected lcore 3
> > -    EAL: Support maximum 64 logical core(s) by configuration.
> > -    EAL: Detected 4 lcore(s)
> > -    EAL: Setting up physically contiguous memory...
> > -    EAL: Mapped memory segment 1 @ 0x802400000: len 1073741824
> > -    EAL: Mapped memory segment 2 @ 0x842400000: len 1073741824
> > -    EAL: WARNING: clock_gettime cannot use CLOCK_MONOTONIC_RAW and HPET
> > -         is not available - clock timings may be less accurate.
> > -    EAL: TSC frequency is ~3569023 KHz
> > -    EAL: PCI scan found 24 devices
> > -    EAL: Master core 0 is ready (tid=0x802006400)
> > -    EAL: Core 1 is ready (tid=0x802006800)
> > -    EAL: Core 3 is ready (tid=0x802007000)
> > -    EAL: Core 2 is ready (tid=0x802006c00)
> > +    EAL: Detected 8 lcore(s)
> > +    EAL: Detected 1 NUMA nodes
> > +    EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
> > +    EAL: Selected IOVA mode 'PA'
> > +    EAL: Contigmem driver has 2 buffers, each of size 1GB
> > +    EAL: Mapped memory segment 0 @ 0x1040000000: physaddr:0x180000000, len 1073741824
> > +    EAL: Mapped memory segment 1 @ 0x1080000000: physaddr:0x1c0000000, len 1073741824
> > +    EAL: PCI device 0000:00:19.0 on NUMA socket 0
> > +    EAL:   probe driver: 8086:153b net_e1000_em
> > +    EAL:   0000:00:19.0 not managed by UIO driver, skipping
> >       EAL: PCI device 0000:01:00.0 on NUMA socket 0
> > -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> > -    EAL:   PCI memory mapped at 0x80074a000
> > -    EAL:   PCI memory mapped at 0x8007ca000
> > +    EAL:   probe driver: 8086:1572 net_i40e
> > +    EAL:   0000:01:00.0 not managed by UIO driver, skipping
> >       EAL: PCI device 0000:01:00.1 on NUMA socket 0
> > -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> > -    EAL:   PCI memory mapped at 0x8007ce000
> > -    EAL:   PCI memory mapped at 0x80084e000
> > -    EAL: PCI device 0000:02:00.0 on NUMA socket 0
> > -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> > -    EAL:   PCI memory mapped at 0x800852000
> > -    EAL:   PCI memory mapped at 0x8008d2000
> > -    EAL: PCI device 0000:02:00.1 on NUMA socket 0
> > -    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
> > -    EAL:   PCI memory mapped at 0x801b3f000
> > -    EAL:   PCI memory mapped at 0x8008d6000
> > +    EAL:   probe driver: 8086:1572 net_i40e
> > +    EAL:   0000:01:00.1 not managed by UIO driver, skipping
> > +    EAL: PCI device 0000:01:00.2 on NUMA socket 0
> > +    EAL:   probe driver: 8086:1572 net_i40e
> > +    EAL:   0000:01:00.2 not managed by UIO driver, skipping
> > +    EAL: PCI device 0000:01:00.3 on NUMA socket 0
> > +    EAL:   probe driver: 8086:1572 net_i40e
> > +    EAL:   0000:01:00.3 not managed by UIO driver, skipping
> >       hello from core 1
> >       hello from core 2
> >       hello from core 3
> >       hello from core 0
> > +
> >   .. note::
> 
> Accidental whitespace?
> 

I don't think so. I think there needs to be a blank line before the note.
If it is extra, I suggest it just be removed on apply.

> >      To run a DPDK process as a non-root user, adjust the permissions on
> > 
> 
> Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
> 
Thanks for the review.

[dpdk-dev] [PATCH v2 6/8] doc: add meson install instructions for FreeBSD

[Bruce Richardson]

Update the FreeBSD GSG doc with instructions for installing using meson and
ninja rather than make.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/build_dpdk.rst | 164 +++++++-------------------
 1 file changed, 40 insertions(+), 124 deletions(-)

diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst
index 7abd85aa5..c5d5379f6 100644
--- a/doc/guides/freebsd_gsg/build_dpdk.rst
+++ b/doc/guides/freebsd_gsg/build_dpdk.rst
@@ -6,147 +6,63 @@
 Compiling the DPDK Target from Source
 =====================================
 
-System Requirements
--------------------
+Prerequisites
+-------------
 
-The DPDK and its applications require the GNU make system (gmake)
-to build on FreeBSD. Optionally, gcc may also be used in place of clang
-to build the DPDK, in which case it too must be installed prior to
-compiling the DPDK. The installation of these tools is covered in this
-section.
+The following FreeBSD packages are required to build DPDK:
 
-Compiling the DPDK requires the FreeBSD kernel sources, which should be
-included during the installation of FreeBSD on the development platform.
-The DPDK also requires the use of FreeBSD ports to compile and function.
+* meson
+* ninja
+* pkgconf
 
-To use the FreeBSD ports system, it is required to update and extract the FreeBSD
-ports tree by issuing the following commands:
+These can be installed using (as root)::
 
-.. code-block:: console
-
-    portsnap fetch
-    portsnap extract
-
-If the environment requires proxies for external communication, these can be set
-using:
-
-.. code-block:: console
-
-    setenv http_proxy <my_proxy_host>:<port>
-    setenv ftp_proxy <my_proxy_host>:<port>
-
-The FreeBSD ports below need to be installed prior to building the DPDK.
-In general these can be installed using the following set of commands::
-
-   cd /usr/ports/<port_location>
-
-   make config-recursive
-
-   make install
-
-   make clean
-
-Each port location can be found using::
-
-   whereis <port_name>
-
-The ports required and their locations are as follows:
-
-* dialog4ports: ``/usr/ports/ports-mgmt/dialog4ports``
-
-* GNU make(gmake): ``/usr/ports/devel/gmake``
-
-* coreutils: ``/usr/ports/sysutils/coreutils``
-
-For compiling and using the DPDK with gcc, the compiler must be installed
-from the ports collection:
-
-* gcc: version 4.9 is recommended ``/usr/ports/lang/gcc49``.
-  Ensure that ``CPU_OPTS`` is selected (default is OFF).
-
-When running the make config-recursive command, a dialog may be presented to the
-user. For the installation of the DPDK, the default options were used.
-
-.. note::
+  pkg install meson pkgconf
 
-    To avoid multiple dialogs being presented to the user during make install,
-    it is advisable before running the make install command to re-run the
-    make config-recursive command until no more dialogs are seen.
+To compile the required kernel modules for memory management and working
+with physical NIC devices, the kernel sources for FreeBSD also
+need to be installed. If not already present on the system, these can be
+installed via commands like the following, for FreeBSD 12.1 on x86_64::
 
+  fetch http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/12.1-RELEASE/src.txz
+  tar -C / -xJvf src.txz
 
-Install the DPDK and Browse Sources
------------------------------------
+To enable the telemetry library in DPDK, the jansson library also needs to
+be installed, and can be installed via::
 
-First, uncompress the archive and move to the DPDK source directory:
+  pkg install jansson
 
-.. code-block:: console
-
-    unzip DPDK-<version>.zip
-    cd DPDK-<version>
-
-The DPDK is composed of several directories:
-
-*   lib: Source code of DPDK libraries
-
-*   app: Source code of DPDK applications (automatic tests)
-
-*   examples: Source code of DPDK applications
-
-*   config, buildtools, mk: Framework-related makefiles, scripts and configuration
-
-Installation of the DPDK Target Environments
---------------------------------------------
-
-The format of a DPDK target is::
-
-   ARCH-MACHINE-EXECENV-TOOLCHAIN
-
-Where:
+Individual drivers may have additional requirements. Consult the relevant
+driver guide for any driver-specific requirements of interest.
 
-* ``ARCH`` is: ``x86_64``
+Building DPDK
+-------------
 
-* ``MACHINE`` is: ``native``
+The following commands can be used to build and install DPDK on a system.
+The final, install, step generally needs to be run as root::
 
-* ``EXECENV`` is: ``freebsd``
+  meson build
+  cd build
+  ninja
+  ninja install
 
-* ``TOOLCHAIN`` is: ``gcc`` | ``clang``
-
-The configuration files for the DPDK targets can be found in the DPDK/config
-directory in the form of::
-
-    defconfig_ARCH-MACHINE-EXECENV-TOOLCHAIN
+This will install the DPDK libraries and drivers to `/usr/local/lib` with a
+pkg-config file `libdpdk.pc` installed to `/usr/local/lib/pkgconfig`. The
+DPDK test applications, such as `dpdk-testpmd` are installed to
+`/usr/local/bin`. To use these applications, it is recommended that the
+`contigmem` and `nic_uio` kernel modules be loaded first, as described in
+the next section.
 
 .. note::
 
-   Configuration files are provided with the ``RTE_MACHINE`` optimization level set.
-   Within the configuration files, the ``RTE_MACHINE`` configuration value is set
-   to native, which means that the compiled software is tuned for the platform
-   on which it is built.  For more information on this setting, and its
-   possible values, see the *DPDK Programmers Guide*.
-
-To make the target, use ``gmake install T=<target>``.
-
-For example to compile for FreeBSD use:
-
-.. code-block:: console
-
-    gmake install T=x86_64-native-freebsd-clang
-
-.. note::
-
-   If the compiler binary to be used does not correspond to that given in the
-   TOOLCHAIN part of the target, the compiler command may need to be explicitly
-   specified. For example, if compiling for gcc, where the gcc binary is called
-   gcc4.9, the command would need to be ``gmake install T=<target> CC=gcc4.9``.
-
-Browsing the Installed DPDK Environment Target
-----------------------------------------------
+        It is recommended that pkg-config be used to query information
+        about the compiler and linker flags needed to build applications
+        against DPDK.  In some cases, the path `/usr/local/lib/pkgconfig`
+        may not be in the default search paths for `.pc` files, which means
+        that queries for DPDK information may fail. This can be fixed by
+        setting the appropriate path in `PKG_CONFIG_PATH` environment
+        variable.
 
-Once a target is created, it contains all the libraries and header files for the
-DPDK environment that are required to build customer applications.
-In addition, the test and testpmd applications are built under the build/app
-directory, which may be used for testing.  A kmod directory is also present that
-contains the kernel modules to install.
 
 .. _loading_contigmem:
 
-- 
2.21.0

Re: [dpdk-dev] [PATCH v2 6/8] doc: add meson install instructions for FreeBSD

[Burakov, Anatoly]

On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> Update the FreeBSD GSG doc with instructions for installing using meson and
> ninja rather than make.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

-- 
Thanks,
Anatoly

[dpdk-dev] [PATCH v2 7/8] doc: update documentation on build and running FreeBSD apps

[Bruce Richardson]

Update the documentation on building and running apps on FreeBSD, taking
account of having used meson for building. We can also update the section
on the command-line parameters, rather than claiming to be a complete list
of parameters, it should describe how to get the complete list and only
cover a few important ones.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/freebsd_gsg/build_sample_apps.rst | 118 +++++--------------
 1 file changed, 27 insertions(+), 91 deletions(-)

diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst
index 0c1b9cb79..2a68f5fc3 100644
--- a/doc/guides/freebsd_gsg/build_sample_apps.rst
+++ b/doc/guides/freebsd_gsg/build_sample_apps.rst
@@ -12,68 +12,37 @@ environment. It also provides a pointer to where sample applications are stored.
 Compiling a Sample Application
 ------------------------------
 
-Once a DPDK target environment directory has been created (such as
-``x86_64-native-freebsd-clang``), it contains all libraries and header files required
-to build an application.
+The DPDK example applications make use of the pkg-config file installed on
+the system when DPDK is installed, and so can be built using GNU make.
 
-When compiling an application in the FreeBSD environment on the DPDK,
-the following variables must be exported:
-
-*   ``RTE_SDK`` - Points to the DPDK installation directory.
-
-*   ``RTE_TARGET`` - Points to the DPDK target environment directory.
-    For FreeBSD, this is the ``x86_64-native-freebsd-clang`` or
-    ``x86_64-native-freebsd-gcc`` directory.
-
-The following is an example of creating the ``helloworld`` application, which runs
-in the DPDK FreeBSD environment. While the example demonstrates compiling
-using gcc version 4.9, compiling with clang will be similar, except that the ``CC=``
-parameter can probably be omitted. The ``helloworld`` example may be found in the
-``${RTE_SDK}/examples`` directory.
-
-The directory contains the ``main.c`` file. This file, when combined with the
-libraries in the DPDK target environment, calls the various functions to
-initialize the DPDK environment, then launches an entry point (dispatch
-application) for each core to be utilized. By default, the binary is generated
-in the build directory.
-
-.. code-block:: console
-
-    setenv RTE_SDK /home/user/DPDK
-    cd $(RTE_SDK)
-    cd examples/helloworld/
-    setenv RTE_SDK $HOME/DPDK
-    setenv RTE_TARGET x86_64-native-freebsd-gcc
-
-    gmake CC=gcc49
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
+.. note::
 
-    ls build/app
-      helloworld helloworld.map
+   BSD make cannot be used to compile the DPDK example applications. GNU
+   make can be installed using `pkg install gmake` if not already installed
+   on the FreeBSD system.
 
-.. note::
+The following shows how to compile the helloworld example app, following
+the installation of DPDK using `ninja install` as described previously::
 
-    In the above example, ``helloworld`` was in the directory structure of the
-    DPDK. However, it could have been located outside the directory
-    structure to keep the DPDK structure intact.  In the following case,
-    the ``helloworld`` application is copied to a new directory as a new starting
-    point.
+        $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 
-.. code-block:: console
+        $ cd examples/helloworld/
 
-    setenv RTE_SDK /home/user/DPDK
-    cp -r $(RTE_SDK)/examples/helloworld my_rte_app
-    cd my_rte_app/
-    setenv RTE_TARGET x86_64-native-freebsd-gcc
+        $ gmake
+        cc -O3 -I/usr/local/include -include rte_config.h -march=native
+        -D__BSD_VISIBLE  main.c -o build/helloworld-shared
+        -L/usr/local/lib -lrte_telemetry -lrte_bpf -lrte_flow_classify
+        -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec
+        -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib
+        -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm
+        -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro
+        -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev
+        -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev
+        -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline
+        -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf
+        -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs
+        ln -sf helloworld-shared build/helloworld
 
-    gmake CC=gcc49
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
 
 .. _running_sample_app:
 
@@ -88,29 +57,15 @@ Running a Sample Application
     Abstraction Layer (EAL) library, which provides some options that are generic
     to every DPDK application.
 
-The following is the list of options that can be given to the EAL:
-
-.. code-block:: console
-
-    ./rte-app -l CORELIST [-n NUM] [-b <domain:bus:devid.func>] \
-              [-r NUM] [-v] [--proc-type <primary|secondary|auto>]
-
-.. note::
-
-    EAL has a common interface between all operating systems and is based on the
-    Linux notation for PCI devices. For example, a FreeBSD device selector of
-    ``pci0:2:0:1`` is referred to as ``02:00.1`` in EAL.
-
-The EAL options for FreeBSD are as follows:
+A large number of options can be given to the EAL when running an
+application. A full list of options can be got by passing `--help` to a
+DPDK application. Some of the EAL options for FreeBSD are as follows:
 
 *   ``-c COREMASK`` or ``-l CORELIST``:
     A hexadecimal bit mask of the cores to run on.  Note that core numbering
     can change between platforms and should be determined beforehand. The corelist
     is a list of cores to use instead of a core mask.
 
-*   ``-n NUM``:
-    Number of memory channels per processor socket.
-
 *   ``-b <domain:bus:devid.func>``:
     Blacklisting of ports; prevent EAL from using specified PCI device
     (multiple ``-b`` options are allowed).
@@ -119,15 +74,9 @@ The EAL options for FreeBSD are as follows:
     Use the specified Ethernet device(s) only.  Use comma-separate
     ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
 
-*   ``-r NUM``:
-    Number of memory ranks.
-
 *   ``-v``:
     Display version information on startup.
 
-*   ``--proc-type``:
-    The type of process instance.
-
 *   ``-m MB``:
     Memory to allocate from hugepages, regardless of processor socket.
 
@@ -147,19 +96,6 @@ Other options, specific to Linux and are not supported under FreeBSD are as foll
 
 The ``-c`` or ``-l`` option is mandatory; the others are optional.
 
-Copy the DPDK application binary to your target, then run the application
-as follows (assuming the platform has four memory channels, and that cores 0-3
-are present and are to be used for running the application)::
-
-    ./helloworld -l 0-3 -n 4
-
-.. note::
-
-    The ``--proc-type`` and ``--file-prefix`` EAL options are used for running multiple
-    DPDK processes.  See the "Multi-process Sample Application" chapter
-    in the *DPDK Sample Applications User Guide and the DPDK
-    Programmers Guide* for more details.
-
 .. _running_non_root:
 
 Running DPDK Applications Without Root Privileges
-- 
2.21.0

Re: [dpdk-dev] [PATCH v2 7/8] doc: update documentation on build and running FreeBSD apps

[Burakov, Anatoly]

On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> Update the documentation on building and running apps on FreeBSD, taking
> account of having used meson for building. We can also update the section
> on the command-line parameters, rather than claiming to be a complete list
> of parameters, it should describe how to get the complete list and only
> cover a few important ones.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

-- 
Thanks,
Anatoly

[dpdk-dev] [PATCH v2 8/8] doc: drop EAL command-line reference from FreeBSD GSG

[Bruce Richardson]

The EAL command-line reference section duplicated material covered in a
previous chapter, was out of date, and generally is unnecessary as options
are best queried directly by passing "--help" to a DPDK binary. Therefore
we can drop this section to avoid having to try and keep it up-to-date in
the future.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 .../freebsd_gsg/freebsd_eal_parameters.rst    | 20 -------------------
 doc/guides/freebsd_gsg/index.rst              |  1 -
 2 files changed, 21 deletions(-)
 delete mode 100644 doc/guides/freebsd_gsg/freebsd_eal_parameters.rst

diff --git a/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst b/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
deleted file mode 100644
index fba467a2c..000000000
--- a/doc/guides/freebsd_gsg/freebsd_eal_parameters.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2018 Intel Corporation.
-
-EAL parameters
-==============
-
-This document contains a list of all EAL parameters. These parameters can be
-used by any DPDK application running on FreeBSD.
-
-Common EAL parameters
----------------------
-
-The following EAL parameters are common to all platforms supported by DPDK.
-
-.. include:: ../linux_gsg/eal_args.include.rst
-
-FreeBSD-specific EAL parameters
--------------------------------
-
-There are currently no FreeBSD-specific EAL command-line parameters available.
diff --git a/doc/guides/freebsd_gsg/index.rst b/doc/guides/freebsd_gsg/index.rst
index 9af5988dc..fdb4df32e 100644
--- a/doc/guides/freebsd_gsg/index.rst
+++ b/doc/guides/freebsd_gsg/index.rst
@@ -14,4 +14,3 @@ Getting Started Guide for FreeBSD
     install_from_ports
     build_dpdk
     build_sample_apps
-    freebsd_eal_parameters
-- 
2.21.0

Re: [dpdk-dev] [PATCH v2 8/8] doc: drop EAL command-line reference from FreeBSD GSG

[Burakov, Anatoly]

On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> The EAL command-line reference section duplicated material covered in a
> previous chapter, was out of date, and generally is unnecessary as options
> are best queried directly by passing "--help" to a DPDK binary. Therefore
> we can drop this section to avoid having to try and keep it up-to-date in
> the future.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

While passing --help works, i believe the parameter guides are a little 
bit more detailed than what you can put in a help message, so there 
still is a place for those. FreeBSD doesn't have FreeBSD-specific 
parameters, so in this case it's probably OK to drop this particular 
document, but it would still be nice to refer users to the common EAL 
arguments guide.

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH v2 8/8] doc: drop EAL command-line reference from FreeBSD GSG

[Bruce Richardson]

On Wed, Nov 27, 2019 at 12:31:10PM +0000, Burakov, Anatoly wrote:
> On 25-Nov-19 2:55 PM, Bruce Richardson wrote:
> > The EAL command-line reference section duplicated material covered in a
> > previous chapter, was out of date, and generally is unnecessary as options
> > are best queried directly by passing "--help" to a DPDK binary. Therefore
> > we can drop this section to avoid having to try and keep it up-to-date in
> > the future.
> > 
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> 
> While passing --help works, i believe the parameter guides are a little bit
> more detailed than what you can put in a help message, so there still is a
> place for those. FreeBSD doesn't have FreeBSD-specific parameters, so in
> this case it's probably OK to drop this particular document, but it would
> still be nice to refer users to the common EAL arguments guide.
> 
Ok. Let's drop this patch from the set for 19.11, then.

/Bruce

[dpdk-dev] [PATCH v3 0/5] GSG Documentation updates

[Bruce Richardson]

This patchset includes documentation updates for both the Linux and
FreeBSD Getting Started Guide Docs. The majority of changes are to add
information on building using meson and ninja, with some additional
cleanups being performed at the same time.

V3: 
 * Updated patch 1 following feedback from Thomas
 * Dropped the final 3 patches for 19.11. Post 19.11 I'm hoping to
   update the BSD port to support 19.11 and have it use meson and ninja
   to build. Since this will require rework to the BSD GSG then anyway,
   other major changes to that doc can be held off until that time too.

V2: Updated patch 2 following feedback from Anatoly

Bruce Richardson (5):
  doc: update Linux GSG system requirements section
  doc: add building with meson to linux GSG
  doc: reorder meson and make build instructions for arm
  doc: remove reference to old versions of FreeBSD
  doc: update examples output in FreeBSD GSG

 doc/guides/freebsd_gsg/install_from_ports.rst |  62 +++-----
 doc/guides/linux_gsg/build_dpdk.rst           | 139 +++++++++++++++++-
 .../linux_gsg/cross_build_dpdk_for_arm64.rst  |  32 ++--
 doc/guides/linux_gsg/sys_reqs.rst             |  68 ++++-----
 4 files changed, 209 insertions(+), 92 deletions(-)

-- 
2.21.0

[dpdk-dev] [PATCH v3 1/5] doc: update Linux GSG system requirements section

[Bruce Richardson]

Update the system requirements section of the doc to cover builds with
meson and ninja. This involves updating the package dependencies to include
meson, ninja and python 3.5, and also updating the optional dependencies
section to explain that the components are enabled/disabled automatically
by meson.

As part of this update, the relevant sections were simplified to keep the
document shorter. For mandatory requirements, we can refer to the various
distro's development tools package groups rather than requiring gcc, core
tools etc. individually. The optional package list was very incomplete, and
if complete would duplicate information in the individual driver's guides.
Therefore we can simplify it by listing only the library optional
requirements and referring users to the driver docs to find details on
their dependencies.

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

---
V3: updated on feedback from Thomas
  * added some compiler version requirements
  * added package names for installing meson/ninja from distros
  * fixed typo
  * added link to network drivers guide
---
 doc/guides/linux_gsg/sys_reqs.rst | 68 ++++++++++++++++---------------
 1 file changed, 35 insertions(+), 33 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index d2359058b..7c47ec04c 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -37,49 +37,32 @@ Compilation of the DPDK
     The setup commands and installed packages needed on various systems may be different.
     For details on Linux distributions and the versions tested, please consult the DPDK Release Notes.
 
-*   GNU ``make``.
+*   General development tools including ``make``, and a supported C compiler such as ``gcc`` (version 4.9+) or ``clang`` (version 3.4+).
 
-*   coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc.
+    * For RHEL/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
 
-*   gcc: versions 4.9 or later is recommended for all platforms.
-    On some distributions, some specific compiler flags and linker flags are enabled by
-    default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
-    of your distribution and to ``gcc -dumpspecs``.
+    * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
 
-*   libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``;
-    ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture;
-    ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;)
+*   Python, recommended version 3.5+.
 
-*   Linux kernel headers or sources required to build kernel modules. (kernel - devel.x86_64;
-    kernel - devel.ppc64)
+    * Python v3.5+ is needed to build DPDK using meson and ninja
 
-*   Additional packages required for 32-bit compilation on 64-bit systems are:
+    * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
 
-    * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64;
+*   Meson (version 0.47.1+) and ninja
 
-    * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64;
+    * ``meson`` & ``ninja-build`` packages in most Linux distributions
 
-    .. note::
-
-       x86_x32 ABI is currently supported with distribution packages only on Ubuntu
-       higher than 13.10 or recent Debian distribution. The only supported  compiler is gcc 4.9+.
+    * If the packaged version is below the minimum version, the latest versions
+      can be installed from Python's "pip" repository: ``pip3 install meson ninja``
 
 *   Library for handling NUMA (Non Uniform Memory Access).
 
-    * numactl-devel in Red Hat/Fedora;
-
-    * libnuma-dev in Debian/Ubuntu;
-
-    .. note::
+    * ``numactl-devel`` in RHEL/Fedora;
 
-        On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`)
-        is a recommended dependency when `--legacy-mem` switch is used,
-        and a *required* dependency if default memory mode is used.
-        While DPDK will compile and run without `libnuma`
-        even on NUMA-enabled systems,
-        both usability and performance will be degraded.
+    * ``libnuma-dev`` in Debian/Ubuntu;
 
-*   Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
+*   Linux kernel headers or sources required to build kernel modules.
 
 .. note::
 
@@ -96,10 +79,29 @@ Compilation of the DPDK
     which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
     it, see the IBM official installation document.
 
-*   libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
-    This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file.
+**Additional Libraries**
+
+A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
+For DPDK builds using meson, the presence or absence of these dependencies will be
+automatically detected enabling or disabling the relevant components appropriately.
+
+For builds using make, these components are disabled in the default configuration and
+need to be enabled manually by changing the relevant setting to "y" in the build configuration file
+i.e. the ``.config`` file in the build folder.
+
+In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
+
+For libraries the additional dependencies include:
+
+*   libarchive: for some unit tests using tar to get their resources.
+
+*   jansson: to compile and use the telemetry library.
+
+*   libelf: to compile and use the bpf library.
 
-*   libarchive headers and library are needed for some unit tests using tar to get their resources.
+For poll-mode drivers, the additional dependencies for each driver can be
+found in that driver's documentation in the relevant DPDK guide document,
+e.g. :doc:`../nics/index`
 
 
 Running DPDK Applications
-- 
2.21.0

[dpdk-dev] [PATCH v3 2/5] doc: add building with meson to linux GSG

[Bruce Richardson]

Add instructions on building DPDK and using the pkg-config file to the
linux GSG.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
V2: Changes following Anatoly's review:
* minor grammar fix
* added ldconfig call to instructions and note about needing to add
  /usr/local/lib* to loader paths on RHEL/Fedora
* added description of -Dexamples option
* added example of using libdpdk from an app meson.build file
---
 doc/guides/linux_gsg/build_dpdk.rst | 139 +++++++++++++++++++++++++++-
 1 file changed, 135 insertions(+), 4 deletions(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 7c0329fcc..4aeb4697d 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -11,8 +11,8 @@ Compiling the DPDK Target from Source
     Parts of this process can also be done using the setup script described in
     the :ref:`linux_setup_script` section of this document.
 
-Install the DPDK and Browse Sources
------------------------------------
+Uncompress DPDK and Browse Sources
+----------------------------------
 
 First, uncompress the archive and move to the uncompressed DPDK source directory:
 
@@ -33,8 +33,139 @@ The DPDK is composed of several directories:
 
 *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
 
-Installation of DPDK Target Environments
-----------------------------------------
+Compiling and Installing DPDK System-wide
+-----------------------------------------
+
+DPDK can be configured, built and installed on your system using the tools
+``meson`` and ``ninja``.
+
+.. note::
+
+  The older makefile-based build system used in older DPDK releases is
+  still present and its use is described in section
+  `Installation of DPDK Target Environment using Make`_.
+
+DPDK Configuration
+~~~~~~~~~~~~~~~~~~
+
+To configure a DPDK build use:
+
+.. code-block:: console
+
+     meson <options> build
+
+where "build" is the desired output build directory, and "<options>" can be
+empty or one of a number of meson or DPDK-specific build options, described
+later in this section. The configuration process will finish with a summary
+of what DPDK libraries and drivers are to be built and installed, and for
+each item disabled, a reason why that is the case. This information can be
+used, for example, to identify any missing required packages for a driver.
+
+Once configured, to build and then install DPDK system-wide use:
+
+.. code-block:: console
+
+        cd build
+        ninja
+        ninja install
+        ldconfig
+
+The last two commands above generally need to be run as root,
+with the `ninja install` step copying the built objects to their final system-wide locations,
+and the last step causing the dynamic loader `ld.so` to update its cache to take account of the new objects.
+
+.. note::
+
+   On some linux distributions, such as Fedora or Redhat, paths in `/usr/local` are
+   not in the default paths for the loader. Therefore, on these
+   distributions, `/usr/local/lib` and `/usr/local/lib64` should be added
+   to a file in `/etc/ld.so.conf.d/` before running `ldconfig`.
+
+
+Adjusting Build Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+DPDK has a number of options that can be adjusted as part of the build configuration process.
+These options can be listed by running ``meson configure`` inside a configured build folder.
+Many of these options come from the "meson" tool itself and can be seen documented on the
+`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
+
+For example, to change the build-type from the default, "debugoptimized",
+to a regular "debug" build, you can either:
+
+* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
+
+Other options are specific to the DPDK project but can be adjusted similarly.
+To set the "max_lcores" value to 256, for example, you can either:
+
+* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
+
+Some of the DPDK sample applications in the `examples` directory can be
+automatically built as part of a meson build too.
+To do so, pass a comma-separated list of the examples to build to the
+`-Dexamples` meson option as below::
+
+  meson -Dexamples=l2fwd,l3fwd build
+
+As with other meson options, this can also be set post-initial-config using `meson configure` in the build directory.
+There is also a special value "all" to request that all example applications whose
+dependencies are met on the current system are built.
+When `-Dexamples=all` is set as a meson option, meson will check each example application to see if it can be built,
+and add all which can be built to the list of tasks in the ninja build configuration file.
+
+Building Applications Using Installed DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
+It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
+for DPDK into the application build process.
+
+An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
+A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
+and the sources for that build are stored in ``$(SRCS-y)``.
+
+.. code-block:: makefile
+
+        PKGCONF = pkg-config
+
+        CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
+        LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
+
+        $(APP): $(SRCS-y) Makefile
+                $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
+
+.. note::
+
+   Unlike with the older make build system, the meson system is not
+   designed to be used directly from a build directory. Instead it is
+   recommended that it be installed either system-wide or to a known
+   location in the user's home directory. The install location can be set
+   using the `--prefix` meson option (default: `/usr/local`).
+
+an equivalent build recipe for a simple DPDK application using meson as a
+build system is shown below:
+
+.. code-block:: python
+
+   project('dpdk-app', 'c')
+
+   dpdk = dependency('libdpdk')
+   sources = files('main.c')
+   executable('dpdk-app', sources, dependencies: dpdk)
+
+
+Installation of DPDK Target Environment using Make
+--------------------------------------------------
+
+.. note::
+
+   The building of DPDK using make will be deprecated in a future release. It
+   is therefore recommended that DPDK installation is done using meson and
+   ninja as described above.
 
 The format of a DPDK target is::
 
-- 
2.21.0

[dpdk-dev] [PATCH v3 3/5] doc: reorder meson and make build instructions for arm

[Bruce Richardson]

Since the meson instructions are the simpler of the two sets, and also the
ones most future-proof, put those first in the user documentation with make
instructions following them.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Gavin Hu <gavin.hu@arm.com>
---
 .../linux_gsg/cross_build_dpdk_for_arm64.rst  | 32 ++++++++++---------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
index e799b0ba4..8c87a595e 100644
--- a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
+++ b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
@@ -77,8 +77,23 @@ Copy the NUMA header files and lib to the cross compiler's directories:
 
 .. _configure_and_cross_compile_dpdk_build:
 
-Configure and cross compile DPDK Build
---------------------------------------
+Cross Compiling DPDK using Meson
+--------------------------------
+
+To cross-compile DPDK on a desired target machine we can use the following
+command::
+
+	meson cross-build --cross-file <target_machine_configuration>
+	ninja -C cross-build
+
+For example if the target machine is arm64 we can use the following
+command::
+
+	meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
+	ninja -C arm64-build
+
+Configure and Cross Compile DPDK using Make
+-------------------------------------------
 To configure a build, choose one of the target configurations, like arm64-dpaa-linux-gcc and arm64-thunderx-linux-gcc.
 
 .. code-block:: console
@@ -119,17 +134,4 @@ To compile for non-NUMA targets, without compiling the kernel modules, use the f
 
       make -j CROSS=aarch64-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n EXTRA_CFLAGS="-isystem <numa_install_dir>/include" EXTRA_LDFLAGS="-L<numa_install_dir>/lib -lnuma"
 
-Meson Cross Compiling DPDK
---------------------------
-
-To cross-compile DPDK on a desired target machine we can use the following
-command::
-
-	meson cross-build --cross-file <target_machine_configuration>
-	ninja -C cross-build
-
-For example if the target machine is arm64 we can use the following
-command::
 
-	meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
-	ninja -C arm64-build
-- 
2.21.0

[dpdk-dev] [PATCH v3 4/5] doc: remove reference to old versions of FreeBSD

[Bruce Richardson]

FreeBSD 10 is now EOL and all testing with DPDK takes place on BSD versions
11 and 12, so we can just remove the note. The BSD ports are supported on
all non-EOL versions of BSD.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
 doc/guides/freebsd_gsg/install_from_ports.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
index a895d6180..4b0447584 100644
--- a/doc/guides/freebsd_gsg/install_from_ports.rst
+++ b/doc/guides/freebsd_gsg/install_from_ports.rst
@@ -11,12 +11,6 @@ install it from the ports collection. Details of getting and using the ports
 collection are documented in the
 `FreeBSD Handbook <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html>`_.
 
-.. note::
-
-    Testing has been performed using FreeBSD 10.0-RELEASE (x86_64) and requires the
-    installation of the kernel sources, which should be included during the
-    installation of FreeBSD.
-
 Installing the DPDK FreeBSD Port
 --------------------------------
 
-- 
2.21.0

[dpdk-dev] [PATCH v3 5/5] doc: update examples output in FreeBSD GSG

[Bruce Richardson]

The output of running the helloworld example on FreeBSD was a little
out-of-date and can be shortened by using the latest version of DPDK.
Update appropriately.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
 doc/guides/freebsd_gsg/install_from_ports.rst | 56 ++++++++-----------
 1 file changed, 22 insertions(+), 34 deletions(-)

diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst
index 4b0447584..29f16cc6c 100644
--- a/doc/guides/freebsd_gsg/install_from_ports.rst
+++ b/doc/guides/freebsd_gsg/install_from_ports.rst
@@ -84,48 +84,36 @@ compiled and run as below:
       INSTALL-APP helloworld
       INSTALL-MAP helloworld.map
 
-    sudo ./build/helloworld -l 0-3 -n 2
-
-    EAL: Contigmem driver has 2 buffers, each of size 1GB
+    sudo ./build//helloworld -l 0-3
     EAL: Sysctl reports 8 cpus
-    EAL: Detected lcore 0
-    EAL: Detected lcore 1
-    EAL: Detected lcore 2
-    EAL: Detected lcore 3
-    EAL: Support maximum 64 logical core(s) by configuration.
-    EAL: Detected 4 lcore(s)
-    EAL: Setting up physically contiguous memory...
-    EAL: Mapped memory segment 1 @ 0x802400000: len 1073741824
-    EAL: Mapped memory segment 2 @ 0x842400000: len 1073741824
-    EAL: WARNING: clock_gettime cannot use CLOCK_MONOTONIC_RAW and HPET
-         is not available - clock timings may be less accurate.
-    EAL: TSC frequency is ~3569023 KHz
-    EAL: PCI scan found 24 devices
-    EAL: Master core 0 is ready (tid=0x802006400)
-    EAL: Core 1 is ready (tid=0x802006800)
-    EAL: Core 3 is ready (tid=0x802007000)
-    EAL: Core 2 is ready (tid=0x802006c00)
+    EAL: Detected 8 lcore(s)
+    EAL: Detected 1 NUMA nodes
+    EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
+    EAL: Selected IOVA mode 'PA'
+    EAL: Contigmem driver has 2 buffers, each of size 1GB
+    EAL: Mapped memory segment 0 @ 0x1040000000: physaddr:0x180000000, len 1073741824
+    EAL: Mapped memory segment 1 @ 0x1080000000: physaddr:0x1c0000000, len 1073741824
+    EAL: PCI device 0000:00:19.0 on NUMA socket 0
+    EAL:   probe driver: 8086:153b net_e1000_em
+    EAL:   0000:00:19.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.0 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x80074a000
-    EAL:   PCI memory mapped at 0x8007ca000
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.1 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x8007ce000
-    EAL:   PCI memory mapped at 0x80084e000
-    EAL: PCI device 0000:02:00.0 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x800852000
-    EAL:   PCI memory mapped at 0x8008d2000
-    EAL: PCI device 0000:02:00.1 on NUMA socket 0
-    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
-    EAL:   PCI memory mapped at 0x801b3f000
-    EAL:   PCI memory mapped at 0x8008d6000
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.1 not managed by UIO driver, skipping
+    EAL: PCI device 0000:01:00.2 on NUMA socket 0
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.2 not managed by UIO driver, skipping
+    EAL: PCI device 0000:01:00.3 on NUMA socket 0
+    EAL:   probe driver: 8086:1572 net_i40e
+    EAL:   0000:01:00.3 not managed by UIO driver, skipping
     hello from core 1
     hello from core 2
     hello from core 3
     hello from core 0
 
+
 .. note::
 
    To run a DPDK process as a non-root user, adjust the permissions on
-- 
2.21.0

Re: [dpdk-dev] [PATCH v3 0/5] GSG Documentation updates

[Thomas Monjalon]

28/11/2019 17:33, Bruce Richardson:
> This patchset includes documentation updates for both the Linux and
> FreeBSD Getting Started Guide Docs. The majority of changes are to add
> information on building using meson and ninja, with some additional
> cleanups being performed at the same time.
> 
> V3: 
>  * Updated patch 1 following feedback from Thomas
>  * Dropped the final 3 patches for 19.11. Post 19.11 I'm hoping to
>    update the BSD port to support 19.11 and have it use meson and ninja
>    to build. Since this will require rework to the BSD GSG then anyway,
>    other major changes to that doc can be held off until that time too.
> 
> V2: Updated patch 2 following feedback from Anatoly
> 
> Bruce Richardson (5):
>   doc: update Linux GSG system requirements section
>   doc: add building with meson to linux GSG
>   doc: reorder meson and make build instructions for arm
>   doc: remove reference to old versions of FreeBSD
>   doc: update examples output in FreeBSD GSG

Applied, thanks

Re: [dpdk-dev] [PATCH v3 0/5] GSG Documentation updates

[Bruce Richardson]

On Thu, Nov 28, 2019 at 07:56:42PM +0100, Thomas Monjalon wrote:
> 28/11/2019 17:33, Bruce Richardson:
> > This patchset includes documentation updates for both the Linux and
> > FreeBSD Getting Started Guide Docs. The majority of changes are to add
> > information on building using meson and ninja, with some additional
> > cleanups being performed at the same time.
> > 
> > V3: 
> >  * Updated patch 1 following feedback from Thomas
> >  * Dropped the final 3 patches for 19.11. Post 19.11 I'm hoping to
> >    update the BSD port to support 19.11 and have it use meson and ninja
> >    to build. Since this will require rework to the BSD GSG then anyway,
> >    other major changes to that doc can be held off until that time too.
> > 
> > V2: Updated patch 2 following feedback from Anatoly
> > 
> > Bruce Richardson (5):
> >   doc: update Linux GSG system requirements section
> >   doc: add building with meson to linux GSG
> >   doc: reorder meson and make build instructions for arm
> >   doc: remove reference to old versions of FreeBSD
> >   doc: update examples output in FreeBSD GSG
> 
> Applied, thanks
> 
Thanks,

For reference, the dropped patches from V2 should now be covered by set:
http://patches.dpdk.org/project/dpdk/list/?series=7980

/Bruce