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_common.h> 30 #include <rte_mempool.h> 31 #include <rte_ring.h> 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /* Opaque handle used for functions in this library. */ 38 typedef struct rte_pcapng rte_pcapng_t; 39 40 /** 41 * Write data to existing open file 42 * 43 * @param fd 44 * file descriptor 45 * @param osname 46 * Optional description of the operating system. 47 * Examples: "Debian 11", "Windows Server 22" 48 * @param hardware 49 * Optional description of the hardware used to create this file. 50 * Examples: "x86 Virtual Machine" 51 * @param appname 52 * Optional: application name recorded in the pcapng file. 53 * Example: "dpdk-dumpcap 1.0 (DPDK 20.11)" 54 * @param comment 55 * Optional comment to add to file header. 56 * @return 57 * handle to library, or NULL in case of error (and rte_errno is set). 58 */ 59 __rte_experimental 60 rte_pcapng_t * 61 rte_pcapng_fdopen(int fd, 62 const char *osname, const char *hardware, 63 const char *appname, const char *comment); 64 65 /** 66 * Close capture file 67 * 68 * @param self 69 * handle to library 70 */ 71 __rte_experimental 72 void 73 rte_pcapng_close(rte_pcapng_t *self); 74 75 /** 76 * Direction flag 77 * These should match Enhanced Packet Block flag bits 78 */ 79 enum rte_pcapng_direction { 80 RTE_PCAPNG_DIRECTION_UNKNOWN = 0, 81 RTE_PCAPNG_DIRECTION_IN = 1, 82 RTE_PCAPNG_DIRECTION_OUT = 2, 83 }; 84 85 /** 86 * Format an mbuf for writing to file. 87 * 88 * @param port_id 89 * The Ethernet port on which packet was received 90 * or is going to be transmitted. 91 * @param queue 92 * The queue on the Ethernet port where packet was received 93 * or is going to be transmitted. 94 * @param mp 95 * The mempool from which the "clone" mbufs are allocated. 96 * @param m 97 * The mbuf to copy 98 * @param length 99 * The upper limit on bytes to copy. Passing UINT32_MAX 100 * means all data (after offset). 101 * @param timestamp 102 * The timestamp in TSC cycles. 103 * @param direction 104 * The direction of the packer: receive, transmit or unknown. 105 * 106 * @return 107 * - The pointer to the new mbuf formatted for pcapng_write 108 * - NULL if allocation fails. 109 * 110 */ 111 __rte_experimental 112 struct rte_mbuf * 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); 117 118 119 /** 120 * Determine optimum mbuf data size. 121 * 122 * @param length 123 * The largest packet that will be copied. 124 * @return 125 * The minimum size of mbuf data to handle packet with length bytes. 126 * Accounting for required header and trailer fields 127 */ 128 __rte_experimental 129 uint32_t 130 rte_pcapng_mbuf_size(uint32_t length); 131 132 /** 133 * Write packets to the capture file. 134 * 135 * Packets to be captured are copied by rte_pcapng_copy() 136 * and then this function is called to write them to the file. 137 * 138 * @warning 139 * Do not pass original mbufs from transmit or receive 140 * or file will be invalid pcapng format. 141 * 142 * @param self 143 * The handle to the packet capture file 144 * @param pkts 145 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures 146 * which contain the output packets 147 * @param nb_pkts 148 * The number of packets to write to the file. 149 * @return 150 * The number of bytes written to file, -1 on failure to write file. 151 * The mbuf's in *pkts* are always freed. 152 */ 153 __rte_experimental 154 ssize_t 155 rte_pcapng_write_packets(rte_pcapng_t *self, 156 struct rte_mbuf *pkts[], uint16_t nb_pkts); 157 158 /** 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. 162 * 163 * @param self 164 * The handle to the packet capture file 165 * @param port 166 * The Ethernet port to report stats on. 167 * @param comment 168 * Optional comment to add to statistics. 169 * @param start_time 170 * The time when packet capture was started in nanoseconds. 171 * Optional: can be zero if not known. 172 * @param end_time 173 * The time when packet capture was stopped in nanoseconds. 174 * Optional: can be zero if not finished; 175 * @param ifrecv 176 * The number of packets received by capture. 177 * Optional: use UINT64_MAX if not known. 178 * @param ifdrop 179 * The number of packets missed by the capture process. 180 * Optional: use UINT64_MAX if not known. 181 * @return 182 * number of bytes written to file, -1 on failure to write file 183 */ 184 __rte_experimental 185 ssize_t 186 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port, 187 const char *comment, 188 uint64_t start_time, uint64_t end_time, 189 uint64_t ifrecv, uint64_t ifdrop); 190 191 #ifdef __cplusplus 192 } 193 #endif 194 195 #endif /* _RTE_PCAPNG_H_ */ 196