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