share/man/man9/iflibdi.9

   1 .\" $FreeBSD$
   2 .Dd January 27, 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 .Fn iflib_device_attach "device_t dev"
  13 .Ft int
  14 .Fn iflib_device_detach "device_t dev"
  15 .Ft int
  16 .Fn iflib_device_suspend "device_t dev"
  17 .Ft int
  18 .Fn iflib_device_resume "device_t dev"
  19 .Ft int
  20 .Fn iflib_device_register "device_t dev, void *softc, if_shared_ctx_t sctx, if_ctx_t *ctxp"
  21 .Ft int
  22 .Fn iflib_device_deregister "if_ctx_t ctx"
  23 .Ft int
  24 .Fn iflib_irq_alloc "if_ctx_t ctx, if_irq_t irq_info, int rid, driver_filter_t filter, void *filter_arg, driver_intr_t handler, void *arg, char *name"
  25 .Ft int
  26 .Fn iflib_irq_alloc_generic "if_ctx_t, ctx, if_irq_t irq, int rid, intr_type_t type, driver_filter_t *filter, void *filter_arg, int qid, char *name"
  27 .Ft void
  28 .Fn iflib_led_create "if_ctx_t ctx"
  29 .Ft void
  30 .Fn iflib_tx_intr_deferred "if_ctx_t ctx, int txqid"
  31 .Ft void
  32 .Fn iflib_rx_intr_deferred "if_ctx_t ctx, int rxqid"
  33 .Ft void
  34 .Fn iflib_link_intr_deferred "if_ctx_t ctx"
  35 .Ft void
  36 .Fn iflib_link_state_change "if_ctx_t ctx, int linkstate"
  37 .Ft void
  38 .Fn iflib_led_create "if_ctx_t ctx"
  39 .Ft void
  40 .Fn iflib_add_int_delay_sysctl "if_ctx_t ctx, const char *, const char *, if_int_delay_info_t, int, int"
  41 .Ss "Global Variables"
  42 .Vt extern struct if_txrx
  43 .Sh DATA STRUCTURES
  44 The \fIif_ctx_t\fP Structure is the device independent data structure that contains statistics and identifying information used to transmit and receive data packets. The interface is associated with an array of queues assigned sequentially. Each queu has its own transmit (iflib_txq_t) and receive (iflib_rxq_t) queue. The transmit queue is used to hold packets while the interface is in the process of sending another. The receive queue is used to receive packets that are awaiting processing.
  45 .Pp
  46 .Ss The if_ctx_t Structure
  47 The fields of
  48 .Vt "struct if_ctx_t"
  49 are as follows:
  50 .Bl -tag -width ".Va if_capabilities" -offset indent
  51 .It Va if_softc
  52 .Pq Vt "void"
  53 A pointer to the driver's private state block.
  54 .It Va ifc_dev
  55 .Pq Vt "device_t"
  56 The underlying device structure.
  57 .It Va ifc_ip
  58 .Pq Vt "if_t"
  59 A link back to the interface structure
  60 .It Va ifc_cpus
  61 .Pq Vt "cpuset_t"
  62 .It Va ifc_mutex
  63 .Pq Vt "struct mtx"
  64 Mutex lock used to maintain data integrity
  65 .It Va ifc_mtx_name
  66 .Pq Vt "char *"
  67 The name of the mutex
  68 .It Va ifc_txqs
  69 .Pq Vt "iflib_txq_t"
  70 Device independent transmit queue maintained internally by iflib
  71 .It Va ifc_rxqs
  72 .Pq Vt "iflib_rxq_t"
  73 Device independent receive queue maintained internally by iflib
  74 .It Va ifc_qsets
  75 .Pq Vt "iflib_qset_t"
  76  Output queue that contains a single transmit (ifc_txq_t) and receive (ifc_rxq_t) queue
  77 .It Va ifc_if_flags
  78 .Pq Vt "uint32_t"
  79 Flags describing the operational parameter of the interface
  80 .It Va ifc_in_detach
  81 .Pq Vt "int"
  82 .It Va ifc_link_state
  83 .Pq Vt "int"
  84 Describes the current link state of the Ethernet interface. It's possible values are either active or inactive.
  85 .It Va ifc_link_irq
  86 .Pq Vt "int"
  87 .It Va ifc_vlan_attach_event
  88 .Pq Vt "eventhandler_tag"
  89 .It Va ifc_vlan_detach_event
  90 .Pq Vt "eventhandler_tag"
  91 .It Va ifc_pause_frames
  92 .Pq Vt "int"
  93 .It Va ifc_watchdog_events
  94 .Pq Vt "int"
  95 .It Va ifc_mac
  96 .Pq Vt "uint8_t"
  97 .It Va ifc_msix_mem
  98 .Pq Vt "struct resource *"
  99 .It Va ifc_legacy_irq
 100 .Pq Vt "struct if_irq"
 101 .It Va ifc_admin_task
 102 .Pq Vt "struct grouptask"
 103 Taskqueue task scheduled for link state change events of the interface
 104 .It Va ifc_filter_info
 105 .Pq Vt "struct iflib_filter_info"
 106 Statistics and information relating to the interface device filter
 107 .It Va ifc_media
 108 .Pq Vt "struct ifmedia"
 109 .It Va ifc_txrx
 110 .Pq Vt "struct if_txrx"
 111 .El
 112 .Sh FUNCTIONS
 113  The above named functions are found exclusively in iflib. They are independent of the underlying hardware type or configuration.
 114 .Ss Device Independent Functions
 115 .Bl -ohang -offset indent
 116 .It Fn iflib_device_attach
 117 Function initiates a device registration with the iflib framework. It calls the iflib_register function, which is responsible for allocating and initializing the \fIif_ctx_t\fP structure.
 118 .It Fn iflib_device_detach
 119 Shutdown and detach the device. Unregister vlan events, drain any dependent tasks, and release irq, pci, and msix memory.
 120 .It Fn iflib_device_suspend
 121 Suspend a device by calling the device dependent suspend function and bus_generic_suspend.
 122 .It Fn iflib_device_resume
 123 Resume a device by calling the device dependent resume function, the iflib_init_locked function, and bus_generic_resume.
 124 .It Fn iflib_device_register
 125 Register a device with the iflib framework. Allocate and initialize the \fIif_ctx_t\fP structure. Setup and initialize the MSI or MSI/X interrupt queues if necessary. Allocate memory for queues and qset structure setup.
 126 .It Fn iflib_device_irq_alloc
 127 Allocate an interrupt resource for a given rid value with an associated filter and handler function.
 128 .It Fn iflib_device_irq_alloc_generic
 129 Performs the same function as iflib_device_irq_alloc along with the additional functionality of adding a taskgroup. The data fields and callback function are determined by the type of interrupt, such as IFLIB_INTR_TX, IFLIB_INTR_RX, and IFLIB_INTR_ADMIN.
 130 .It Fn iflib_led_create
 131 Calls led_create to initialize the ctx->ifc_led_dev field
 132 .It Fn iflib_tx_intr_deferred
 133 Calls GROUPTASK_ENQUEUE to enqueue the transfer queues ift_task.
 134 .It Fn iflib_rx_intr_deferred
 135 Calls GROUPTASK_ENQUEUE to enqueue the receive queues ifr_task.
 136 .It Fn iflib_link_intr_deferred
 137 Calls GROUPTASK_ENQUEUE to enqueue the link task
 138 .It Fn iflib_link_state_change
 139 Change the interface link status to either LINK_STATE_UP or LINK_STATE_DOWN as specified by the second argument to the function.
 140 \fBInterface Link States\fP
 141 The following link states are currently defined:
 142
 143        LINK_STATE_UP       The link is up.
 144        LINK_STATE_DOWN     The link is down.
 145 .It Fn iflib_add_int_delay_sysctl
 146 Modifies settings to user defined values for a given set of variables.
 147 .El
 148 .Sh "SEE ALSO"
 149  iflibtxrx(9), iflibdd(9)
 150 .Sh AUTHORS
 151 This manual page was written by
 152 .An Nicole Graziano