share/man/man9/iflibdi.9

   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
  95 The \fIif_ctx_t\fP Structure is the device independent data structure that
  96 contains statistics and identifying information used to transmit and receive
  97 data packets.
  98 The interface is associated with an array of queues assigned sequentially.
  99 Each queue has its own transmit (iflib_txq_t) and receive (iflib_rxq_t) queue.
 100 The transmit queue is used to hold packets while the interface is in the
 101 process of sending another.
 102 The receive queue is used to receive packets that are awaiting processing.
 103 .Pp
 104 .Ss The if_ctx_t Structure
 105 The fields of
 106 .Vt "struct if_ctx_t"
 107 are as follows:
 108 .Bl -tag -width ".Va if_capabilities" -offset indent
 109 .It Va if_softc
 110 .Pq Vt "void"
 111 A pointer to the driver's private state block.
 112 .It Va ifc_dev
 113 .Pq Vt "device_t"
 114 The underlying device structure.
 115 .It Va ifc_ip
 116 .Pq Vt "if_t"
 117 A link back to the interface structure
 118 .It Va ifc_cpus
 119 .Pq Vt "cpuset_t"
 120 .It Va ifc_mutex
 121 .Pq Vt "struct mtx"
 122 Mutex lock used to maintain data integrity
 123 .It Va ifc_mtx_name
 124 .Pq Vt "char *"
 125 The name of the mutex
 126 .It Va ifc_txqs
 127 .Pq Vt "iflib_txq_t"
 128 Device independent transmit queue maintained internally by iflib
 129 .It Va ifc_rxqs
 130 .Pq Vt "iflib_rxq_t"
 131 Device independent receive queue maintained internally by iflib
 132 .It Va ifc_qsets
 133 .Pq Vt "iflib_qset_t"
 134 Output queue that contains a single transmit (ifc_txq_t) and receive
 135 (ifc_rxq_t) queue
 136 .It Va ifc_if_flags
 137 .Pq Vt "uint32_t"
 138 Flags describing the operational parameter of the interface
 139 .It Va ifc_in_detach
 140 .Pq Vt "int"
 141 .It Va ifc_link_state
 142 .Pq Vt "int"
 143 Describes the current link state of the Ethernet interface.
 144 Its possible values are either active or inactive.
 145 .It Va ifc_link_irq
 146 .Pq Vt "int"
 147 .It Va ifc_vlan_attach_event
 148 .Pq Vt "eventhandler_tag"
 149 .It Va ifc_vlan_detach_event
 150 .Pq Vt "eventhandler_tag"
 151 .It Va ifc_pause_frames
 152 .Pq Vt "int"
 153 .It Va ifc_watchdog_events
 154 .Pq Vt "int"
 155 .It Va ifc_mac
 156 .Pq Vt "uint8_t"
 157 .It Va ifc_msix_mem
 158 .Pq Vt "struct resource *"
 159 .It Va ifc_legacy_irq
 160 .Pq Vt "struct if_irq"
 161 .It Va ifc_admin_task
 162 .Pq Vt "struct grouptask"
 163 Taskqueue task scheduled for link state change events of the interface
 164 .It Va ifc_filter_info
 165 .Pq Vt "struct iflib_filter_info"
 166 Statistics and information relating to the interface device filter
 167 .It Va ifc_media
 168 .Pq Vt "struct ifmedia"
 169 .It Va ifc_txrx
 170 .Pq Vt "struct if_txrx"
 171 .El
 172 .Sh FUNCTIONS
 173 The above named functions are found exclusively in iflib.
 174 They are independent of the underlying hardware type or configuration.
 175 .Ss Device Independent Functions
 176 .Bl -ohang -offset indent
 177 .It Fn iflib_device_attach
 178 Function initiates a device registration with the iflib framework.
 179 It calls the iflib_register function, which is responsible for allocating
 180 and initializing the \fIif_ctx_t\fP structure.
 181 .It Fn iflib_device_detach
 182 Shutdown and detach the device.
 183 Unregister vlan events, drain any dependent tasks, and release irq, pci, and
 184 msix memory.
 185 .It Fn iflib_device_suspend
 186 Suspend a device by calling the device dependent suspend function and
 187 bus_generic_suspend.
 188 .It Fn iflib_device_resume
 189 Resume a device by calling the device dependent resume function, the
 190 iflib_init_locked function, and bus_generic_resume.
 191 .It Fn iflib_device_register
 192 Register a device with the iflib framework.
 193 Allocate and initialize the
 194 \fIif_ctx_t\fP structure.
 195 Setup and initialize the MSI or MSI/X interrupt queues if necessary.
 196 Allocate memory for queues and qset structure setup.
 197 .It Fn iflib_irq_alloc
 198 Allocate an interrupt resource for a given rid value with an associated filter
 199 and handler function.
 200 .It Fn iflib_irq_alloc_generic
 201 Performs the same function as iflib_device_irq_alloc along with the additional
 202 functionality of adding a taskgroup.
 203 The data fields and callback function are determined by the type of interrupt,
 204 such as
 205 .Dv IFLIB_INTR_TX ,
 206 .Dv IFLIB_INTR_RX ,
 207 and
 208 .Dv IFLIB_INTR_ADMIN .
 209 .It Fn iflib_led_create
 210 Calls led_create to initialize the ctx->ifc_led_dev field
 211 .It Fn iflib_tx_intr_deferred
 212 Calls GROUPTASK_ENQUEUE to enqueue the transfer queues ift_task.
 213 .It Fn iflib_rx_intr_deferred
 214 Calls GROUPTASK_ENQUEUE to enqueue the receive queues ifr_task.
 215 .It Fn iflib_link_intr_deferred
 216 Calls GROUPTASK_ENQUEUE to enqueue the link task
 217 .It Fn iflib_link_state_change
 218 Change the interface link status to either
 219 .Dv LINK_STATE_UP
 220 or
 221 .Dv LINK_STATE_DOWN
 222 as specified by the second argument to the function.
 223 .Pp
 224 .Em Interface Link States
 225 The following link states are currently defined:
 226 .It Dv LINK_STATE_UP
 227 The link is up.
 228 .It Dv LINK_STATE_DOWN
 229 The link is down.
 230 .It Fn iflib_add_int_delay_sysctl
 231 Modifies settings to user defined values for a given set of variables.
 232 .El
 233 .Sh SEE ALSO
 234 .Xr iflibdd 9 ,
 235 .Xr iflibtxrx 9
 236 .Sh AUTHORS
 237 This manual page was written by
 238 .An Nicole Graziano