1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc.
   3 .\" All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH GLD 9F "February 15, 2020"
   8 .SH NAME
   9 gld, gld_mac_alloc, gld_mac_free, gld_register, gld_unregister, gld_recv,
  10 gld_sched, gld_intr \- Generic LAN Driver service routines
  11 .SH SYNOPSIS
  12 .nf
  13 #include <sys/gld.h>
  14 
  15 \fBgld_mac_info_t *\fR\fBgld_mac_alloc\fR(\fBdev_info_t *\fR\fIdip\fR);
  16 .fi
  17 
  18 .LP
  19 .nf
  20 \fBvoid\fR \fBgld_mac_free\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR);
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBint\fR \fBgld_register\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, \fBgld_mac_info_t *\fR\fImacinfo\fR);
  26 .fi
  27 
  28 .LP
  29 .nf
  30 \fBint\fR \fBgld_unregister\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR);
  31 .fi
  32 
  33 .LP
  34 .nf
  35 \fBvoid\fR \fBgld_recv\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, \fBmblk_t *\fR\fImp\fR);
  36 .fi
  37 
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBgld_sched\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR);
  41 .fi
  42 
  43 .LP
  44 .nf
  45 \fBuint_t\fR \fBgld_intr\fR(\fBcaddr_t);\fR
  46 .fi
  47 
  48 .LP
  49 .nf
  50 \fBvoid\fR \fBgld_linkstate\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, \fBint32_t\fR \fInewstate\fR);
  51 .fi
  52 
  53 .SH INTERFACE LEVEL
  54 Solaris architecture specific (Solaris DDI).
  55 .SH PARAMETERS
  56 .ne 2
  57 .na
  58 \fB\fImacinfo\fR \fR
  59 .ad
  60 .RS 13n
  61 Pointer to a \fBgld_mac_info\fR(9S) structure.
  62 .RE
  63 
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIdip\fR \fR
  68 .ad
  69 .RS 13n
  70 Pointer to \fBdev_info\fR structure.
  71 .RE
  72 
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIname\fR \fR
  77 .ad
  78 .RS 13n
  79 Device interface name.
  80 .RE
  81 
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fImp\fR \fR
  86 .ad
  87 .RS 13n
  88 Pointer to a message block containing a received packet.
  89 .RE
  90 
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fInewstate\fR \fR
  95 .ad
  96 .RS 13n
  97 Media link state.
  98 .RE
  99 
 100 .SH DESCRIPTION
 101 \fBgld_mac_alloc\fR(\|) allocates a new \fBgld_mac_info\fR(9S) structure and
 102 returns a pointer to it. Some of the GLD-private elements of the structure may
 103 be initialized before \fBgld_mac_alloc\fR(\|) returns; all other elements are
 104 initialized to zero. The device driver must initialize some structure members,
 105 as described in \fBgld_mac_info\fR(9S), before passing the mac_info pointer to
 106 \fBgld_register\fR(\|).
 107 .sp
 108 .LP
 109 \fBgld_mac_free\fR(\|) frees a \fBgld_mac_info\fR(9S) structure previously
 110 allocated by \fBgld_mac_alloc\fR(\|).
 111 .sp
 112 .LP
 113 \fBgld_register\fR(\|) is called from the device driver's \fBattach\fR(9E)
 114 routine, and is used to link the GLD-based device driver with the GLD
 115 framework. Before calling \fBgld_register\fR(\|) the device driver's
 116 \fBattach\fR(9E) routine must first use \fBgld_mac_alloc\fR(\|) to allocate a
 117 \fBgld_mac_info\fR(9S) structure, and initialize several of its structure
 118 elements. See \fBgld_mac_info\fR(9S) for more information. A successful call to
 119 \fBgld_register\fR(\|) performs the following actions:
 120 .RS +4
 121 .TP
 122 .ie t \(bu
 123 .el o
 124 links the device-specific driver with the GLD system;
 125 .RE
 126 .RS +4
 127 .TP
 128 .ie t \(bu
 129 .el o
 130 sets the device-specific driver's private data pointer (using
 131 \fBddi_set_driver_private\fR(9F)) to point to the \fBmacinfo\fR structure;
 132 .RE
 133 .RS +4
 134 .TP
 135 .ie t \(bu
 136 .el o
 137 creates the minor device node.
 138 .RE
 139 .sp
 140 .LP
 141 The device interface name passed to \fBgld_register\fR(\|) must exactly match
 142 the name of the driver module as it exists in the filesystem.
 143 .sp
 144 .LP
 145 The driver's \fBattach\fR(9E) routine should return \fBDDI_SUCCESS\fR if
 146 \fBgld_register\fR(\|) succeeds. If \fBgld_register\fR(\|) returns
 147 \fBDDI_FAILURE\fR, the \fBattach\fR(9E) routine should deallocate any resources
 148 it allocated before calling \fBgld_register\fR(\|) and then also return
 149 \fBDDI_FAILURE\fR.
 150 .sp
 151 .LP
 152 \fBgld_unregister\fR(\|) is called by the device driver's \fBdetach\fR(9E)
 153 function, and if successful, performs the following tasks:
 154 .RS +4
 155 .TP
 156 .ie t \(bu
 157 .el o
 158 ensures the device's interrupts are stopped, calling the driver's
 159 \fBgldm_stop\fR(\|) routine if necessary;
 160 .RE
 161 .RS +4
 162 .TP
 163 .ie t \(bu
 164 .el o
 165 removes the minor device node;
 166 .RE
 167 .RS +4
 168 .TP
 169 .ie t \(bu
 170 .el o
 171 unlinks the device-specific driver from the GLD system.
 172 .RE
 173 .sp
 174 .LP
 175 If \fBgld_unregister\fR(\|) returns \fBDDI_SUCCESS\fR, the \fBdetach\fR(9E)
 176 routine should deallocate any data structures allocated in the \fBattach\fR(9E)
 177 routine, using \fBgld_mac_free\fR(\|) to deallocate the \fBmacinfo\fR
 178 structure, and return \fBDDI_SUCCESS\fR. If \fBgld_unregister\fR(\|) returns
 179 \fBDDI_FAILURE\fR, the driver's \fBdetach\fR(9E) routine must leave the device
 180 operational and return \fBDDI_FAILURE\fR.
 181 .sp
 182 .LP
 183 \fBgld_recv\fR(\|) is called by the driver's interrupt handler to pass a
 184 received packet upstream. The driver must construct and pass a STREAMS
 185 \fBM_DATA\fR message containing the raw packet. \fBgld_recv\fR(\|) determines
 186 which STREAMS queues, if any, should receive a copy of the packet, duplicating
 187 it if necessary. It then formats a \fBDL_UNITDATA_IND\fR message, if required,
 188 and passes the data up all appropriate streams.
 189 .sp
 190 .LP
 191 The driver should avoid holding mutex or other locks during the call to
 192 \fBgld_recv\fR(\|). In particular, locks that could be taken by a transmit
 193 thread may not be held during a call to \fBgld_recv\fR(\|): the interrupt
 194 thread that calls \fBgld_recv\fR(\|) may in some cases carry out processing
 195 that includes sending an outgoing packet, resulting in a call to the driver's
 196 \fBgldm_send\fR(\|) routine. If the \fBgldm_send\fR(\|) routine were to try to
 197 acquire a mutex being held by the \fBgldm_intr\fR(\|) routine at the time it
 198 calls \fBgld_recv\fR(\|), this could result in a panic due to recursive mutex
 199 entry.
 200 .sp
 201 .LP
 202 \fBgld_sched\fR(\|) is called by the device driver to reschedule stalled
 203 outbound packets. Whenever the driver's \fBgldm_send\fR(\|) routine has
 204 returned \fBGLD_NORESOURCES\fR, the driver must later call \fBgld_sched\fR(\|)
 205 to inform the GLD framework that it should retry the packets that previously
 206 could not be sent. \fBgld_sched\fR(\|) should be called as soon as possible
 207 after resources are again available, to ensure that GLD resumes passing
 208 outbound packets to the driver's \fBgldm_send\fR(\|) routine in a timely way.
 209 (If the driver's \fBgldm_stop\fR(\|) routine is called, the driver is absolved
 210 from this obligation until it later again returns \fBGLD_NORESOURCES\fR from
 211 its \fBgldm_send\fR(\|) routine; however, extra calls to \fBgld_sched\fR(\|)
 212 will not cause incorrect operation.)
 213 .sp
 214 .LP
 215 \fBgld_intr\fR(\|) is GLD's main interrupt handler. Normally it is specified as
 216 the interrupt routine in the device driver's call to \fBddi_add_intr\fR(9F).
 217 The argument to the interrupt handler (specified as \fIint_handler_arg\fR in
 218 the call to \fBddi_add_intr\fR(9F)) must be a pointer to the
 219 \fBgld_mac_info\fR(9S) structure. \fBgld_intr\fR(\|) will, when appropriate,
 220 call the device driver's \fBgldm_intr\fR(\|) function, passing that pointer to
 221 the \fBgld_mac_info\fR(9S) structure. However, if the driver uses a high-level
 222 interrupt, it must provide its own high-level interrupt handler, and trigger a
 223 soft interrupt from within that. In this case, \fBgld_intr\fR(\|) may be
 224 specified as the soft interrupt handler in the call to
 225 \fBddi_add_softintr\fR(\|).
 226 .sp
 227 .LP
 228 \fBgld_linkstate()\fR is called by the device driver to notify GLD of changes
 229 in the media link state. The newstate argument should be set to one of the
 230 following:
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBGLD_LINKSTATE_DOWN\fR \fR
 235 .ad
 236 .RS 26n
 237 The media link is unavailable.
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBGLD_LINKSTATE_UP\fR \fR
 244 .ad
 245 .RS 26n
 246 The media link is unavailable.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBGLD_LINKSTATE_UNKNOWN\fR \fR
 253 .ad
 254 .RS 26n
 255 The status of the media link is unknown.
 256 .RE
 257 
 258 .sp
 259 .LP
 260 If a driver calls \fBgld_linkstate()\fR, it must also set the GLD_CAP_LINKSTATE
 261 bit in the gldm_capabilities field of the \fBgld_mac_info\fR(9S) structure.
 262 .SH RETURN VALUES
 263 \fBgld_mac_alloc\fR(\|) returns a pointer to a new \fBgld_mac_info\fR(9S)
 264 structure.
 265 .sp
 266 .LP
 267 \fBgld_register\fR(\|) and \fBgld_unregister\fR(\|) return:
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fBDDI_SUCCESS\fR \fR
 272 .ad
 273 .RS 16n
 274 on success.
 275 .RE
 276 
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fBDDI_FAILURE\fR \fR
 281 .ad
 282 .RS 16n
 283 on failure.
 284 .RE
 285 
 286 .sp
 287 .LP
 288 \fBgld_intr\fR(\|) returns a value appropriate for an interrupt handler.
 289 .SH SEE ALSO
 290 \fBgld\fR(7D), \fBgld\fR(9E), \fBgld_mac_info\fR(9S), \fBgld_stats\fR(9S),
 291 \fBdlpi\fR(7P), \fBattach\fR(9E), \fBddi_add_intr\fR(9F)
 292 .sp
 293 .LP
 294 \fIWriting Device Drivers\fR