| blob | 073f27f3d69a9898add10e69b6fe2f659d1fa52a |
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>
16 \fBgld_mac_info_t *\fR\fBgld_mac_alloc\fR(\fBdev_info_t *\fR\fIdip\fR);
17 .fi
19 .LP
20 .nf
21 \fBvoid\fR \fBgld_mac_free\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR);
22 .fi
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
29 .LP
30 .nf
31 \fBint\fR \fBgld_unregister\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR);
32 .fi
34 .LP
35 .nf
36 \fBvoid\fR \fBgld_recv\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, \fBmblk_t *\fR\fImp\fR);
37 .fi
39 .LP
40 .nf
41 \fBvoid\fR \fBgld_sched\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR);
42 .fi
44 .LP
45 .nf
46 \fBuint_t\fR \fBgld_intr\fR(\fBcaddr_t);\fR
47 .fi
49 .LP
50 .nf
51 \fBvoid\fR \fBgld_linkstate\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, \fBint32_t\fR \fInewstate\fR);
52 .fi
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
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
77 .sp
78 .ne 2
79 .na
80 \fB\fIname\fR \fR
81 .ad
82 .RS 13n
83 Device interface name.
84 .RE
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
95 .sp
96 .ne 2
97 .na
98 \fB\fInewstate\fR \fR
99 .ad
100 .RS 13n
101 Media link state.
102 .RE
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
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
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
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
285 .sp
286 .ne 2
287 .na
288 \fB\fBDDI_FAILURE\fR \fR
289 .ad
290 .RS 16n
291 on failure.
292 .RE
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