share/man/man9/iflibdi.9

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