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