| blob | dd0e016540c06e418ae9670673f715f2da7cf1f9 |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH GLD 7D "Nov 10, 2005"
7 .SH NAME
8 gld \- Generic \fBLAN\fR Driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include\fR \fB<sys/stropts.h>\fR
13 .fi
15 .LP
16 .nf
17 \fB#include\fR \fB<sys/stream.h>\fR
18 .fi
20 .LP
21 .nf
22 \fB#include\fR \fB<sys/dlpi.h>\fR
23 .fi
25 .LP
26 .nf
27 \fB#include\fR \fB<sys/gld.h>\fR
28 .fi
30 .SH INTERFACE LEVEL
31 .sp
32 .LP
33 Solaris architecture specific (Solaris DDI).
34 .SH DESCRIPTION
35 .sp
36 .LP
37 GLD is a multi-threaded, clonable, loadable kernel module providing support for
38 Solaris local area network (\fBLAN\fR) device drivers. \fBLAN\fR drivers in
39 Solaris are \fBSTREAMS\fR-based drivers that use the Data Link Provider
40 Interface (\fBDLPI\fR) to communicate with network protocol stacks. These
41 protocol stacks use the network drivers to send and receive packets on a local
42 area network. A network device driver must implement and adhere to the
43 requirements imposed by the DDI/DKI specification, \fBSTREAMS\fR specification,
44 DLPI specification, and programmatic interface of the device itself.
45 .sp
46 .LP
47 GLD implements most \fBSTREAMS\fR and DLPI functionality required of a Solaris
48 LAN driver. Several Solaris network drivers are implemented using GLD.
49 .sp
50 .LP
51 A Solaris network driver implemented using GLD comprises two distinct parts: a
52 generic component that deals with \fBSTREAMS\fR and DLPI interfaces, and a
53 device-specific component that deals with the particular hardware device. The
54 device-specific module indicates its dependency on the GLD module and registers
55 itself with GLD from within the driver's \fBattach\fR(9E) function. Once it is
56 successfully loaded, the driver is \fBDLPI\fR-compliant. The device-specific
57 part of the driver calls \fBgld\fR(9F) functions when it receives data or needs
58 some service from GLD. GLD makes calls into the \fBgld\fR(9E) entry points of
59 the device-specific driver through pointers provided to GLD by the
60 device-specific driver when it registered itself with GLD. The
61 \fBgld_mac_info\fR(9S) structure is the main data interface between GLD and the
62 device-specific driver.
63 .sp
64 .LP
65 The GLD facility currently supports devices of type \fBDL_ETHER\fR,
66 \fBDL_TPR\fR, and \fBDL_FDDI\fR. GLD drivers are expected to process
67 fully-formed MAC-layer packets and should not perform logical link control
68 (LLC) handling.
69 .LP
70 Note -
71 .sp
72 .RS 2
73 Support for the DL_TPR and DL_FDDI media types in GLD is obsolete and may be
74 removed in a future release of Solaris.
75 .RE
76 .sp
77 .LP
78 In some cases, it may be necessary or desirable to implement a full
79 DLPI-compliant driver without using the GLD facility. This is true for devices
80 that are not IEEE 802-style LAN devices, or where a device type or DLPI service
81 not supported by GLD is required.
82 .SS "Device Naming Constraints"
83 .sp
84 .LP
85 The name of the device-specific driver module must adhere to the naming
86 constraints outlined in the NOTES section of \fBdlpi\fR(7P).
87 .SS "Type DL_ETHER: Ethernet V2 and ISO 8802-3 (IEEE 802.3)"
88 .sp
89 .LP
90 For devices designated type \fBDL_ETHER\fR, GLD provides support for both
91 Ethernet V2 and ISO 8802-3 (IEEE 802.3) packet processing. Ethernet V2 enables
92 a data link service user to access and use any of a variety of conforming data
93 link service providers without special knowledge of the provider's protocol. A
94 service access point (\fBSAP\fR) is the point through which the user
95 communicates with the service provider.
96 .sp
97 .LP
98 SAP 0 denotes that the user wishes to use \fI802.3\fR mode. In transmission,
99 GLD checks the destination SAP value of the DL_UNITDATA_REQ and the SAP value
100 to which the stream is bound. If both are 0, the GLD computes the length of
101 the packet payload and transmits \fI802.3\fR frames having that length in the
102 MAC frame header type field. Such lengths will never exceed 1500.
103 .sp
104 .LP
105 All frames received from the media that have a type field in the range [0-1500]
106 are assumed to be \fI802.3\fR frames and are routed up all open streams that
107 are in \fI802.3\fR mode, (those streams bound to a SAP value in of 0. If more
108 than one stream is in \fI802.3\fR mode, the incoming frame is duplicated and
109 routed up each such stream.
110 .sp
111 .LP
112 Streams bound to a SAP value of 1536 or greater receive incoming packets
113 whose Ethernet MAC header type value exactly matches the value of the SAP to
114 which the stream is bound. SAP values in the range [1-1535] are undefined and
115 should not be used.
116 .SS "Types DL_TPR and DL_FDDI: SNAP Processing"
117 .LP
118 Note -
119 .sp
120 .RS 2
121 Support for the DL_TPR and DL_FDDI media types in GLD is obsolete and may be
122 removed in a future release of Solaris.
123 .RE
124 .sp
125 .LP
126 For media types DL_TPR and DL_FDDI, GLD implements minimal SNAP (Sub-Net
127 Access Protocol) processing for SAP values of 1536 or greater. A SAP value of
128 0 denotes that the user wishes to use LLC mode. SAP values in the range
129 [1-1535] have undefined semantics and should not be used.
130 .sp
131 .LP
132 \fBSNAP\fR headers are carried under LLC headers with destination SAP 0xAA. For
133 outgoing packets with SAP values greater than 1535, GLD creates an LLC+SNAP
134 header that always looks like:
135 .sp
136 .LP
137 ``AA AA 03 00 00 00 XX XX''
138 .sp
139 .LP
140 where ``XX XX'' represents the 16-bit SAP, corresponding to the Ethernet V2
141 style ``type.'' This is the only class of SNAP header that is processed -
142 non-zero OUI fields, and LLC control fields other than 03 are considered to be
143 LLC packets with SAP 0xAA.
144 .sp
145 .LP
146 A DL_UNITDATA_REQ message specifying a destination SAP value of 0, passed
147 down a stream bound to SAP 0, is assumed to contain an LLC packet and
148 will not undergo SNAP processing.
149 .sp
150 .LP
151 Incoming packets are examined to ascertain whether they fall into the format
152 specified above. Packets that do will be passed to streams bound to the
153 packet's 16-bit SNAP type, as well as being passed to any stream in LLC mode
154 (those bound to a SAP value of 0).
155 .SS "Type DL_TPR: Source Routing"
156 .LP
157 Note -
158 .sp
159 .RS 2
160 Support for the DL_TPR media type in GLD is obsolete and may be removed in a
161 future release of Solaris.
162 .RE
163 .sp
164 .LP
165 For type \fBDL_TPR\fR devices, GLD implements minimal support for source
166 routing. Source routing enables a station that is sending a packet across a
167 bridged medium to specify (in the packet MAC header) routing information that
168 determines the route that the packet will take through the network.
169 .sp
170 .LP
171 Functionally, the source routing support provided by GLD learns routes,
172 solicits and responds to requests for information about possible multiple
173 routes and selects among the multiple routes that are available. It adds
174 \fIRouting Information Fields\fR to the MAC headers of outgoing packets and
175 recognizes such fields in incoming packets.
176 .sp
177 .LP
178 GLD's source routing support does not implement the full \fIRoute Determination
179 Entity\fR \fB(RDE)\fR specified in \fIISO 8802-2 (IEEE 802.2)\fR Section 9.
180 However, it is designed to interoperate with any such implementations that may
181 exist in the same (or a bridged) network.
182 .SS "Style 1 and 2 Providers"
183 .sp
184 .LP
185 GLD implements both Style 1 and Style 2 providers. A physical point of
186 attachment (\fBPPA\fR) is the point at which a system attaches itself to a
187 physical communication medium. All communication on that physical medium
188 funnels through the \fBPPA\fR. The Style 1 provider attaches the stream to a
189 particular \fBPPA\fR based on the major/minor device that has been opened. The
190 Style 2 provider requires the DLS user to explicitly identify the desired
191 \fBPPA\fR using \fBDL_ATTACH_REQ.\fR In this case, \fBopen\fR(9E) creates a
192 stream between the user and GLD and \fBDL_ATTACH_REQ\fR subsequently associates
193 a particular \fBPPA\fR with that stream. Style 2 is denoted by a minor number
194 of zero. If a device node whose minor number is not zero is opened, Style 1 is
195 indicated and the associated \fBPPA\fR is the minor number minus 1. In both
196 Style 1 and Style 2 opens, the device is cloned.
197 .SS "Implemented DLPI Primitives"
198 .sp
199 .LP
200 GLD implements the following DLPI primitives:
201 .sp
202 .LP
203 The \fBDL_INFO_REQ\fR primitive requests information about the DLPI stream. The
204 message consists of one \fBM_PROTO\fR message block. GLD returns
205 device-dependent values in the \fBDL_INFO_ACK\fR response to this request,
206 based on information the GLD-based driver specified in the
207 \fBgld_mac_info\fR(9S) structure passed to \fBgld_register()\fR. However GLD
208 returns the following values on behalf of all GLD-based drivers:
209 .RS +4
210 .TP
211 .ie t \(bu
212 .el o
213 The version is \fBDL_VERSION_2\fR.
214 .RE
215 .RS +4
216 .TP
217 .ie t \(bu
218 .el o
219 The service mode is \fBDL_CLDLS\fR \(em GLD implements connectionless-mode
220 service.
221 .RE
222 .RS +4
223 .TP
224 .ie t \(bu
225 .el o
226 The provider style is \fBDL_STYLE1\fR or \fBDL_STYLE2,\fR depending on how the
227 stream was opened.
228 .RE
229 .sp
230 .LP
231 The \fBDL_ATTACH_REQ\fR primitive is called to associate a \fBPPA\fR with a
232 stream. This request is needed for Style 2 DLS providers to identify the
233 physical medium over which the communication will transpire. Upon completion,
234 the state changes from \fBDL_UNATTACHED\fR to \fBDL_UNBOUND.\fR The message
235 consists of one \fBM_PROTO\fR message block. This request may not be issued
236 when using the driver in Style 1 mode; streams opened using Style 1 are already
237 attached to a \fBPPA\fR by the time the open completes.
238 .sp
239 .LP
240 The \fBDL_DETACH_REQ\fR primitive requests to detach the \fBPPA\fR from the
241 stream. This is only allowed if the stream was opened using Style 2.
242 .sp
243 .LP
244 The \fBDL_BIND_REQ\fR and \fBDL_UNBIND_REQ\fR primitives bind and unbind a
245 \fBDLSAP\fR to the stream. The \fBPPA\fR associated with each stream will have
246 been initialized upon completion of the processing of the \fBDL_BIND_REQ.\fR
247 Multiple streams may be bound to the same \fBSAP\fR; each such stream receives
248 a copy of any packets received for that SAP.
249 .sp
250 .LP
251 The \fBDL_ENABMULTI_REQ\fR and \fBDL_DISABMULTI_REQ\fR primitives enable and
252 disable reception of individual multicast group addresses. A set of multicast
253 addresses may be iteratively created and modified on a per-stream basis using
254 these primitives. The stream must be attached to a \fBPPA\fR for these
255 primitives to be accepted.
256 .sp
257 .LP
258 The \fBDL_PROMISCON_REQ\fR and \fBDL_PROMISCOFF_REQ\fR primitives enable and
259 disable promiscuous mode on a per-stream basis, either at a physical level or
260 at the \fBSAP\fR level. The DL Provider will route all received messages on the
261 media to the DLS user until either a \fBDL_DETACH_REQ\fR or a
262 \fBDL_PROMISCOFF_REQ\fR is received or the stream is closed. Physical level
263 promiscuous mode may be specified for all packets on the medium or for
264 multicast packets only. The stream must be attached to a \fBPPA\fR for these
265 primitives to be accepted.
266 .sp
267 .LP
268 The \fBDL_UNITDATA_REQ\fR primitive is used to send data in a connectionless
269 transfer. Because this is an unacknowledged service, there is no guarantee of
270 delivery. The message consists of one \fBM_PROTO\fR message block followed by
271 one or more \fBM_DATA\fR blocks containing at least one byte of data.
272 .sp
273 .LP
274 The \fBDL_UNITDATA_IND\fR type is used when a packet is received and is to be
275 passed upstream. The packet is put into an \fBM_PROTO\fR message with the
276 primitive set to \fBDL_UNITDATA_IND\fR.
277 .sp
278 .LP
279 The \fBDL_PHYS_ADDR_REQ\fR primitive returns the MAC address currently
280 associated with the \fBPPA\fR attached to the stream, in the
281 \fBDL_PHYS_ADDR_ACK\fR primitive. When using style 2, this primitive is only
282 valid following a successful \fBDL_ATTACH_REQ\fR.
283 .sp
284 .LP
285 The \fBDL_SET_PHYS_ADDR_REQ\fR primitive changes the MAC address currently
286 associated with the \fBPPA\fR attached to the stream. This primitive affects
287 all other current and future streams attached to this device. Once changed, all
288 streams currently or subsequently opened and attached to this device will
289 obtain this new physical address. The new physical address will remain in
290 effect until this primitive is used to change the physical address again or the
291 driver is reloaded.
292 .sp
293 .LP
294 The \fBDL_GET_STATISTICS_REQ\fR primitive requests a
295 \fBDL_GET_STATISTICS_ACK\fR response containing statistics information
296 associated with the PPA attached to the stream. Style 2 streams must be
297 attached to a particular \fBPPA\fR using \fBDL_ATTACH_REQ\fR before this
298 primitive will be successful.
299 .sp
300 .LP
301 GLD supports the DL_NOTE_LINK_UP, DL_NOTE_LINK_DOWN and DL_NOTE_SPEED
302 notifications using the DL_NOTIFY_IND primitive. See \fBdlpi\fR(7P).
303 .SS "Implemented ioctl Functions"
304 .sp
305 .LP
306 GLD implements the \fBDLIOCRAW\fR ioctl described in \fBdlpi\fR(7P). For any
307 other ioctl command, GLD passes it to the device-specific driver's
308 \fBgldm_ioctl()\fR function as described in \fBgld\fR(9E).
309 .SS "Requirements on GLD Drivers"
310 .sp
311 .LP
312 GLD-based drivers must include the header file \fB<sys/gld.h>\fR\&.
313 .sp
314 .LP
315 GLD-based drivers must also specify a link dependency on "misc/gld". (See
316 the -N option in \fBld\fR(1)).
317 .sp
318 .LP
319 GLD implements the \fBopen\fR(9E) and \fBclose\fR(9E) functions and the
320 required \fBSTREAMS\fR \fBput\fR(9E) and \fBsrv\fR(9E) functions on behalf of
321 the device-specific driver. GLD also implements the \fBgetinfo\fR(9E) function
322 for the driver.
323 .sp
324 .LP
325 The \fBmi_idname\fR element of the \fBmodule_info\fR(9S) structure is a string
326 specifying the name of the driver. This must exactly match the name of the
327 driver module as it exists in the file system.
328 .sp
329 .LP
330 The read-side \fBqinit\fR(9S) structure should specify the following elements
331 as shown below:
332 .sp
333 .ne 2
334 .na
335 \fB\fBqi_putp\fR \fR
336 .ad
337 .RS 14n
338 \fINULL\fR
339 .RE
341 .sp
342 .ne 2
343 .na
344 \fB\fBqi_srvp\fR \fR
345 .ad
346 .RS 14n
347 \fBgld_rsrv\fR
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fBqi_qopen\fR \fR
354 .ad
355 .RS 14n
356 \fBgld_open\fR
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBqi_qclose\fR \fR
363 .ad
364 .RS 14n
365 \fBgld_close\fR
366 .RE
368 .sp
369 .LP
370 The write-side \fBqinit\fR(9S) structure should specify the following elements
371 as shown below:
372 .sp
373 .ne 2
374 .na
375 \fB\fBqi_putp\fR \fR
376 .ad
377 .RS 14n
378 \fBgld_wput\fR
379 .RE
381 .sp
382 .ne 2
383 .na
384 \fB\fBqi_srvp\fR \fR
385 .ad
386 .RS 14n
387 \fBgld_wsrv\fR
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fB\fBqi_qopen\fR \fR
394 .ad
395 .RS 14n
396 \fINULL\fR
397 .RE
399 .sp
400 .ne 2
401 .na
402 \fB\fBqi_qclose\fR \fR
403 .ad
404 .RS 14n
405 \fINULL\fR
406 .RE
408 .sp
409 .LP
410 The \fBdevo_getinfo\fR element of the \fBdev_ops\fR(9S) structure should
411 specify \fBgld_getinfo\fR as the \fBgetinfo\fR(9E) routine.
412 .sp
413 .LP
414 The driver's \fBattach\fR(9E) function does all the work of associating the
415 hardware-specific device driver with the GLD facility and preparing the device
416 and driver for use.
417 .sp
418 .LP
419 The \fBattach\fR(9E) function allocates a \fBgld_mac_info\fR(9S) (``macinfo'')
420 structure using \fBgld_mac_alloc()\fR. The driver usually needs to save more
421 information per device than is defined in the macinfo structure; it should
422 allocate the additional required data structure and save a pointer to it in the
423 \fBgldm_private\fR member of the \fBgld_mac_info\fR(9S) structure.
424 .sp
425 .LP
426 The \fBattach\fR(9E) routine must initialize the macinfo structure as described
427 in \fBgld_mac_info\fR(9S) and then call \fBgld_register()\fR to link the driver
428 with the GLD module. The driver should map registers if necessary and be fully
429 initialized and prepared to accept interrupts before calling
430 \fBgld_register()\fR. The \fBattach\fR(9E) function should add interrupts but
431 not enable the device to generate them. The driver should reset the hardware
432 before calling \fBgld_register()\fR to ensure it is quiescent; the device must
433 not be started or put into a state where it may generate an interrupt before
434 \fBgld_register()\fR is called. That will be done later when GLD calls the
435 driver's \fBgldm_start()\fR entry point described in \fBgld\fR(9E). Once
436 \fBgld_register()\fR succeeds, the \fBgld\fR(9E) entry points may be called by
437 GLD at any time.
438 .sp
439 .LP
440 The \fBattach\fR(9E) routine should return \fBDDI_SUCCESS\fR if
441 \fBgld_register()\fR succeeds. If \fBgld_register()\fR fails, it returns
442 \fBDDI_FAILURE\fR and the \fBattach\fR(9E) routine should deallocate any
443 resources it allocated before calling \fBgld_register()\fR and then also return
444 \fBDDI_FAILURE\fR. Under no circumstances should a failed macinfo structure be
445 reused; it should be deallocated using \fBgld_mac_free\fR().
446 .sp
447 .LP
448 The \fBdetach\fR(9E) function should attempt to unregister the driver from GLD.
449 This is done by calling \fBgld_unregister()\fR described in \fBgld\fR(9F). The
450 \fBdetach\fR(9E) routine can get a pointer to the needed \fBgld_mac_info\fR(9S)
451 structure from the device's private data using
452 \fBddi_get_driver_private\fR(9F). \fBgld_unregister\fR() checks certain
453 conditions that could require that the driver not be detached. If the checks
454 fail, \fBgld_unregister()\fR returns \fBDDI_FAILURE\fR, in which case the
455 driver's \fBdetach\fR(9E) routine must leave the device operational and return
456 \fBDDI_FAILURE\fR. If the checks succeed, \fBgld_unregister()\fR ensures that
457 the device interrupts are stopped, calling the driver's \fBgldm_stop()\fR
458 routine if necessary, unlinks the driver from the GLD framework, and returns
459 \fBDDI_SUCCESS\fR. In this case, the \fBdetach\fR(9E) routine should remove
460 interrupts, deallocate any data structures allocated in the \fBattach\fR(9E)
461 routine, using \fBgld_mac_free()\fR to deallocate the macinfo structure, and
462 return \fBDDI_SUCCESS\fR. It is important to remove the interrupt \fIbefore\fR
463 calling \fBgld_mac_free()\fR.
464 .SS "Network Statistics"
465 .sp
466 .LP
467 Solaris network drivers must implement statistics variables. GLD itself tallies
468 some network statistics, but other statistics must be counted by each GLD-based
469 driver. GLD provides support for GLD-based drivers to report a standard set of
470 network driver statistics. Statistics are reported by GLD using the
471 \fBkstat\fR(7D) and \fBkstat\fR(9S) mechanism. The \fBDL_GET_STATISTICS_REQ\fR
472 DLPI command may also be used to retrieve the current statistics counters. All
473 statistics are maintained as unsigned, and all are 32 bits unless otherwise
474 noted.
475 .sp
476 .LP
477 GLD maintains and reports the following statistics.
478 .sp
479 .ne 2
480 .na
481 \fB\fBrbytes64\fR \fR
482 .ad
483 .RS 15n
484 Total bytes successfully received on the interface (64 bits).
485 .RE
487 .sp
488 .ne 2
489 .na
490 \fB\fBrbytes\fR \fR
491 .ad
492 .RS 15n
493 Total bytes successfully received on the interface.
494 .RE
496 .sp
497 .ne 2
498 .na
499 \fB\fBobytes64\fR \fR
500 .ad
501 .RS 15n
502 Total bytes requested to be transmitted on the interface (64 bits).
503 .RE
505 .sp
506 .ne 2
507 .na
508 \fB\fBobytes\fR \fR
509 .ad
510 .RS 15n
511 Total bytes requested to be transmitted on the interface.
512 .RE
514 .sp
515 .ne 2
516 .na
517 \fB\fBipackets64\fR \fR
518 .ad
519 .RS 15n
520 Total packets successfully received on the interface (64 bits).
521 .RE
523 .sp
524 .ne 2
525 .na
526 \fB\fBipackets\fR \fR
527 .ad
528 .RS 15n
529 Total packets successfully received on the interface.
530 .RE
532 .sp
533 .ne 2
534 .na
535 \fB\fBopackets64\fR \fR
536 .ad
537 .RS 15n
538 Total packets requested to be transmitted on the interface (64 bits).
539 .RE
541 .sp
542 .ne 2
543 .na
544 \fB\fBopackets\fR \fR
545 .ad
546 .RS 15n
547 Total packets requested to be transmitted on the interface.
548 .RE
550 .sp
551 .ne 2
552 .na
553 \fB\fBmultircv\fR \fR
554 .ad
555 .RS 15n
556 Multicast packets successfully received, including group and functional
557 addresses (long).
558 .RE
560 .sp
561 .ne 2
562 .na
563 \fB\fBmultixmt\fR \fR
564 .ad
565 .RS 15n
566 Multicast packets requested to be transmitted, including group and functional
567 addresses (long).
568 .RE
570 .sp
571 .ne 2
572 .na
573 \fB\fBbrdcstrcv\fR \fR
574 .ad
575 .RS 15n
576 Broadcast packets successfully received (long).
577 .RE
579 .sp
580 .ne 2
581 .na
582 \fB\fBbrdcstxmt\fR \fR
583 .ad
584 .RS 15n
585 Broadcast packets requested to be transmitted (long).
586 .RE
588 .sp
589 .ne 2
590 .na
591 \fB\fBunknowns\fR \fR
592 .ad
593 .RS 15n
594 Valid received packets not accepted by any stream (long).
595 .RE
597 .sp
598 .ne 2
599 .na
600 \fB\fBnoxmtbuf\fR \fR
601 .ad
602 .RS 15n
603 Packets discarded on output because transmit buffer was busy, or no buffer
604 could be allocated for transmit (long).
605 .RE
607 .sp
608 .ne 2
609 .na
610 \fB\fBblocked\fR \fR
611 .ad
612 .RS 15n
613 Times a received packet could not be put up a stream because the queue was flow
614 controlled (long).
615 .RE
617 .sp
618 .ne 2
619 .na
620 \fB\fBxmtretry\fR \fR
621 .ad
622 .RS 15n
623 Times transmit was retried after having been delayed due to lack of resources
624 (long).
625 .RE
627 .sp
628 .ne 2
629 .na
630 \fB\fBpromisc\fR \fR
631 .ad
632 .RS 15n
633 Current ``promiscuous'' state of the interface (string).
634 .RE
636 .sp
637 .LP
638 The device dependent driver counts the following statistics, keeping track of
639 them in a private per-instance structure. When GLD is asked to report
640 statistics, it calls the driver's \fBgldm_get_stats()\fR entry point, as
641 described in \fBgld\fR(9E), to update the device-specific statistics in the
642 \fBgld_stats\fR(9S) structure. GLD then reports the updated statistics using
643 the named statistics variables below.
644 .sp
645 .ne 2
646 .na
647 \fB\fBifspeed\fR \fR
648 .ad
649 .RS 13n
650 Current estimated bandwidth of the interface in bits per second (64 bits).
651 .RE
653 .sp
654 .ne 2
655 .na
656 \fB\fBmedia\fR \fR
657 .ad
658 .RS 13n
659 Current media type in use by the device (string).
660 .RE
662 .sp
663 .ne 2
664 .na
665 \fB\fBintr\fR \fR
666 .ad
667 .RS 13n
668 Times interrupt handler was called and claimed the interrupt (long).
669 .RE
671 .sp
672 .ne 2
673 .na
674 \fB\fBnorcvbuf\fR \fR
675 .ad
676 .RS 13n
677 Times a valid incoming packet was known to have been discarded because no
678 buffer could be allocated for receive (long).
679 .RE
681 .sp
682 .ne 2
683 .na
684 \fB\fBierrors\fR \fR
685 .ad
686 .RS 13n
687 Total packets received that couldn't be processed because they contained errors
688 (long).
689 .RE
691 .sp
692 .ne 2
693 .na
694 \fB\fBoerrors\fR \fR
695 .ad
696 .RS 13n
697 Total packets that weren't successfully transmitted because of errors (long).
698 .RE
700 .sp
701 .ne 2
702 .na
703 \fB\fBmissed\fR \fR
704 .ad
705 .RS 13n
706 Packets known to have been dropped by the hardware on receive (long).
707 .RE
709 .sp
710 .ne 2
711 .na
712 \fB\fBuflo\fR \fR
713 .ad
714 .RS 13n
715 Times FIFO underflowed on transmit (long).
716 .RE
718 .sp
719 .ne 2
720 .na
721 \fB\fBoflo\fR \fR
722 .ad
723 .RS 13n
724 Times receiver overflowed during receive (long).
725 .RE
727 .sp
728 .LP
729 The following group of statistics applies to networks of type \fBDL_ETHER\fR;
730 these are maintained by device-specific drivers of that type, as above.
731 .sp
732 .ne 2
733 .na
734 \fB\fBalign_errors\fR \fR
735 .ad
736 .RS 23n
737 Packets received with framing errors (not an integral number of octets) (long).
738 .RE
740 .sp
741 .ne 2
742 .na
743 \fB\fBfcs_errors\fR \fR
744 .ad
745 .RS 23n
746 Packets received with CRC errors (long).
747 .RE
749 .sp
750 .ne 2
751 .na
752 \fB\fBduplex\fR \fR
753 .ad
754 .RS 23n
755 Current duplex mode of the interface (string).
756 .RE
758 .sp
759 .ne 2
760 .na
761 \fB\fBcarrier_errors\fR \fR
762 .ad
763 .RS 23n
764 Times carrier was lost or never detected on a transmission attempt (long).
765 .RE
767 .sp
768 .ne 2
769 .na
770 \fB\fBcollisions\fR \fR
771 .ad
772 .RS 23n
773 Ethernet collisions during transmit (long).
774 .RE
776 .sp
777 .ne 2
778 .na
779 \fB\fBex_collisions\fR \fR
780 .ad
781 .RS 23n
782 Frames where excess collisions occurred on transmit, causing transmit failure
783 (long).
784 .RE
786 .sp
787 .ne 2
788 .na
789 \fB\fBtx_late_collisions\fR \fR
790 .ad
791 .RS 23n
792 Times a transmit collision occurred late (after 512 bit times) (long).
793 .RE
795 .sp
796 .ne 2
797 .na
798 \fB\fBdefer_xmts\fR \fR
799 .ad
800 .RS 23n
801 Packets without collisions where first transmit attempt was delayed because the
802 medium was busy (long).
803 .RE
805 .sp
806 .ne 2
807 .na
808 \fB\fBfirst_collisions\fR \fR
809 .ad
810 .RS 23n
811 Packets successfully transmitted with exactly one collision.
812 .RE
814 .sp
815 .ne 2
816 .na
817 \fB\fBmulti_collisions\fR \fR
818 .ad
819 .RS 23n
820 Packets successfully transmitted with multiple collisions.
821 .RE
823 .sp
824 .ne 2
825 .na
826 \fB\fBsqe_errors\fR \fR
827 .ad
828 .RS 23n
829 Times SQE test error was reported.
830 .RE
832 .sp
833 .ne 2
834 .na
835 \fB\fBmacxmt_errors\fR \fR
836 .ad
837 .RS 23n
838 Packets encountering transmit MAC failures, except carrier and collision
839 failures.
840 .RE
842 .sp
843 .ne 2
844 .na
845 \fB\fBmacrcv_errors\fR \fR
846 .ad
847 .RS 23n
848 Packets received with MAC errors, except align, fcs, and toolong errors.
849 .RE
851 .sp
852 .ne 2
853 .na
854 \fB\fBtoolong_errors\fR \fR
855 .ad
856 .RS 23n
857 Packets received larger than the maximum permitted length.
858 .RE
860 .sp
861 .ne 2
862 .na
863 \fB\fBrunt_errors\fR \fR
864 .ad
865 .RS 23n
866 Packets received smaller than the minimum permitted length (long).
867 .RE
869 .sp
870 .LP
871 The following group of statistics applies to networks of type \fBDL_TPR\fR;
872 these are maintained by device-specific drivers of that type, as above.
873 .sp
874 .ne 2
875 .na
876 \fB\fBline_errors\fR \fR
877 .ad
878 .RS 24n
879 Packets received with non-data bits or FCS errors.
880 .RE
882 .sp
883 .ne 2
884 .na
885 \fB\fBburst_errors\fR \fR
886 .ad
887 .RS 24n
888 Times an absence of transitions for five half-bit timers was detected.
889 .RE
891 .sp
892 .ne 2
893 .na
894 \fB\fBsignal_losses\fR \fR
895 .ad
896 .RS 24n
897 Times loss of signal condition on the ring was detected.
898 .RE
900 .sp
901 .ne 2
902 .na
903 \fB\fBace_errors\fR \fR
904 .ad
905 .RS 24n
906 Times an AMP or SMP frame in which A is equal to C is equal to 0, was followed
907 by another such SMP frame without an intervening AMP frame.
908 .RE
910 .sp
911 .ne 2
912 .na
913 \fB\fBinternal_errors\fR \fR
914 .ad
915 .RS 24n
916 Times the station recognized an internal error.
917 .RE
919 .sp
920 .ne 2
921 .na
922 \fB\fBlost_frame_errors\fR \fR
923 .ad
924 .RS 24n
925 Times the TRR timer expired during transmit.
926 .RE
928 .sp
929 .ne 2
930 .na
931 \fB\fBframe_copied_errors\fR \fR
932 .ad
933 .RS 24n
934 Times a frame addressed to this station was received with the FS field A bit
935 set to 1.
936 .RE
938 .sp
939 .ne 2
940 .na
941 \fB\fBtoken_errors\fR \fR
942 .ad
943 .RS 24n
944 Times the station acting as the active monitor recognized an error condition
945 that needed a token transmitted.
946 .RE
948 .sp
949 .ne 2
950 .na
951 \fB\fBfreq_errors\fR \fR
952 .ad
953 .RS 24n
954 Times the frequency of the incoming signal differed from the expected
955 frequency.
956 .RE
958 .sp
959 .LP
960 The following group of statistics applies to networks of type \fBDL_FDDI\fR;
961 these are maintained by device-specific drivers of that type, as above.
962 .sp
963 .ne 2
964 .na
965 \fB\fBmac_errors\fR \fR
966 .ad
967 .RS 20n
968 Frames detected in error by this MAC that had not been detected in error by
969 another MAC.
970 .RE
972 .sp
973 .ne 2
974 .na
975 \fB\fBmac_lost_errors\fR \fR
976 .ad
977 .RS 20n
978 Frames received with format errors such that the frame was stripped.
979 .RE
981 .sp
982 .ne 2
983 .na
984 \fB\fBmac_tokens\fR \fR
985 .ad
986 .RS 20n
987 Number of tokens received (total of non-restricted and restricted).
988 .RE
990 .sp
991 .ne 2
992 .na
993 \fB\fBmac_tvx_expired\fR \fR
994 .ad
995 .RS 20n
996 Number of times that TVX has expired.
997 .RE
999 .sp
1000 .ne 2
1001 .na
1002 \fB\fBmac_late\fR \fR
1003 .ad
1004 .RS 20n
1005 Number of TRT expirations since this MAC was reset or a token was received.
1006 .RE
1008 .sp
1009 .ne 2
1010 .na
1011 \fB\fBmac_ring_ops\fR \fR
1012 .ad
1013 .RS 20n
1014 Number of times the ring has entered the ``Ring_Operational'' state from the
1015 ``Ring Not Operational'' state.
1016 .RE
1018 .SH FILES
1019 .sp
1020 .ne 2
1021 .na
1022 \fB\fB/kernel/misc/gld\fR \fR
1023 .ad
1024 .RS 21n
1025 loadable kernel module
1026 .RE
1028 .SH SEE ALSO
1029 .sp
1030 .LP
1031 \fBld\fR(1), \fBkstat\fR(7D), \fBdlpi\fR(7P), \fBattach\fR(9E), \fBgld\fR(9E),
1032 \fBopen\fR(9E), \fBgld\fR(9F), \fBgld_mac_info\fR(9S), \fBgld_stats\fR(9S),
1033 \fBkstat\fR(9S)
1034 .sp
1035 .LP
1036 \fIWriting Device Drivers\fR
1037 .SH WARNINGS
1038 .sp
1039 .LP
1040 Contrary to the DLPI specification, GLD returns the device's correct address
1041 length and broadcast address in \fBDL_INFO_ACK\fR even before the stream has
1042 been attached to a \fBPPA\fR.
1043 .sp
1044 .LP
1045 Promiscuous mode may only be entered by streams that are attached to a
1046 \fBPPA\fR.
1047 .sp
1048 .LP
1049 The physical address of a \fBPPA\fR may be changed by the superuser while other
1050 streams are bound to the same PPA.