share/man/man9/iflibtxrx.9

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