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_mempool.h>
35 /* Opaque handle used for functions in this library. */
36 typedef struct rte_pcapng rte_pcapng_t;
39 * Write data to existing open file
44 * Optional description of the operating system.
45 * Examples: "Debian 11", "Windows Server 22"
47 * Optional description of the hardware used to create this file.
48 * Examples: "x86 Virtual Machine"
50 * Optional: application name recorded in the pcapng file.
51 * Example: "dpdk-dumpcap 1.0 (DPDK 20.11)"
53 * Optional comment to add to file header.
55 * handle to library, or NULL in case of error (and rte_errno is set).
59 rte_pcapng_fdopen(int fd,
60 const char *osname, const char *hardware,
61 const char *appname, const char *comment);
71 rte_pcapng_close(rte_pcapng_t *self);
75 * These should match Enhanced Packet Block flag bits
77 enum rte_pcapng_direction {
78 RTE_PCAPNG_DIRECTION_UNKNOWN = 0,
79 RTE_PCAPNG_DIRECTION_IN = 1,
80 RTE_PCAPNG_DIRECTION_OUT = 2,
84 * Format an mbuf for writing to file.
87 * The Ethernet port on which packet was received
88 * or is going to be transmitted.
90 * The queue on the Ethernet port where packet was received
91 * or is going to be transmitted.
93 * The mempool from which the "clone" mbufs are allocated.
97 * The upper limit on bytes to copy. Passing UINT32_MAX
98 * means all data (after offset).
100 * The timestamp in TSC cycles.
102 * The direction of the packer: receive, transmit or unknown.
105 * - The pointer to the new mbuf formatted for pcapng_write
106 * - NULL if allocation fails.
111 rte_pcapng_copy(uint16_t port_id, uint32_t queue,
112 const struct rte_mbuf *m, struct rte_mempool *mp,
113 uint32_t length, uint64_t timestamp,
114 enum rte_pcapng_direction direction);
118 * Determine optimum mbuf data size.
121 * The largest packet that will be copied.
123 * The minimum size of mbuf data to handle packet with length bytes.
124 * Accounting for required header and trailer fields
128 rte_pcapng_mbuf_size(uint32_t length);
131 * Write packets to the capture file.
133 * Packets to be captured are copied by rte_pcapng_copy()
134 * and then this function is called to write them to the file.
137 * Do not pass original mbufs from transmit or receive
138 * or file will be invalid pcapng format.
141 * The handle to the packet capture file
143 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures
144 * which contain the output packets
146 * The number of packets to write to the file.
148 * The number of bytes written to file, -1 on failure to write file.
149 * The mbuf's in *pkts* are always freed.
153 rte_pcapng_write_packets(rte_pcapng_t *self,
154 struct rte_mbuf *pkts[], uint16_t nb_pkts);
157 * Write an Interface statistics block.
158 * For statistics, use 0 if don't know or care to report it.
159 * Should be called before closing capture to report results.
162 * The handle to the packet capture file
164 * The Ethernet port to report stats on.
166 * Optional comment to add to statistics.
168 * The time when packet capture was started in nanoseconds.
169 * Optional: can be zero if not known.
171 * The time when packet capture was stopped in nanoseconds.
172 * Optional: can be zero if not finished;
174 * The number of packets received by capture.
175 * Optional: use UINT64_MAX if not known.
177 * The number of packets missed by the capture process.
178 * Optional: use UINT64_MAX if not known.
180 * number of bytes written to file, -1 on failure to write file
184 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port,
186 uint64_t start_time, uint64_t end_time,
187 uint64_t ifrecv, uint64_t ifdrop);
193 #endif /* _RTE_PCAPNG_H_ */