1.\" $FreeBSD$ 2.Dd March 23, 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.Fo isc_txd_encap 13.Fa "void *sc" 14.Fa "if_pkt_into_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 "uint32_t credits" 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 59The device dependent mechanisms for handling packet transmit and receive are 60primarily defined by the functions named above. 61The if_pkt_info data structure contains statistics and identifying info 62necessary for packet transmission. 63While the data structure for packet receipt is the if_rxd_info structure. 64.Pp 65.Ss The if_pkt_info Structure 66The fields of 67.Vt "struct if_pkt_info" 68are as follows: 69.Bl -tag -width ".Va if_capabilities" -offset indent 70.It Va ipi_len 71.Pq Vt "uint32_t" 72Denotes the size of packet to be sent on the transmit queue. 73.It Va ipi_segs 74.Pq Vt "bus_dma_segment_t *" 75A pointer to the bus_dma_segment of the device independent transfer queue 76defined in iflib. 77.It Va ipi_qsidx 78Unique index value assigned sequentially to each transmit queue. 79Used to reference the currently transmitting queue. 80.It Va ipi_nsegs 81.Pq Vt "uint16_t" 82Number of descriptors to be read into the device dependent transfer 83descriptors. 84.It Va ipi_ndescs 85.Pq Vt "uint16_t" 86Number of descriptors in use. 87Calculated by subtracting the old pidx value from the new pidx value. 88.It Va ipi_flags 89.Pq Vt "uint16_t" 90Flags defined on a per packet basis. 91.It Va ipi_pidx 92.Pq Vt "uint32_t" 93Value of first pidx sent to the isc_encap function for encapsulation and 94subsequent transmission. 95.It Va ipi_new_pidx 96.Pq Vt "uint32_t" 97Value set after the termination of the isc_encap function. 98This value will become the first pidx sent to the isc-encap the next time that 99the 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" 103Flags describing the checksum values, used on a per packet basis. 104.It Va ipi_tso_segsz 105.Pq Vt "uint16_t" 106Size of the TSO Segment Size. 107.It Va ipi_mflags 108.Pq Vt "uint16_t" 109Flags describing the operational parameters of the mbuf. 110.It Va ipi_vtag 111.Pq Vt "uint16_t" 112Contains the VLAN information in the Ethernet Frame. 113.It Va ipi_etype 114.Pq Vt "uint16_t" 115Type of ethernet header protocol as contained by the struct ether_vlan_header. 116.It Va ipi_ehrdlen 117.Pq Vt "uint8_t" 118Length of the Ethernet Header. 119.It Va ipi_ip_hlen 120.Pq Vt "uint8_t" 121Length of the TCP Header 122.It Va ipi_tcp_hlen 123.Pq Vt "uint8_t" 124Length of the TCP Header. 125.It Va ipi_tcp_hflags 126.Pq Vt "uint8_t" 127Flags describing the operational parameters of the TCP Header. 128.It Va ipi_ipproto 129.Pq Vt "uint8_t" 130Specifies the type of IP Protocol in use. 131Example TCP, UDP, or SCTP. 132.El 133.Ss The if_rxd_info Structure 134The fields of 135.Vt "struct if_rxd_info" 136are as follows: 137.Bl -tag -width ".Va if_capabilities" -offset indent 138.It Va iri_qsidx 139.Pq Vt "uint16_t" 140Unique index value assigned sequentially to each receive queue. 141Used to reference the currently receiving queue. 142.It Va iri_vtag 143.Pq Vt "uint16_t" 144Contains the VLAN information in the Ethernet Frame. 145.It Va iri_len 146.Pq Vt "uint16_t" 147Denotes the size of a received packet. 148.It Va iri_next_offset 149.Pq Vt "uint16_t" 150Denotes the offset value for the next packet to be receive. 151A Null value signifies the end of packet. 152.It Va iri_cidx 153.Pq Vt "uint32_t" 154Denotes the index value of the packet currently being processed in the 155consumer queue. 156.It Va iri_flowid 157.Pq Vt "uint32_t" 158Value 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" 165Flags describing the checksum value contained in the receive packet. 166.It Va iri_csum_data 167.Pq Vt "uint32_t" 168Checksum data contained in the 169.Xr mbuf 9 170packet header. 171.It Va iri_m 172.Pq Vt "struct mbuf *" 173A mbuf for drivers that manage their own receive queues. 174.It Va iri_ifp 175.Pq Vt "struct ifnet *" 176A link back to the interface structure. 177Utilized by drivers that have multiple interface per softc. 178.It Va iri_rsstype 179.Pq Vt "uint8_t" 180The value of the RSS hash type. 181.It Va iri_pad 182.Pq Vt "uint8_t" 183The length of any padding contained by the received data. 184.It Va iri_qidx 185.Pq Vt "uint8_t" 186Represents the type of queue event. 187If value >= 0 then it is the freelist id otherwise it is a completion queue 188event. 189.El 190.Sh FUNCTIONS 191All function calls are associated exclusively with either packet transmission 192or receipt. 193The void *sc passed as the first argument to all of the following functions 194represents the driver's softc. 195.Ss Transmit Packet Functions 196.Bl -ohang -offset indent 197.It Fn isc_txd_encap 198Transmit function that sends a packet on an interface. 199The if_pkt_info data structure contains data information fields describing the 200packet. 201This function returns 0 if successful, otherwise an error value is returned. 202.It Fn isc_txd_flush 203Flush function is called immediately after the isc_txd_encap function transmits 204a packet. 205It updates the hardware producer index or increments the descriptors used to 206pidx_or_credits in the queue designated by the qid number. 207This is often referred to as poking the doorbell register. 208.It Fn isc_txd_credits_update 209Credit function advances the buffer ring and calculates the credits 210(descriptors) processed. 211Until the I/O is complete it cleans the range in case of multisegments and 212updates the count of processed packets. 213The 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 218Function calculates the remaining number of descriptors from a position given 219by idx. 220The function returns this value. 221.It Fn isc_rxd_refill 222Starting with the physical address paddrs, the function reads a packet into the 223rx_ring until a value designated by count is reached. 224vaddrs is typically not needed and is provided for devices that place their own 225metadata in the packet header. 226.It Fn isc_rxd_flush 227Flush function updates the producer pointer on the free list flid in queue set 228number qid to pidx to reflect the presence of new buffers. 229.It Fn isc_rxd_pkt_get 230Process a single software descriptor. 231rxr->rx_base[i] contains a descriptor that describes a received packet. 232Hardware specific information about the buffer referred to by ri is returned in 233the 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 240This manual page was written by 241.An Nicole Graziano 242