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