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 * Direction flag 75 * These should match Enhanced Packet Block flag bits 76 */ 77 enum rte_pcapng_direction { 78 RTE_PCAPNG_DIRECTION_UNKNOWN = 0, 79 RTE_PCAPNG_DIRECTION_IN = 1, 80 RTE_PCAPNG_DIRECTION_OUT = 2, 81 }; 82 83 /** 84 * Format an mbuf for writing to file. 85 * 86 * @param port_id 87 * The Ethernet port on which packet was received 88 * or is going to be transmitted. 89 * @param queue 90 * The queue on the Ethernet port where packet was received 91 * or is going to be transmitted. 92 * @param mp 93 * The mempool from which the "clone" mbufs are allocated. 94 * @param m 95 * The mbuf to copy 96 * @param length 97 * The upper limit on bytes to copy. Passing UINT32_MAX 98 * means all data (after offset). 99 * @param timestamp 100 * The timestamp in TSC cycles. 101 * @param direction 102 * The direction of the packer: receive, transmit or unknown. 103 * 104 * @return 105 * - The pointer to the new mbuf formatted for pcapng_write 106 * - NULL if allocation fails. 107 * 108 */ 109 __rte_experimental 110 struct rte_mbuf * 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); 115 116 117 /** 118 * Determine optimum mbuf data size. 119 * 120 * @param length 121 * The largest packet that will be copied. 122 * @return 123 * The minimum size of mbuf data to handle packet with length bytes. 124 * Accounting for required header and trailer fields 125 */ 126 __rte_experimental 127 uint32_t 128 rte_pcapng_mbuf_size(uint32_t length); 129 130 /** 131 * Write packets to the capture file. 132 * 133 * Packets to be captured are copied by rte_pcapng_copy() 134 * and then this function is called to write them to the file. 135 * 136 * @warning 137 * Do not pass original mbufs from transmit or receive 138 * or file will be invalid pcapng format. 139 * 140 * @param self 141 * The handle to the packet capture file 142 * @param pkts 143 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures 144 * which contain the output packets 145 * @param nb_pkts 146 * The number of packets to write to the file. 147 * @return 148 * The number of bytes written to file, -1 on failure to write file. 149 * The mbuf's in *pkts* are always freed. 150 */ 151 __rte_experimental 152 ssize_t 153 rte_pcapng_write_packets(rte_pcapng_t *self, 154 struct rte_mbuf *pkts[], uint16_t nb_pkts); 155 156 /** 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. 160 * 161 * @param self 162 * The handle to the packet capture file 163 * @param port 164 * The Ethernet port to report stats on. 165 * @param comment 166 * Optional comment to add to statistics. 167 * @param start_time 168 * The time when packet capture was started in nanoseconds. 169 * Optional: can be zero if not known. 170 * @param end_time 171 * The time when packet capture was stopped in nanoseconds. 172 * Optional: can be zero if not finished; 173 * @param ifrecv 174 * The number of packets received by capture. 175 * Optional: use UINT64_MAX if not known. 176 * @param ifdrop 177 * The number of packets missed by the capture process. 178 * Optional: use UINT64_MAX if not known. 179 * @return 180 * number of bytes written to file, -1 on failure to write file 181 */ 182 __rte_experimental 183 ssize_t 184 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port, 185 const char *comment, 186 uint64_t start_time, uint64_t end_time, 187 uint64_t ifrecv, uint64_t ifdrop); 188 189 #ifdef __cplusplus 190 } 191 #endif 192 193 #endif /* _RTE_PCAPNG_H_ */ 194