1.\" $FreeBSD$ 2.Dd May 21, 2019 3.Dt IFLIBDI 9 4.Os 5.Sh NAME 6.Nm iflibdi 7.Nd Device Independent Configuration Functions 8.Sh SYNOPSIS 9.In "ifdi_if.h" 10.Ss "Device Independent Functions" 11.Ft int 12.Fo iflib_device_attach 13.Fa "device_t dev" 14.Fc 15.Ft int 16.Fo iflib_device_detach 17.Fa "device_t dev" 18.Fc 19.Ft int 20.Fo iflib_device_suspend 21.Fa "device_t dev" 22.Fc 23.Ft int 24.Fo iflib_device_resume 25.Fa "device_t dev" 26.Fc 27.Ft int 28.Fo iflib_device_register 29.Fa "device_t dev" 30.Fa "void *softc" 31.Fa "if_shared_ctx_t sctx" 32.Fa "if_ctx_t *ctxp" 33.Fc 34.Ft int 35.Fo iflib_device_deregister 36.Fa "if_ctx_t ctx" 37.Fc 38.Ft int 39.Fo iflib_irq_alloc 40.Fa "if_ctx_t ctx" 41.Fa "if_irq_t irq_info" 42.Fa "int rid" 43.Fa "driver_filter_t filter" 44.Fa "void *filter_arg" 45.Fa "driver_intr_t handler" 46.Fa "void *arg" 47.Fa "char *name" 48.Fc 49.Ft int 50.Fo iflib_irq_alloc_generic 51.Fa "if_ctx_t ctx" 52.Fa "if_irq_t irq" 53.Fa "int rid" 54.Fa "intr_type_t type" 55.Fa "driver_filter_t *filter" 56.Fa "void *filter_arg" 57.Fa "int qid" 58.Fa "char *name" 59.Fc 60.Ft void 61.Fo iflib_led_create 62.Fa "if_ctx_t ctx" 63.Fc 64.Ft void 65.Fo iflib_tx_intr_deferred 66.Fa "if_ctx_t ctx" 67.Fa "int txqid" 68.Fc 69.Ft void 70.Fo iflib_rx_intr_deferred 71.Fa "if_ctx_t ctx" 72.Fa "int rxqid" 73.Fc 74.Ft void 75.Fo iflib_link_intr_deferred 76.Fa "if_ctx_t ctx" 77.Fc 78.Ft void 79.Fo iflib_link_state_change 80.Fa "if_ctx_t ctx" 81.Fa "int linkstate" 82.Fc 83.Ft void 84.Fo iflib_add_int_delay_sysctl 85.Fa "if_ctx_t ctx" 86.Fa "const char *" 87.Fa "const char *" 88.Fa "if_int_delay_info_t" 89.Fa "int" 90.Fa "int" 91.Fc 92.Ss "Global Variables" 93.Vt extern struct if_txrx 94.Sh DATA STRUCTURES 95The \fIif_ctx_t\fP Structure is the device independent data structure that 96contains statistics and identifying information used to transmit and receive 97data packets. 98The interface is associated with an array of queues assigned sequentially. 99Each queue has its own transmit (iflib_txq_t) and receive (iflib_rxq_t) queue. 100The transmit queue is used to hold packets while the interface is in the 101process of sending another. 102The receive queue is used to receive packets that are awaiting processing. 103.Ss The if_ctx_t Structure 104The fields of 105.Vt "struct if_ctx_t" 106are as follows: 107.Bl -tag -width ".Va if_capabilities" -offset indent 108.It Va if_softc 109.Pq Vt "void" 110A pointer to the driver's private state block. 111.It Va ifc_dev 112.Pq Vt "device_t" 113The underlying device structure. 114.It Va ifc_ip 115.Pq Vt "if_t" 116A link back to the interface structure 117.It Va ifc_cpus 118.Pq Vt "cpuset_t" 119.It Va ifc_mutex 120.Pq Vt "struct mtx" 121Mutex lock used to maintain data integrity 122.It Va ifc_mtx_name 123.Pq Vt "char *" 124The name of the mutex 125.It Va ifc_txqs 126.Pq Vt "iflib_txq_t" 127Device independent transmit queue maintained internally by iflib 128.It Va ifc_rxqs 129.Pq Vt "iflib_rxq_t" 130Device independent receive queue maintained internally by iflib 131.It Va ifc_qsets 132.Pq Vt "iflib_qset_t" 133Output queue that contains a single transmit (ifc_txq_t) and receive 134(ifc_rxq_t) queue 135.It Va ifc_if_flags 136.Pq Vt "uint32_t" 137Flags describing the operational parameter of the interface 138.It Va ifc_in_detach 139.Pq Vt "int" 140.It Va ifc_link_state 141.Pq Vt "int" 142Describes the current link state of the Ethernet interface. 143Its possible values are either active or inactive. 144.It Va ifc_link_irq 145.Pq Vt "int" 146.It Va ifc_vlan_attach_event 147.Pq Vt "eventhandler_tag" 148.It Va ifc_vlan_detach_event 149.Pq Vt "eventhandler_tag" 150.It Va ifc_pause_frames 151.Pq Vt "int" 152.It Va ifc_watchdog_events 153.Pq Vt "int" 154.It Va ifc_mac 155.Pq Vt "uint8_t" 156.It Va ifc_msix_mem 157.Pq Vt "struct resource *" 158.It Va ifc_legacy_irq 159.Pq Vt "struct if_irq" 160.It Va ifc_admin_task 161.Pq Vt "struct grouptask" 162Taskqueue task scheduled for link state change events of the interface 163.It Va ifc_filter_info 164.Pq Vt "struct iflib_filter_info" 165Statistics and information relating to the interface device filter 166.It Va ifc_media 167.Pq Vt "struct ifmedia" 168.It Va ifc_txrx 169.Pq Vt "struct if_txrx" 170.El 171.Sh FUNCTIONS 172The above named functions are found exclusively in iflib. 173They are independent of the underlying hardware type or configuration. 174.Ss Device Independent Functions 175.Bl -ohang -offset indent 176.It Fn iflib_device_attach 177Function initiates a device registration with the iflib framework. 178It calls the iflib_register function, which is responsible for allocating 179and initializing the \fIif_ctx_t\fP structure. 180.It Fn iflib_device_detach 181Shutdown and detach the device. 182Unregister vlan events, drain any dependent tasks, and release irq, pci, and 183msix memory. 184.It Fn iflib_device_suspend 185Suspend a device by calling the device dependent suspend function and 186bus_generic_suspend. 187.It Fn iflib_device_resume 188Resume a device by calling the device dependent resume function, the 189iflib_init_locked function, and bus_generic_resume. 190.It Fn iflib_device_register 191Register a device with the iflib framework. 192Allocate and initialize the 193\fIif_ctx_t\fP structure. 194Setup and initialize the MSI or MSI/X interrupt queues if necessary. 195Allocate memory for queues and qset structure setup. 196.It Fn iflib_irq_alloc 197Allocate an interrupt resource for a given rid value with an associated filter 198and handler function. 199.It Fn iflib_irq_alloc_generic 200Performs the same function as iflib_device_irq_alloc along with the additional 201functionality of adding a taskgroup. 202The data fields and callback function are determined by the type of interrupt, 203such as 204.Dv IFLIB_INTR_TX , 205.Dv IFLIB_INTR_RX , 206and 207.Dv IFLIB_INTR_ADMIN . 208.It Fn iflib_led_create 209Calls led_create to initialize the ctx->ifc_led_dev field 210.It Fn iflib_tx_intr_deferred 211Calls GROUPTASK_ENQUEUE to enqueue the transfer queues ift_task. 212.It Fn iflib_rx_intr_deferred 213Calls GROUPTASK_ENQUEUE to enqueue the receive queues ifr_task. 214.It Fn iflib_link_intr_deferred 215Calls GROUPTASK_ENQUEUE to enqueue the link task 216.It Fn iflib_link_state_change 217Change the interface link status to either 218.Dv LINK_STATE_UP 219or 220.Dv LINK_STATE_DOWN 221as specified by the second argument to the function. 222.Pp 223.Em Interface Link States 224The following link states are currently defined: 225.It Dv LINK_STATE_UP 226The link is up. 227.It Dv LINK_STATE_DOWN 228The link is down. 229.It Fn iflib_add_int_delay_sysctl 230Modifies settings to user defined values for a given set of variables. 231.El 232.Sh SEE ALSO 233.Xr iflibdd 9 , 234.Xr iflibtxrx 9 235.Sh AUTHORS 236This manual page was written by 237.An Nicole Graziano 238