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