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