1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2019 Microsoft Corporation
11 * All functions in this file may be changed or removed without prior notice.
13 * Pcapng is an evolution from the pcap format, created to address some of
14 * its deficiencies. Namely, the lack of extensibility and inability to store
15 * additional information.
17 * For details about the file format see RFC:
18 * https://www.ietf.org/id/draft-tuexen-opsawg-pcapng-03.html
20 * https://github.com/pcapng/pcapng/
23 #ifndef _RTE_PCAPNG_H_
24 #define _RTE_PCAPNG_H_
27 #include <sys/types.h>
28 #include <rte_compat.h>
29 #include <rte_common.h>
30 #include <rte_mempool.h>
37 /* Opaque handle used for functions in this library. */
38 typedef struct rte_pcapng rte_pcapng_t;
41 * Write data to existing open file
46 * Optional description of the operating system.
47 * Examples: "Debian 11", "Windows Server 22"
49 * Optional description of the hardware used to create this file.
50 * Examples: "x86 Virtual Machine"
52 * Optional: application name recorded in the pcapng file.
53 * Example: "dpdk-dumpcap 1.0 (DPDK 20.11)"
55 * Optional comment to add to file header.
57 * handle to library, or NULL in case of error (and rte_errno is set).
61 rte_pcapng_fdopen(int fd,
62 const char *osname, const char *hardware,
63 const char *appname, const char *comment);
73 rte_pcapng_close(rte_pcapng_t *self);
77 * These should match Enhanced Packet Block flag bits
79 enum rte_pcapng_direction {
80 RTE_PCAPNG_DIRECTION_UNKNOWN = 0,
81 RTE_PCAPNG_DIRECTION_IN = 1,
82 RTE_PCAPNG_DIRECTION_OUT = 2,
86 * Format an mbuf for writing to file.
89 * The Ethernet port on which packet was received
90 * or is going to be transmitted.
92 * The queue on the Ethernet port where packet was received
93 * or is going to be transmitted.
95 * The mempool from which the "clone" mbufs are allocated.
99 * The upper limit on bytes to copy. Passing UINT32_MAX
100 * means all data (after offset).
102 * The timestamp in TSC cycles.
104 * The direction of the packer: receive, transmit or unknown.
107 * - The pointer to the new mbuf formatted for pcapng_write
108 * - NULL if allocation fails.
113 rte_pcapng_copy(uint16_t port_id, uint32_t queue,
114 const struct rte_mbuf *m, struct rte_mempool *mp,
115 uint32_t length, uint64_t timestamp,
116 enum rte_pcapng_direction direction);
120 * Determine optimum mbuf data size.
123 * The largest packet that will be copied.
125 * The minimum size of mbuf data to handle packet with length bytes.
126 * Accounting for required header and trailer fields
130 rte_pcapng_mbuf_size(uint32_t length);
133 * Write packets to the capture file.
135 * Packets to be captured are copied by rte_pcapng_copy()
136 * and then this function is called to write them to the file.
139 * Do not pass original mbufs from transmit or receive
140 * or file will be invalid pcapng format.
143 * The handle to the packet capture file
145 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures
146 * which contain the output packets
148 * The number of packets to write to the file.
150 * The number of bytes written to file, -1 on failure to write file.
151 * The mbuf's in *pkts* are always freed.
155 rte_pcapng_write_packets(rte_pcapng_t *self,
156 struct rte_mbuf *pkts[], uint16_t nb_pkts);
159 * Write an Interface statistics block.
160 * For statistics, use 0 if don't know or care to report it.
161 * Should be called before closing capture to report results.
164 * The handle to the packet capture file
166 * The Ethernet port to report stats on.
168 * Optional comment to add to statistics.
170 * The time when packet capture was started in nanoseconds.
171 * Optional: can be zero if not known.
173 * The time when packet capture was stopped in nanoseconds.
174 * Optional: can be zero if not finished;
176 * The number of packets received by capture.
177 * Optional: use UINT64_MAX if not known.
179 * The number of packets missed by the capture process.
180 * Optional: use UINT64_MAX if not known.
182 * number of bytes written to file, -1 on failure to write file
186 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port,
188 uint64_t start_time, uint64_t end_time,
189 uint64_t ifrecv, uint64_t ifdrop);
195 #endif /* _RTE_PCAPNG_H_ */