242 lines
7.0 KiB
Groff
242 lines
7.0 KiB
Groff
.\" $FreeBSD$
|
|
.Dd December 17, 2020
|
|
.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
|
|
.Fo isc_txd_encap
|
|
.Fa "void *sc"
|
|
.Fa "if_pkt_info_t pi"
|
|
.Fc
|
|
.Ft void
|
|
.Fo isc_txd_flush
|
|
.Fa "void *sc"
|
|
.Fa "uint16_t qid"
|
|
.Fa "uint32_t _pidx_or_credits_"
|
|
.Fc
|
|
.Ft int
|
|
.Fo isc_txd_credits_update
|
|
.Fa "void *sc"
|
|
.Fa "uint16_t qid"
|
|
.Fa "bool clear"
|
|
.Fc
|
|
.Ft int
|
|
.Fo isc_rxd_available
|
|
.Fa "void *sc"
|
|
.Fa "uint16_t qsid"
|
|
.Fa "uint32_t cidx"
|
|
.Fc
|
|
.Ft void
|
|
.Fo isc_rxd_refill
|
|
.Fa "void *sc"
|
|
.Fa "uint16_t qsid"
|
|
.Fa "uint8_t flid"
|
|
.Fa "uint32_t pidx"
|
|
.Fa "uint64_t *paddrs"
|
|
.Fa "caddr_t *vaddrs"
|
|
.Fa "uint16_t count"
|
|
.Fc
|
|
.Ft void
|
|
.Fo isc_rxd_flush
|
|
.Fa "void *sc"
|
|
.Fa "uint16_t qsid"
|
|
.Fa "uint8_t flid"
|
|
.Fa "uint32_t pidx"
|
|
.Fc
|
|
.Ft int
|
|
.Fo isc_rxd_pkt_get
|
|
.Fa "void *sc"
|
|
.Fa "if_rxd_info_t ri"
|
|
.Fc
|
|
.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
|
|
.Xr mbuf 9
|
|
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 argument to all of the following functions
|
|
represents 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
|
|
.Xr iflibdd 9 ,
|
|
.Xr iflibdi 9 ,
|
|
.Xr mbuf 9
|
|
.Sh AUTHORS
|
|
This manual page was written by
|
|
.An Nicole Graziano
|