share/man/man9/iflibtxrx.9

   1 .\" $FreeBSD$
   2 .Dd December 17, 2020
   3 .Dt IFLIBTXTX 9
   4 .Os
   5 .Sh NAME
   6 .Nm iflibtxrx
   7 .Nd Device Dependent Transmit and Receive Functions
   8 .Sh SYNOPSIS
   9 .In "ifdi_if.h"
  10 .Ss "Interface Manipulation Functions"
  11 .Ft int
  12 .Fo isc_txd_encap
  13 .Fa "void *sc"
  14 .Fa "if_pkt_info_t pi"
  15 .Fc
  16 .Ft void
  17 .Fo isc_txd_flush
  18 .Fa "void *sc"
  19 .Fa "uint16_t qid"
  20 .Fa "uint32_t _pidx_or_credits_"
  21 .Fc
  22 .Ft int
  23 .Fo isc_txd_credits_update
  24 .Fa "void *sc"
  25 .Fa "uint16_t qid"
  26 .Fa "bool clear"
  27 .Fc
  28 .Ft int
  29 .Fo isc_rxd_available
  30 .Fa "void *sc"
  31 .Fa "uint16_t qsid"
  32 .Fa "uint32_t cidx"
  33 .Fc
  34 .Ft void
  35 .Fo isc_rxd_refill
  36 .Fa "void *sc"
  37 .Fa "uint16_t qsid"
  38 .Fa "uint8_t flid"
  39 .Fa "uint32_t pidx"
  40 .Fa "uint64_t *paddrs"
  41 .Fa "caddr_t *vaddrs"
  42 .Fa "uint16_t count"
  43 .Fc
  44 .Ft void
  45 .Fo isc_rxd_flush
  46 .Fa "void *sc"
  47 .Fa "uint16_t qsid"
  48 .Fa "uint8_t flid"
  49 .Fa "uint32_t pidx"
  50 .Fc
  51 .Ft int
  52 .Fo isc_rxd_pkt_get
  53 .Fa "void *sc"
  54 .Fa "if_rxd_info_t ri"
  55 .Fc
  56 .Ss "Global Variables"
  57 .Vt extern struct if_txrx
  58 .Sh DATA STRUCTURES
  59 The device dependent mechanisms for handling packet transmit and receive are
  60 primarily defined by the functions named above.
  61 The if_pkt_info data structure contains statistics and identifying info
  62 necessary for packet transmission.
  63 While the data structure for packet receipt is the if_rxd_info structure.
  64 .Pp
  65 .Ss The if_pkt_info Structure
  66 The fields of
  67 .Vt "struct if_pkt_info"
  68 are as follows:
  69 .Bl -tag -width ".Va if_capabilities" -offset indent
  70 .It Va ipi_len
  71 .Pq Vt "uint32_t"
  72 Denotes the size of packet to be sent on the transmit queue.
  73 .It Va ipi_segs
  74 .Pq Vt "bus_dma_segment_t *"
  75 A pointer to the bus_dma_segment of the device independent transfer queue
  76 defined in iflib.
  77 .It Va ipi_qsidx
  78 Unique index value assigned sequentially to each transmit queue.
  79 Used to reference the currently transmitting queue.
  80 .It Va ipi_nsegs
  81 .Pq Vt "uint16_t"
  82 Number of descriptors to be read into the device dependent transfer
  83 descriptors.
  84 .It Va ipi_ndescs
  85 .Pq Vt "uint16_t"
  86 Number of descriptors in use.
  87 Calculated by subtracting the old pidx value from the new pidx value.
  88 .It Va ipi_flags
  89 .Pq Vt "uint16_t"
  90 Flags defined on a per packet basis.
  91 .It Va ipi_pidx
  92 .Pq Vt "uint32_t"
  93 Value of first pidx sent to the isc_encap function for encapsulation and
  94 subsequent transmission.
  95 .It Va ipi_new_pidx
  96 .Pq Vt "uint32_t"
  97 Value set after the termination of the isc_encap function.
  98 This value will become the first pidx sent to the isc-encap the next time that
  99 the function is called.
 100 .It Va \fBThe Following Fields Are Used For Offload Handling\fP
 101 .It Va ipi_csum_flags
 102 .Pq Vt "uint64_t"
 103 Flags describing the checksum values, used on a per packet basis.
 104 .It Va ipi_tso_segsz
 105 .Pq Vt "uint16_t"
 106 Size of the TSO Segment Size.
 107 .It Va ipi_mflags
 108 .Pq Vt "uint16_t"
 109 Flags describing the operational parameters of the mbuf.
 110 .It Va ipi_vtag
 111 .Pq Vt "uint16_t"
 112 Contains the VLAN information in the Ethernet Frame.
 113 .It Va ipi_etype
 114 .Pq Vt "uint16_t"
 115 Type of ethernet header protocol as contained by the struct ether_vlan_header.
 116 .It Va ipi_ehrdlen
 117 .Pq Vt "uint8_t"
 118 Length of the Ethernet Header.
 119 .It Va ipi_ip_hlen
 120 .Pq Vt "uint8_t"
 121 Length of the TCP Header
 122 .It Va ipi_tcp_hlen
 123 .Pq Vt "uint8_t"
 124 Length of the TCP Header.
 125 .It Va ipi_tcp_hflags
 126 .Pq Vt "uint8_t"
 127 Flags describing the operational parameters of the TCP Header.
 128 .It Va ipi_ipproto
 129 .Pq Vt "uint8_t"
 130 Specifies the type of IP Protocol in use.
 131 Example TCP, UDP, or SCTP.
 132 .El
 133 .Ss The if_rxd_info Structure
 134 The fields of
 135 .Vt "struct if_rxd_info"
 136 are as follows:
 137 .Bl -tag -width ".Va if_capabilities" -offset indent
 138 .It Va iri_qsidx
 139 .Pq Vt "uint16_t"
 140 Unique index value assigned sequentially to each receive queue.
 141 Used to reference the currently receiving queue.
 142 .It Va iri_vtag
 143 .Pq Vt "uint16_t"
 144 Contains the VLAN information in the Ethernet Frame.
 145 .It Va iri_len
 146 .Pq Vt "uint16_t"
 147 Denotes the size of a received packet.
 148 .It Va iri_next_offset
 149 .Pq Vt "uint16_t"
 150 Denotes the offset value for the next packet to be receive.
 151 A Null value signifies the end of packet.
 152 .It Va iri_cidx
 153 .Pq Vt "uint32_t"
 154 Denotes the index value of the packet currently being processed in the
 155 consumer queue.
 156 .It Va iri_flowid
 157 .Pq Vt "uint32_t"
 158 Value of the RSS hash for the packet.
 159 .It Va iri_flags
 160 .Pq Vt "uint"
 161  Flags describing the operational parameters of the mbuf contained in the
 162  receive packet.
 163 .It Va iri_csum_flags
 164 .Pq Vt "uint32_t"
 165 Flags describing the checksum value contained in the receive packet.
 166 .It Va iri_csum_data
 167 .Pq Vt "uint32_t"
 168 Checksum data contained in the
 169 .Xr mbuf 9
 170 packet header.
 171 .It Va iri_m
 172 .Pq Vt "struct mbuf *"
 173 A mbuf for drivers that manage their own receive queues.
 174 .It Va iri_ifp
 175 .Pq Vt "struct ifnet *"
 176 A link back to the interface structure.
 177 Utilized by drivers that have multiple interface per softc.
 178 .It Va iri_rsstype
 179 .Pq Vt "uint8_t"
 180 The value of the RSS hash type.
 181 .It Va iri_pad
 182 .Pq Vt "uint8_t"
 183 The length of any padding contained by the received data.
 184 .It Va iri_qidx
 185 .Pq Vt "uint8_t"
 186 Represents the type of queue event.
 187 If value >= 0 then it is the freelist id otherwise it is a completion queue
 188 event.
 189 .El
 190 .Sh FUNCTIONS
 191 All function calls are associated exclusively with either packet transmission
 192 or receipt.
 193 The void *sc passed as the first argument to all of the following functions
 194 represents the driver's softc.
 195 .Ss Transmit Packet Functions
 196 .Bl -ohang -offset indent
 197 .It Fn isc_txd_encap
 198 Transmit function that sends a packet on an interface.
 199 The if_pkt_info data structure contains data information fields describing the
 200 packet.
 201 This function returns 0 if successful, otherwise an error value is returned.
 202 .It Fn isc_txd_flush
 203 Flush function is called immediately after the isc_txd_encap function transmits
 204 a packet.
 205 It updates the hardware producer index or increments the descriptors used to
 206 pidx_or_credits in the queue designated by the qid number.
 207 This is often referred to as poking the doorbell register.
 208 .It Fn isc_txd_credits_update
 209 Credit function advances the buffer ring and calculates the credits
 210 (descriptors) processed.
 211 Until the I/O is complete it cleans the range in case of multisegments and
 212 updates the count of processed packets.
 213 The function returns the number of processed credits.
 214 .El
 215 .Ss Receive Packet Functions
 216 .Bl -ohang -offset indent
 217 .It Fn isc_rxd_available
 218 Function calculates the remaining number of descriptors from a position given
 219 by idx.
 220 The function returns this value.
 221 .It Fn isc_rxd_refill
 222 Starting with the physical address paddrs, the function reads a packet into the
 223 rx_ring until a value designated by count is reached.
 224 vaddrs is typically not needed and is provided for devices that place their own
 225 metadata in the packet header.
 226 .It Fn isc_rxd_flush
 227 Flush function updates the producer pointer on the free list flid in queue set
 228 number qid to pidx to reflect the presence of new buffers.
 229 .It Fn isc_rxd_pkt_get
 230 Process a single software descriptor.
 231 rxr->rx_base[i] contains a descriptor that describes a received packet.
 232 Hardware specific information about the buffer referred to by ri is returned in
 233 the data structure if_rxd_info
 234 .El
 235 .Sh SEE ALSO
 236 .Xr iflibdd 9 ,
 237 .Xr iflibdi 9 ,
 238 .Xr mbuf 9
 239 .Sh AUTHORS
 240 This manual page was written by
 241 .An Nicole Graziano