lib/pcapng/rte_pcapng.h

   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_ */