.\" $FreeBSD$
.Dd January 27, 2017
.Dt IFlIBTXTX(9)
.Os
.Sh NAME
.Nm iflibtxrx
.Nd Device Dependent Transmit and Receive Functions
.Sh SYNOPSIS
.In "ifdi_if.h"
.Ss "Interface Manipulation Functions"
.Ft int
.Fn isc_txd_encap "void *sc, if_pkt_into_t pi"
.Ft void
.Fn isc_txd_flush "void *sc, uint16_t qid, uint32_t _pidx_or_credits_"
.Ft int *
.Fn isc_txd_credits_update "void *sc, uint16_t qid, uint32_t credits"
.Ft int *
.Fn isc_rxd_available "void *sc, uint16_t qsid, uint32_t cidx"
.Ft void *
.Fn isc_rxd_refill "void *sc, uint16_t qsid, uint8_t flid, uint32_t pidx, uint64_t *paddrs, caddr_t *vaddrs, uint16_t count"
.Ft void *
.Fn isc_rxd_flush "void *sc, uint16_t qsid, uint8_t flid, uint32_t pidx"
.Ft int
.Fn isc_rxd_pkt_get "void *sc, if_rxd_info_t ri"
.Ss "Global Variables"
.Vt extern struct if_txrx
.Sh DATA STRUCTURES
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.     
.Pp
.Ss The if_pkt_info Structure
The fields of
.Vt "struct if_pkt_info"
are as follows:
.Bl -tag -width ".Va if_capabilities" -offset indent
.It Va ipi_len
.Pq Vt "uint32_t"
Denotes the size of packet to be sent on the transmit queue.
.It Va ipi_segs
.Pq Vt "bus_dma_segment_t *"
A pointer to the bus_dma_segment of the device independent transfer queue defined in iflib. 
.It Va ipi_qsidx
Unique index value assigned sequentially to each transmit queue. Used to reference the currently transmitting queue.
.It Va ipi_nsegs
.Pq Vt "uint16_t"
Number of descriptors to be read into the device dependent transfer descriptors. 
.It Va ipi_ndescs
.Pq Vt "uint16_t"
Number of descriptors in use. Calculated by subtracting the old pidx value from the new pidx value.
.It Va ipi_flags
.Pq Vt "uint16_t"
Flags defined on a per packet basis. 
.It Va ipi_pidx
.Pq Vt "uint32_t"
Value of first pidx sent to the isc_encap function for encapsulation and subsequent transmission.
.It Va ipi_new_pidx
.Pq Vt "uint32_t"
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.
.It Va \fBThe Following Fields Are Used For Offload Handling\fP
.It Va ipi_csum_flags
.Pq Vt "uint64_t"
Flags describing the checksum values. Used on a per packet basis.
.It Va ipi_tso_segsz
.Pq Vt "uint16_t"
Size of the TSO Segment Size.
.It Va ipi_mflags
.Pq Vt "uint16_t"
Flags describing the operational parameters of the mbuf.
.It Va ipi_vtag
.Pq Vt "uint16_t"
Contains the VLAN information in the Ethernet Frame.
.It Va ipi_etype
.Pq Vt "uint16_t"
Type of ethernet header protocol as contained by the struct ether_vlan_header.
.It Va ipi_ehrdlen
.Pq Vt "uint8_t"
Length of the Ethernet Header.
.It Va ipi_ip_hlen
.Pq Vt "uint8_t"
Length of the TCP Header
.It Va ipi_tcp_hlen
.Pq Vt "uint8_t"
Length of the TCP Header.
.It Va ipi_tcp_hflags
.Pq Vt "uint8_t"
Flags describing the operational parameters of the TCP Header.
.It Va ipi_ipproto
.Pq Vt "uint8_t"
Specifies the type of IP Protocol in use. Example TCP, UDP, or SCTP.
.El
.Ss The if_rxd_info Structure
The fields of 
.Vt "struct if_rxd_info"
are as follows:
.Bl -tag -width ".Va if_capabilities" -offset indent
.It Va iri_qsidx
.Pq Vt "uint16_t"
Unique index value assigned sequentially to each receive queue. Used to reference the currently receiving queue.
.It Va iri_vtag
.Pq Vt "uint16_t"
Contains the VLAN information in the Ethernet Frame.
.It Va iri_len
.Pq Vt "uint16_t"
Denotes the size of a received packet.
.It Va iri_next_offset
.Pq Vt "uint16_t"
Denotes the offset value for the next packet to be receive. A Null value signifies the end of packet.
.It Va iri_cidx
.Pq Vt "uint32_t"
Denotes the index value of the packet currently being processed in the consumer queue.
.It Va iri_flowid
.Pq Vt "uint32_t"
Value of the RSS hash for the packet.
.It Va iri_flags
.Pq Vt "uint"
 Flags describing the operational parameters of the mbuf contained in the receive packet.
.It Va iri_csum_flags
.Pq Vt "uint32_t"
Flags describing the checksum value contained in the receive packet.
.It Va iri_csum_data
.Pq Vt "uint32_t"
Checksum data contained in the mbuf packet header.
.It Va iri_m
.Pq Vt "struct mbuf *"
A mbuf for drivers that manage their own receive queues.
.It Va iri_ifp
.Pq Vt "struct ifnet *"
A link back to the interface structure. Utilized by drivers that have multiple interface per softc. 
.It Va iri_rsstype
.Pq Vt "uint8_t"
The value of the RSS hash type.
.It Va iri_pad
.Pq Vt "uint8_t"
The length of any padding contained by the received data.
.It Va iri_qidx
.Pq Vt "uint8_t"
Represents the type of queue event. If value >= 0 then it is the freelist id otherwise it is a completion queue event.
.El
.Sh FUNCTIONS
All function calls are associated exclusively with either packet transmission or receipt.
The void *sc passed as the first arguement to all of the following functions repressents the driver's softc.
.Ss Transmit Packet Functions 
.Bl -ohang -offset indent
.It Fn isc_txd_encap
 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.
.It Fn isc_txd_flush
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.
.It Fn isc_txd_credits_update 			
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.
.El
.Ss Receive Packet Functions
.Bl -ohang -offset indent
.It Fn isc_rxd_available
Function calculates the remaining number of descriptors from a position given by idx. The function returns this value.
.It Fn isc_rxd_refill
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.
.It Fn isc_rxd_flush
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.
.It Fn isc_rxd_pkt_get
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
.El
.Sh "SEE ALSO"
 iflibdd(9), iflibdi(9)
.Sh AUTHORS
This manual page was written by
.An Nicole Graziano