share/man/man9/iflibdd.9

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