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