When the pdump application is run print a warning.
Add release note about deprecation and mark the API's
as deprecated.
Signed-off-by: Stephen Hemminger <step...@networkplumber.org>
---
app/pdump/main.c | 3 +++
app/pdump/meson.build | 1 +
app/test-pmd/meson.build | 1 +
app/test/meson.build | 6 +++++-
doc/guides/howto/packet_capture_framework.rst | 15 +++++++++------
doc/guides/nics/bnxt.rst | 2 +-
doc/guides/prog_guide/ethdev/index.rst | 1 +
doc/guides/prog_guide/pdump_lib.rst | 4 ++++
doc/guides/rel_notes/deprecation.rst | 3 +++
doc/guides/tools/pdump.rst | 2 ++
lib/pdump/rte_pdump.h | 12 +++++++++---
11 files changed, 39 insertions(+), 11 deletions(-)
diff --git a/app/pdump/main.c b/app/pdump/main.c
index fa85859703..a4e0f4e5ae 100644
--- a/app/pdump/main.c
+++ b/app/pdump/main.c
@@ -986,6 +986,9 @@ main(int argc, char **argv)
char mp_flag[] = "--proc-type=secondary";
char *argp[argc + 2];
+
+ fprintf(stderr, "%s: is deprecated use dpdk-dumpcap instead\n",
argv[0]);
+
/* catch ctrl-c so we can cleanup on exit */
sigemptyset(&action.sa_mask);
sigaction(SIGTERM, &action, NULL);
diff --git a/app/pdump/meson.build b/app/pdump/meson.build
index a4c7dd44e7..1fe034fcb8 100644
--- a/app/pdump/meson.build
+++ b/app/pdump/meson.build
@@ -11,3 +11,4 @@ sources = files('main.c')
deps += ['ethdev', 'kvargs', 'pdump']
cflags += no_wvla_cflag
+cflags += '-Wno-deprecated-declarations'
diff --git a/app/test-pmd/meson.build b/app/test-pmd/meson.build
index e67665028f..3ab8280ce7 100644
--- a/app/test-pmd/meson.build
+++ b/app/test-pmd/meson.build
@@ -60,6 +60,7 @@ if dpdk_conf.has('RTE_LIB_METRICS')
endif
if dpdk_conf.has('RTE_LIB_PDUMP')
deps += 'pdump'
+ cflags += '-Wno-deprecated-declarations'
endif
if dpdk_conf.has('RTE_NET_BNXT')
deps += 'net_bnxt'
diff --git a/app/test/meson.build b/app/test/meson.build
index 07bc00148d..45ece2179c 100644
--- a/app/test/meson.build
+++ b/app/test/meson.build
@@ -138,7 +138,6 @@ source_file_deps = {
'test_net_ip6.c': ['net'],
'test_pcapng.c': ['ethdev', 'net', 'pcapng', 'bus_vdev'],
'test_pdcp.c': ['eventdev', 'pdcp', 'net', 'timer', 'security'],
- 'test_pdump.c': ['pdump'] + sample_packet_forward_deps,
'test_per_lcore.c': [],
'test_pflock.c': [],
'test_pie.c': ['sched'],
@@ -217,6 +216,11 @@ source_file_ext_deps = {
'test_pcapng.c': ['pcap'],
}
+if dpdk_conf.has('RTE_LIB_PDUMP')
+ source_file_deps += { 'test_pdump.c': ['pdump'] +
sample_packet_forward_deps, }
+ cflags += '-Wno-deprecated-declarations'
+endif
+
def_lib = get_option('default_library')
foreach f, f_deps : source_file_deps
has_deps = true
diff --git a/doc/guides/howto/packet_capture_framework.rst
b/doc/guides/howto/packet_capture_framework.rst
index 4099c419aa..995d0fc1ce 100644
--- a/doc/guides/howto/packet_capture_framework.rst
+++ b/doc/guides/howto/packet_capture_framework.rst
@@ -10,11 +10,11 @@ for users of DPDK who want to know more about the Packet
Capture feature and
for those who want to monitor traffic on DPDK-controlled devices.
The DPDK packet capture framework was introduced in DPDK v16.07
-and enhanced in 21.11.
+and enhanced in 21.11, and deprecated in 25.11. It is superseded
+by the new port mirroring facility of ethdev.
+
The DPDK packet capture framework consists of the libraries
-for collecting packets ``librte_pdump``
-and writing packets to a file ``librte_pcapng``.
-There are two sample applications: ``dpdk-dumpcap`` and older ``dpdk-pdump``.
+for collecting packets ``librte_pdump`` and an application ``dpdk-pdump``.
Introduction
------------
@@ -49,10 +49,13 @@ and then to the Pcapng file.
Some things to note:
-* All tools using ``librte_pdump`` can only be used in conjunction with a
primary
+* The ``dpdk-dumpcap`` tool used the ethdev port mirror functionality
+ to transparently mirror packets to an internal ring device.
+
+* Older tools using ``librte_pdump`` can only be used in conjunction with a
primary
application which has the packet capture framework initialized already. In
dpdk, only ``testpmd`` is modified to initialize packet capture framework,
- other applications remain untouched. So, if the ``dpdk-dumpcap`` tool has to
+ other applications remain untouched. So, if the ``dpdk-pdump`` tool has to
be used with any application other than the testpmd, the user needs to
explicitly modify that application to call the packet capture framework
initialization code. Refer to the ``app/test-pmd/testpmd.c`` code and look
diff --git a/doc/guides/nics/bnxt.rst b/doc/guides/nics/bnxt.rst
index 370931fbb0..9534214286 100644
--- a/doc/guides/nics/bnxt.rst
+++ b/doc/guides/nics/bnxt.rst
@@ -723,7 +723,7 @@ Note that the applications cannot update the firmware using
BNXT PMD.
Multiple Processes
~~~~~~~~~~~~~~~~~~
-When two or more DPDK applications (e.g., testpmd and dpdk-pdump) share a
single
+When two or more DPDK applications (e.g., testpmd and dpdk-dumpcap) share a
single
instance of DPDK, the BNXT PMD supports a single primary application and one or
more secondary applications. Note that the DPDK-layer (not the PMD) ensures
there is only one primary application.
diff --git a/doc/guides/prog_guide/ethdev/index.rst
b/doc/guides/prog_guide/ethdev/index.rst
index 392ced0a2e..49c41b5c94 100644
--- a/doc/guides/prog_guide/ethdev/index.rst
+++ b/doc/guides/prog_guide/ethdev/index.rst
@@ -10,6 +10,7 @@ Ethernet Device Library
ethdev
switch_representation
flow_offload
+ port_mirroring
traffic_metering_and_policing
traffic_management
qos_framework
diff --git a/doc/guides/prog_guide/pdump_lib.rst
b/doc/guides/prog_guide/pdump_lib.rst
index 07b9f39d09..eb1ae25fae 100644
--- a/doc/guides/prog_guide/pdump_lib.rst
+++ b/doc/guides/prog_guide/pdump_lib.rst
@@ -9,6 +9,10 @@ The library does the complete copy of the Rx and Tx mbufs to a
new mempool and
hence it slows down the performance of the applications, so it is recommended
to use this library for debugging purposes.
+The pdump functionality will not work if secondary process sends and receives
+packets. This is not easily fixable therefore this library is now deprecated
+and replace by port mirroring functionality of ethdev.
+
The library uses a generic multi process channel to facilitate communication
between primary and secondary process for enabling/disabling packet capture on
ports.
diff --git a/doc/guides/rel_notes/deprecation.rst
b/doc/guides/rel_notes/deprecation.rst
index c91207cab2..6c775eb605 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -175,3 +175,6 @@ Deprecation Notices
without relying on flow API.
Currently there is no alternative API
providing the same functionality as with ``repr_matching_en`` set to 0.
+
+* pdump: The pdump API and application have been deprecated and will
+ be removed in a later release.
diff --git a/doc/guides/tools/pdump.rst b/doc/guides/tools/pdump.rst
index 6f9bd77ab1..ffb8bde192 100644
--- a/doc/guides/tools/pdump.rst
+++ b/doc/guides/tools/pdump.rst
@@ -10,6 +10,8 @@ The ``dpdk-pdump`` tool is a Data Plane Development Kit
(DPDK) tool that runs as
a DPDK secondary process and is capable of enabling packet capture on dpdk
ports.
.. Note::
+ * The ``dpdk-pdump`` is deprecated, use ``dpdk-dumpcap`` instead.
+
* The ``dpdk-pdump`` tool can only be used in conjunction with a primary
application which has the packet capture framework initialized already.
In dpdk, only the ``testpmd`` is modified to initialize packet capture
diff --git a/lib/pdump/rte_pdump.h b/lib/pdump/rte_pdump.h
index 1e32d46097..bfea7c560d 100644
--- a/lib/pdump/rte_pdump.h
+++ b/lib/pdump/rte_pdump.h
@@ -39,6 +39,7 @@ enum {
* @return
* 0 on success, -1 on error
*/
+__rte_deprecated
int
rte_pdump_init(void);
@@ -50,6 +51,7 @@ rte_pdump_init(void);
* @return
* 0 on success, -1 on error
*/
+__rte_deprecated
int
rte_pdump_uninit(void);
@@ -75,7 +77,7 @@ rte_pdump_uninit(void);
* @return
* 0 on success, -1 on error, rte_errno is set accordingly.
*/
-
+__rte_deprecated
int
rte_pdump_enable(uint16_t port, uint16_t queue, uint32_t flags,
struct rte_ring *ring,
@@ -106,6 +108,7 @@ rte_pdump_enable(uint16_t port, uint16_t queue, uint32_t
flags,
* @return
* 0 on success, -1 on error, rte_errno is set accordingly.
*/
+__rte_deprecated
int
rte_pdump_enable_bpf(uint16_t port_id, uint16_t queue,
uint32_t flags, uint32_t snaplen,
@@ -129,7 +132,7 @@ rte_pdump_enable_bpf(uint16_t port_id, uint16_t queue,
* @return
* 0 on success, -1 on error, rte_errno is set accordingly.
*/
-
+__rte_deprecated
int
rte_pdump_disable(uint16_t port, uint16_t queue, uint32_t flags);
@@ -156,7 +159,7 @@ rte_pdump_disable(uint16_t port, uint16_t queue, uint32_t
flags);
* @return
* 0 on success, -1 on error, rte_errno is set accordingly.
*/
-
+__rte_deprecated
int
rte_pdump_enable_by_deviceid(char *device_id, uint16_t queue,
uint32_t flags,
@@ -189,6 +192,7 @@ rte_pdump_enable_by_deviceid(char *device_id, uint16_t
queue,
* @return
* 0 on success, -1 on error, rte_errno is set accordingly.
*/
+__rte_deprecated
int
rte_pdump_enable_bpf_by_deviceid(const char *device_id, uint16_t queue,
uint32_t flags, uint32_t snaplen,
@@ -215,6 +219,7 @@ rte_pdump_enable_bpf_by_deviceid(const char *device_id,
uint16_t queue,
* @return
* 0 on success, -1 on error, rte_errno is set accordingly.
*/
+__rte_deprecated
int
rte_pdump_disable_by_deviceid(char *device_id, uint16_t queue,
uint32_t flags);
@@ -243,6 +248,7 @@ struct rte_pdump_stats {
* @return
* Zero if successful. -1 on error and rte_errno is set.
*/
+__rte_deprecated
int
rte_pdump_stats(uint16_t port_id, struct rte_pdump_stats *stats);
--
2.47.2
