share/man/man9/iflibdd.9

   1 .\" $FreeBSD$
   2 .Dd March 23, 2017
   3 .Dt IFLIBDD 9
   4 .Os
   5 .Sh NAME
   6 .Nm iflibdd
   7 .Nd Device Dependent Configuration Functions
   8 .Sh SYNOPSIS
   9 .In "ifdi_if.h"
  10 .Ss "Soft Queue Setup and Teardown Functions"
  11 .Ss "Mandatory Functions"
  12 .Ft int
  13 .Fo ifdi_queues_alloc
  14 .Fa "if_ctx_t ctx"
  15 .Fa "caddr_t *vaddrs"
  16 .Fa "uint64_t *paddrs"
  17 .Fa "int nqs"
  18 .Fc
  19 .Ft int
  20 .Fo ifdi_queues_free
  21 .Fa "if_ctx_t ctx"
  22 .Fc
  23 .Ss "Optional Functions"
  24 .Ft int
  25 .Fo ifdi_txq_setup
  26 .Fa "if_ctx_t ctx"
  27 .Fa "uint16_t qid"
  28 .Fc
  29 .Ft int
  30 .Fo ifdi_rxq_setup
  31 .Fa "if_ctx_t ctx"
  32 .Fa "uint16_t qid"
  33 .Fc
  34 .Ss "Device Setup and Teardown Functions"
  35 .Ss "Mandatory Functions"
  36 .Ft int
  37 .Fo ifdi_attach_pre
  38 .Fa "if_ctx_t ctx"
  39 .Fc
  40 .Ft int
  41 .Fo ifdi_attach_post
  42 .Fa "if_ctx_t ctx"
  43 .Fc
  44 .Ft int
  45 .Fo ifdi_detach
  46 .Fa "if_ctx_t ctx"
  47 .Fc
  48 .Ss "Optional Functions"
  49 .Ft void
  50 .Fo ifdi_vlan_register
  51 .Fa "if_ctx_t ctx"
  52 .Fa "uint16_t vtag"
  53 .Fc
  54 .Ft void
  55 .Fo ifdi_vlan_unregister
  56 .Fa "if_ctx_t ctx"
  57 .Fa "uint16_t vtag"
  58 .Fc
  59 .Ft int
  60 .Fo ifdi_suspend
  61 .Fa "if_ctx_t ctx"
  62 .Fc
  63 .Ft int
  64 .Fo ifdi_resume
  65 .Fa "if_ctx_t ctx"
  66 .Fc
  67 .Ss "Device Configuration Functions"
  68 .Ss "Mandatory Functions"
  69 .Ft void
  70 .Fo ifdi_init
  71 .Fa "if_ctx_t ctx"
  72 .Fc
  73 .Ft void
  74 .Fo ifdi_stop
  75 .Fa "if_ctx_t ctx"
  76 .Fc
  77 .Ft void
  78 .Fo ifdi_multi_set
  79 .Fa "if_ctx_t ctx"
  80 .Fc
  81 .Ft int
  82 .Fo ifdi_mtu_set
  83 .Fa "if_ctx_t ctx"
  84 .Fa "uint32_t mtu"
  85 .Fc
  86 .Ft void
  87 .Fo ifdi_media_status
  88 .Fa "if_ctx_t ctx"
  89 .Fa "struct ifmediareq *ifr"
  90 .Fc
  91 .Ft int
  92 .Fo ifdi_media_change
  93 .Fa "if_ctx_t ctx"
  94 .Fc
  95 .Ft void
  96 .Fo ifdi_promisc_set
  97 .Fa "if_ctx_t ctx"
  98 .Fa "int flags"
  99 .Fc
 100 .Ft uint64_t
 101 .Fo ifdi_get_counter
 102 .Fa "if_ctx_t ctx"
 103 .Fa "ift_counter cnt"
 104 .Fc
 105 .Ft void
 106 .Fo ifdi_update_admin_status
 107 .Fa "if_ctx_t ctx"
 108 .Fc
 109 .Ss "Optional Functions"
 110 .Ft void
 111 .Fo ifdi_media_set
 112 .Fa "if_ctx_t ctx"
 113 .Fc
 114 .Ss "Interrupt enable/disable"
 115 .Ss "Mandatory Functions"
 116 .Ft void
 117 .Fo ifdi_intr_enable
 118 .Fa "if_ctx_t ctx"
 119 .Fc
 120 .Ft void
 121 .Fo ifdi_queue_intr_enable
 122 .Fa "if_ctx_t ctx"
 123 .Fa "uint16_t qid"
 124 .Fc
 125 .Ft void
 126 .Fo ifdi_intr_disable
 127 .Fa "if_ctx_t ctx"
 128 .Fc
 129 .Ss IOV Support
 130 .Ft init
 131 .Fo iov_init
 132 .Fa "if_ctx_t ctx"
 133 .Fa "uint16_t num_vfs"
 134 .Fa "const nvlist_t *params"
 135 .Fc
 136 .Ft void
 137 .Fo iov_uinit
 138 .Fa "if_ctx_t ctx"
 139 .Fc
 140 .Ft void
 141 .Fo ifdi_vflr_handle
 142 .Fa "if_ctx_t ctx"
 143 .Fc
 144 .Ft int
 145 .Fo ifdi_vf_add
 146 .Fa "if_ctx_t ctx"
 147 .Fa "uint16_t vfnum"
 148 .Fa "const nvlist_t *params"
 149 .Fc
 150 .Ss "Optional Functions"
 151 .Ft void
 152 .Fo ifdi_link_intr_enable
 153 .Fa "if_ctx_t ctx"
 154 .Fc
 155 .Ss "Optional Service Routines"
 156 .Ft void
 157 .Fo ifdi_timer
 158 .Fa "if_ctx_t ctx"
 159 .Fc
 160 .Ft void
 161 .Fo ifdi_watchdog_reset
 162 .Fa "if_ctx_t ctx"
 163 .Fc
 164 .Ss "Additional Functions"
 165 .Ft void
 166 .Fo ifdi_led_func
 167 .Fa "if_ctx_t ctx"
 168 .Fa "int onoff"
 169 .Fc
 170 .Ft int
 171 .Fo ifdi_sysctl_int_delay
 172 .Fa "if_ctx_t ctx"
 173 .Fa "if_int_delay_info_t iidi"
 174 .Fc
 175 .Ft int
 176 .Fo ifdi_i2c_req
 177 .Fa "if_ctx_t ctx"
 178 .Fa "struct ifi2creq *req"
 179 .Fc
 180 .Sh FUNCTIONS
 181 The above named functions are device dependent configuration functions.
 182 These routines are registered with iflib by the driver and are called from the
 183 corresponding iflib function to configure device specific functions and
 184 registers.
 185 .Ss Device Dependent Functions
 186 .Ss Soft Queue Setup and Teardown
 187 .Bl -ohang -offset indent
 188 .It Fn ifdi_queues_alloc
 189 Mandatory queues allocation function that is called during iflib_attach.
 190 vaddrs and paddrs are arrays of virtual and physical addresses respectively of
 191 the hardware transmit and receive queues, and if relevany, any command
 192 completion queues.
 193 nqs is the number of queues per qset.
 194 For example, a driver with a single receive and transmit queue would have a nqs
 195 equal to 2.
 196 .It Fn ifdi_queues_free
 197 Mandatory function that frees the allocated queues and associated transmit
 198 buffers.
 199 .It Fn ifdi_txq_setup
 200 Optional function for each transmit queue that handles device specific
 201 initialization.
 202 .It Fn ifdi_rxq_setup
 203 Optional function for each receive queue that handles device specific
 204 initialization.
 205 .El
 206 .Ss Device Setup and Teardown
 207 .Bl -ohang -offset indent
 208 .It Fn ifdi_attach_pre
 209 Mandatory function implemented by the driver to perform any attach logic that
 210 procedes interrupt and queue allocation, queue setup, and interrupt assignment.
 211 .It Fn ifdi_attach_post
 212 Mandatory function implemented by the driver to perform any attach logic that
 213 occurs after ifdi_attach_pre, and iflib's queue setup and MSI/MSIX(X) or legacy
 214 interrupt assignment.
 215 .It Fn ifdi_detach
 216 Mandatory function that frees any resources allocated by the driver in
 217 ifdi_attach_pre and ifdi_attach_post.
 218 .It Fn ifdi_vlan_register
 219 Optional function called by the VLAN config eventhandler.
 220 .Va vtag
 221 is the new VLAN tag.
 222 .It Fn ifdi_vlan_unregister
 223 Optional function called by the VLAN unconfig eventhandler.
 224 .It Fn ifdi_suspend
 225 Optional function that suspends the driver.
 226 .It Fn ifdi_resume
 227 Optional function that resumes a driver.
 228 .El
 229 .Ss Device Configuration Functions
 230 .Bl -ohang -offset indent
 231 .It Fn ifdi_init
 232 Mandatory function that will initialize and bring up the hardware.
 233 For example, it will reset the chip and enable the receiver unit.
 234 It should mark the interface running, but not active (
 235 .Dv IFF_DRV_RUNNING ,
 236 .Dv ~IIF_DRV_OACTIVE ).
 237 .It Fn ifdi_stop
 238 Mandatory function that should disable all traffic on the interface by issuing
 239 a global reset on the MAC and deallocating the TX and RX buffers.
 240 .It Fn ifdi_multi_set
 241 Programs the interfaces multicast addresses
 242 .It Fn ifdi_media_status
 243 Media Ioctl Callback.
 244 Function is called whenever the user queries the status of the interface using
 245 .Xr ifconfig 8 .
 246 The driver sets the appropriate link type and speed in ifmr->ifm_active.
 247 .It Fn ifdi_mtu_set
 248 Sets the mtu interface to the value of the second function parameter mtu.
 249 .It Fn ifdi_media_change
 250 Function is called when the user changes speed/duplex using the media/mediaopt
 251 option with
 252 .Xr ifconfig 8 .
 253 .It Fn ifdi_promisc_set
 254 Enables or disables promisc settings depending upon the flags value.
 255 .Va flags
 256 contains the interface's
 257 .Xr ifnet 9
 258 flags.
 259 .It Fn ifdi_get_counter
 260 Returns the value for counter cnt depending upon counter type.
 261 .It Fn ifdi_update_admin_status
 262 Sets the link_up state to TRUE or FALSE depending upon the OS link state.
 263 A real check of the hardware only happens with a link interrupt.
 264 .It Fn ifdi_media_set
 265 Need to define
 266 .El
 267 .Ss Interrupt Enable/Disable
 268 .Bl -ohang -offset indent
 269 .It Fn ifdi_intr_enable
 270 Mandatory function that enables all interrupts.
 271 .It Fn ifdi_intr_disable
 272 Mandatory function that disables all interrupts.
 273 .It Fn ifdi_queue_intr_enable
 274 Mandatory function that enables interrupts on queue qid.
 275 .It Fn iov_init
 276 Initialize num_vfs VFs.
 277 .It Fn io_uninit
 278 Tear down the context for all VFs.
 279 .It Fn ifdi_vflr_handle
 280 Handle any VFs that have reset themselves via a Function Level Reset (FLR).
 281 .It Fn ifdi_vf_add
 282 Set parameters in params in VF vfnum.
 283 .El
 284 .Ss Service Routines
 285 .Bl -ohang -offset indent
 286 .It Fn ifdi_timer
 287 Optional timer routine that will be run every 500ms.
 288 .It Fn ifdi_watchdog_reset
 289 Optional function to run when a transmit queue is hung.
 290 .El
 291 .Ss Additional Functions
 292 .Bl -ohang -offset indent
 293 .It Fn ifdi_led_func
 294 .It Fn ifdi_sysctl_int_delay
 295 .It Fn ifdi_i2c_req
 296 .El
 297 .Sh SEE ALSO
 298 .Xr ifconfig 8 ,
 299 .Xr iflibdi 9 ,
 300 .Xr iflibtxrx 9 ,
 301 .Xr ifnet 9
 302 .Sh AUTHORS
 303 This manual page was written by
 304 .An Nicole Graziano