1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2019 Microsoft Corporation 3 */ 4 5 /** 6 * @file 7 * RTE pcapng 8 * 9 * @warning 10 * @b EXPERIMENTAL: 11 * All functions in this file may be changed or removed without prior notice. 12 * 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. 16 * 17 * For details about the file format see RFC: 18 * https://www.ietf.org/id/draft-tuexen-opsawg-pcapng-03.html 19 * and 20 * https://github.com/pcapng/pcapng/ 21 */ 22 23 #ifndef _RTE_PCAPNG_H_ 24 #define _RTE_PCAPNG_H_ 25 26 #include <stdint.h> 27 #include <sys/types.h> 28 #include <rte_compat.h> 29 #include <rte_mempool.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /* Opaque handle used for functions in this library. */ 36 typedef struct rte_pcapng rte_pcapng_t; 37 38 /** 39 * Write data to existing open file 40 * 41 * @param fd 42 * file descriptor 43 * @param osname 44 * Optional description of the operating system. 45 * Examples: "Debian 11", "Windows Server 22" 46 * @param hardware 47 * Optional description of the hardware used to create this file. 48 * Examples: "x86 Virtual Machine" 49 * @param appname 50 * Optional: application name recorded in the pcapng file. 51 * Example: "dpdk-dumpcap 1.0 (DPDK 20.11)" 52 * @param comment 53 * Optional comment to add to file header. 54 * @return 55 * handle to library, or NULL in case of error (and rte_errno is set). 56 */ 57 __rte_experimental 58 rte_pcapng_t * 59 rte_pcapng_fdopen(int fd, 60 const char *osname, const char *hardware, 61 const char *appname, const char *comment); 62 63 /** 64 * Close capture file 65 * 66 * @param self 67 * handle to library 68 */ 69 __rte_experimental 70 void 71 rte_pcapng_close(rte_pcapng_t *self); 72 73 /** 74 * Add interface information to the capture file 75 * 76 * @param self 77 * The handle to the packet capture file 78 * @param port 79 * The Ethernet port to report stats on. 80 * @param ifname (optional) 81 * Interface name to record in the file. 82 * If not specified, name will be constructed from port 83 * @param ifdescr (optional) 84 * Interface description to record in the file. 85 * @param filter 86 * Capture filter to record in the file. 87 * 88 * Interfaces must be added to the output file after opening 89 * and before any packet record. All ports used in packet capture 90 * must be added. 91 */ 92 __rte_experimental 93 int 94 rte_pcapng_add_interface(rte_pcapng_t *self, uint16_t port, 95 const char *ifname, const char *ifdescr, 96 const char *filter); 97 98 /** 99 * Direction flag 100 * These should match Enhanced Packet Block flag bits 101 */ 102 enum rte_pcapng_direction { 103 RTE_PCAPNG_DIRECTION_UNKNOWN = 0, 104 RTE_PCAPNG_DIRECTION_IN = 1, 105 RTE_PCAPNG_DIRECTION_OUT = 2, 106 }; 107 108 /** 109 * Format an mbuf for writing to file. 110 * 111 * @param port_id 112 * The Ethernet port on which packet was received 113 * or is going to be transmitted. 114 * @param queue 115 * The queue on the Ethernet port where packet was received 116 * or is going to be transmitted. 117 * @param mp 118 * The mempool from which the "clone" mbufs are allocated. 119 * @param m 120 * The mbuf to copy 121 * @param length 122 * The upper limit on bytes to copy. Passing UINT32_MAX 123 * means all data (after offset). 124 * @param timestamp 125 * The timestamp in TSC cycles. 126 * @param direction 127 * The direction of the packer: receive, transmit or unknown. 128 * @param comment 129 * Packet comment. 130 * 131 * @return 132 * - The pointer to the new mbuf formatted for pcapng_write 133 * - NULL if allocation fails. 134 * 135 */ 136 __rte_experimental 137 struct rte_mbuf * 138 rte_pcapng_copy(uint16_t port_id, uint32_t queue, 139 const struct rte_mbuf *m, struct rte_mempool *mp, 140 uint32_t length, uint64_t timestamp, 141 enum rte_pcapng_direction direction, const char *comment); 142 143 144 /** 145 * Determine optimum mbuf data size. 146 * 147 * @param length 148 * The largest packet that will be copied. 149 * @return 150 * The minimum size of mbuf data to handle packet with length bytes. 151 * Accounting for required header and trailer fields 152 */ 153 __rte_experimental 154 uint32_t 155 rte_pcapng_mbuf_size(uint32_t length); 156 157 /** 158 * Write packets to the capture file. 159 * 160 * Packets to be captured are copied by rte_pcapng_copy() 161 * and then this function is called to write them to the file. 162 * 163 * @warning 164 * Do not pass original mbufs from transmit or receive 165 * or file will be invalid pcapng format. 166 * 167 * @param self 168 * The handle to the packet capture file 169 * @param pkts 170 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures 171 * which contain the output packets 172 * @param nb_pkts 173 * The number of packets to write to the file. 174 * @return 175 * The number of bytes written to file, -1 on failure to write file. 176 * The mbuf's in *pkts* are always freed. 177 */ 178 __rte_experimental 179 ssize_t 180 rte_pcapng_write_packets(rte_pcapng_t *self, 181 struct rte_mbuf *pkts[], uint16_t nb_pkts); 182 183 /** 184 * Write an Interface statistics block. 185 * For statistics, use 0 if don't know or care to report it. 186 * Should be called before closing capture to report results. 187 * 188 * @param self 189 * The handle to the packet capture file 190 * @param port 191 * The Ethernet port to report stats on. 192 * @param comment 193 * Optional comment to add to statistics. 194 * @param start_time 195 * The time when packet capture was started in nanoseconds. 196 * Optional: can be zero if not known. 197 * @param end_time 198 * The time when packet capture was stopped in nanoseconds. 199 * Optional: can be zero if not finished; 200 * @param ifrecv 201 * The number of packets received by capture. 202 * Optional: use UINT64_MAX if not known. 203 * @param ifdrop 204 * The number of packets missed by the capture process. 205 * Optional: use UINT64_MAX if not known. 206 * @return 207 * number of bytes written to file, -1 on failure to write file 208 */ 209 __rte_experimental 210 ssize_t 211 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port, 212 const char *comment, 213 uint64_t start_time, uint64_t end_time, 214 uint64_t ifrecv, uint64_t ifdrop); 215 216 #ifdef __cplusplus 217 } 218 #endif 219 220 #endif /* _RTE_PCAPNG_H_ */ 221