1gld(7D) Devices gld(7D)
2
6 gld - Generic LAN Driver
7
9 #include <sys/stropts.h>
10 #include <sys/stream.h>
13 #include <sys/dlpi.h>
16 #include <sys/gld.h>
19
22 Solaris architecture specific (Solaris DDI).
23
25 GLD is a multi-threaded, clonable, loadable kernel module providing
26 support for Solaris local area network (LAN) device drivers. LAN driv‐
27 ers in Solaris are STREAMS-based drivers that use the Data Link
28 Provider Interface (DLPI) to communicate with network protocol stacks.
29 These protocol stacks use the network drivers to send and receive pack‐
30 ets on a local area network. A network device driver must implement and
31 adhere to the requirements imposed by the DDI/DKI specification,
32 STREAMS specification, DLPI specification, and programmatic interface
33 of the device itself.
34 GLD implements most STREAMS and DLPI functionality required of a
37 Solaris LAN driver. Several Solaris network drivers are implemented
38 using GLD.
39 A Solaris network driver implemented using GLD comprises two distinct
42 parts: a generic component that deals with STREAMS and DLPI interfaces,
43 and a device-specific component that deals with the particular hardware
44 device. The device-specific module indicates its dependency on the GLD
45 module and registers itself with GLD from within the driver's
46 attach(9E) function. Once it is successfully loaded, the driver is
47 DLPI-compliant. The device-specific part of the driver calls gld(9F)
48 functions when it receives data or needs some service from GLD. GLD
49 makes calls into the gld(9E) entry points of the device-specific driver
50 through pointers provided to GLD by the device-specific driver when it
51 registered itself with GLD. The gld_mac_info(9S) structure is the main
52 data interface between GLD and the device-specific driver.
53 The GLD facility currently supports devices of type DL_ETHER, DL_TPR,
56 and DL_FDDI. GLD drivers are expected to process fully-formed MAC-layer
57 packets and should not perform logical link control (LLC) handling.
58 Note -
60 Support for the DL_TPR and DL_FDDI media types in GLD is obsolete and
62 may be removed in a future release of Solaris.
63 In some cases, it may be necessary or desirable to implement a full
66 DLPI-compliant driver without using the GLD facility. This is true for
67 devices that are not IEEE 802-style LAN devices, or where a device type
68 or DLPI service not supported by GLD is required.
69 Device Naming Constraints
71 The name of the device-specific driver module must adhere to the naming
72 constraints outlined in the NOTES section of dlpi(7P).
73 Type DL_ETHER: Ethernet V2 and ISO 8802-3 (IEEE 802.3)
75 For devices designated type DL_ETHER, GLD provides support for both
76 Ethernet V2 and ISO 8802-3 (IEEE 802.3) packet processing. Ethernet V2
77 enables a data link service user to access and use any of a variety of
78 conforming data link service providers without special knowledge of the
79 provider's protocol. A service access point (SAP) is the point through
80 which the user communicates with the service provider.
81 SAP 0 denotes that the user wishes to use 802.3 mode. In transmis‐
84 sion, GLD checks the destination SAP value of the DL_UNITDATA_REQ and
85 the SAP value to which the stream is bound. If both are 0, the GLD
86 computes the length of the packet payload and transmits 802.3 frames
87 having that length in the MAC frame header type field. Such lengths
88 will never exceed 1500.
89 All frames received from the media that have a type field in the range
92 [0-1500] are assumed to be 802.3 frames and are routed up all open
93 streams that are in 802.3 mode, (those streams bound to a SAP value
94 in of 0. If more than one stream is in 802.3 mode, the incoming frame
95 is duplicated and routed up each such stream.
96 Streams bound to a SAP value of 1536 or greater receive incoming
99 packets whose Ethernet MAC header type value exactly matches the value
100 of the SAP to which the stream is bound. SAP values in the range
101 [1-1535] are undefined and should not be used.
102 Types DL_TPR and DL_FDDI: SNAP Processing
104 Note -
105 Support for the DL_TPR and DL_FDDI media types in GLD is obsolete and
107 may be removed in a future release of Solaris.
108 For media types DL_TPR and DL_FDDI, GLD implements minimal SNAP (Sub-
111 Net Access Protocol) processing for SAP values of 1536 or greater. A
112 SAP value of 0 denotes that the user wishes to use LLC mode. SAP values
113 in the range [1-1535] have undefined semantics and should not be used.
114 SNAP headers are carried under LLC headers with destination SAP 0xAA.
117 For outgoing packets with SAP values greater than 1535, GLD creates an
118 LLC+SNAP header that always looks like:
119 ``AA AA 03 00 00 00 XX XX''
122 where ``XX XX'' represents the 16-bit SAP, corresponding to the Eth‐
125 ernet V2 style ``type.'' This is the only class of SNAP header that is
126 processed - non-zero OUI fields, and LLC control fields other than 03
127 are considered to be LLC packets with SAP 0xAA.
128 A DL_UNITDATA_REQ message specifying a destination SAP value of 0,
131 passed down a stream bound to SAP 0, is assumed to contain an
132 LLC packet and will not undergo SNAP processing.
133 Incoming packets are examined to ascertain whether they fall into the
136 format specified above. Packets that do will be passed to streams bound
137 to the packet's 16-bit SNAP type, as well as being passed to any stream
138 in LLC mode (those bound to a SAP value of 0).
139 Type DL_TPR: Source Routing
141 Note -
142 Support for the DL_TPR media type in GLD is obsolete and may be
144 removed in a future release of Solaris.
145 For type DL_TPR devices, GLD implements minimal support for source
148 routing. Source routing enables a station that is sending a packet
149 across a bridged medium to specify (in the packet MAC header) routing
150 information that determines the route that the packet will take through
151 the network.
152 Functionally, the source routing support provided by GLD learns routes,
155 solicits and responds to requests for information about possible multi‐
156 ple routes and selects among the multiple routes that are available. It
157 adds Routing Information Fields to the MAC headers of outgoing packets
158 and recognizes such fields in incoming packets.
159 GLD's source routing support does not implement the full Route Determi‐
162 nation Entity (RDE) specified in ISO 8802-2 (IEEE 802.2) Section 9.
163 However, it is designed to interoperate with any such implementations
164 that may exist in the same (or a bridged) network.
165 Style 1 and 2 Providers
167 GLD implements both Style 1 and Style 2 providers. A physical point of
168 attachment (PPA) is the point at which a system attaches itself to a
169 physical communication medium. All communication on that physical
170 medium funnels through the PPA. The Style 1 provider attaches the
171 stream to a particular PPA based on the major/minor device that has
172 been opened. The Style 2 provider requires the DLS user to explicitly
173 identify the desired PPA using DL_ATTACH_REQ. In this case, open(9E)
174 creates a stream between the user and GLD and DL_ATTACH_REQ subse‐
175 quently associates a particular PPA with that stream. Style 2 is
176 denoted by a minor number of zero. If a device node whose minor number
177 is not zero is opened, Style 1 is indicated and the associated PPA is
178 the minor number minus 1. In both Style 1 and Style 2 opens, the device
179 is cloned.
180 Implemented DLPI Primitives
182 GLD implements the following DLPI primitives:
183 The DL_INFO_REQ primitive requests information about the DLPI stream.
186 The message consists of one M_PROTO message block. GLD returns device-
187 dependent values in the DL_INFO_ACK response to this request, based on
188 information the GLD-based driver specified in the gld_mac_info(9S)
189 structure passed to gld_register(). However GLD returns the following
190 values on behalf of all GLD-based drivers:
191 o The version is DL_VERSION_2.
193 o The service mode is DL_CLDLS — GLD implements connection‐
195 less-mode service.
196 o The provider style is DL_STYLE1 or DL_STYLE2, depending on
198 how the stream was opened.
199 The DL_ATTACH_REQ primitive is called to associate a PPA with a stream.
202 This request is needed for Style 2 DLS providers to identify the physi‐
203 cal medium over which the communication will transpire. Upon comple‐
204 tion, the state changes from DL_UNATTACHED to DL_UNBOUND. The message
205 consists of one M_PROTO message block. This request may not be issued
206 when using the driver in Style 1 mode; streams opened using Style 1 are
207 already attached to a PPA by the time the open completes.
208 The DL_DETACH_REQ primitive requests to detach the PPA from the stream.
211 This is only allowed if the stream was opened using Style 2.
212 The DL_BIND_REQ and DL_UNBIND_REQ primitives bind and unbind a DLSAP to
215 the stream. The PPA associated with each stream will have been initial‐
216 ized upon completion of the processing of the DL_BIND_REQ. Multiple
217 streams may be bound to the same SAP; each such stream receives a copy
218 of any packets received for that SAP.
219 The DL_ENABMULTI_REQ and DL_DISABMULTI_REQ primitives enable and dis‐
222 able reception of individual multicast group addresses. A set of multi‐
223 cast addresses may be iteratively created and modified on a per-stream
224 basis using these primitives. The stream must be attached to a PPA for
225 these primitives to be accepted.
226 The DL_PROMISCON_REQ and DL_PROMISCOFF_REQ primitives enable and dis‐
229 able promiscuous mode on a per-stream basis, either at a physical level
230 or at the SAP level. The DL Provider will route all received messages
231 on the media to the DLS user until either a DL_DETACH_REQ or a
232 DL_PROMISCOFF_REQ is received or the stream is closed. Physical level
233 promiscuous mode may be specified for all packets on the medium or for
234 multicast packets only. The stream must be attached to a PPA for these
235 primitives to be accepted.
236 The DL_UNITDATA_REQ primitive is used to send data in a connectionless
239 transfer. Because this is an unacknowledged service, there is no guar‐
240 antee of delivery. The message consists of one M_PROTO message block
241 followed by one or more M_DATA blocks containing at least one byte of
242 data.
243 The DL_UNITDATA_IND type is used when a packet is received and is to be
246 passed upstream. The packet is put into an M_PROTO message with the
247 primitive set to DL_UNITDATA_IND.
248 The DL_PHYS_ADDR_REQ primitive returns the MAC address currently asso‐
251 ciated with the PPA attached to the stream, in the DL_PHYS_ADDR_ACK
252 primitive. When using style 2, this primitive is only valid following a
253 successful DL_ATTACH_REQ.
254 The DL_SET_PHYS_ADDR_REQ primitive changes the MAC address currently
257 associated with the PPA attached to the stream. This primitive affects
258 all other current and future streams attached to this device. Once
259 changed, all streams currently or subsequently opened and attached to
260 this device will obtain this new physical address. The new physical
261 address will remain in effect until this primitive is used to change
262 the physical address again or the driver is reloaded.
263 The DL_GET_STATISTICS_REQ primitive requests a DL_GET_STATISTICS_ACK
266 response containing statistics information associated with the PPA
267 attached to the stream. Style 2 streams must be attached to a particu‐
268 lar PPA using DL_ATTACH_REQ before this primitive will be successful.
269 GLD supports the DL_NOTE_LINK_UP, DL_NOTE_LINK_DOWN and DL_NOTE_SPEED
272 notifications using the DL_NOTIFY_IND primitive. See dlpi(7P).
273 Implemented ioctl Functions
275 GLD implements the DLIOCRAW ioctl described in dlpi(7P). For any other
276 ioctl command, GLD passes it to the device-specific driver's
277 gldm_ioctl() function as described in gld(9E).
278 Requirements on GLD Drivers
280 GLD-based drivers must include the header file <sys/gld.h>.
281 GLD-based drivers must also specify a link dependency on "misc/gld".
284 (See the -N option in ld(1)).
285 GLD implements the open(9E) and close(9E) functions and the required
288 STREAMS put(9E) and srv(9E) functions on behalf of the device-specific
289 driver. GLD also implements the getinfo(9E) function for the driver.
290 The mi_idname element of the module_info(9S) structure is a string
293 specifying the name of the driver. This must exactly match the name of
294 the driver module as it exists in the file system.
295 The read-side qinit(9S) structure should specify the following elements
298 as shown below:
299 qi_putp NULL
301 qi_srvp gld_rsrv
304 qi_qopen gld_open
307 qi_qclose gld_close
310 The write-side qinit(9S) structure should specify the following ele‐
314 ments as shown below:
315 qi_putp gld_wput
317 qi_srvp gld_wsrv
320 qi_qopen NULL
323 qi_qclose NULL
326 The devo_getinfo element of the dev_ops(9S) structure should specify
330 gld_getinfo as the getinfo(9E) routine.
331 The driver's attach(9E) function does all the work of associating the
334 hardware-specific device driver with the GLD facility and preparing the
335 device and driver for use.
336 The attach(9E) function allocates a gld_mac_info(9S) (``macinfo'')
339 structure using gld_mac_alloc(). The driver usually needs to save more
340 information per device than is defined in the macinfo structure; it
341 should allocate the additional required data structure and save a
342 pointer to it in the gldm_private member of the gld_mac_info(9S) struc‐
343 ture.
344 The attach(9E) routine must initialize the macinfo structure as
347 described in gld_mac_info(9S) and then call gld_register() to link the
348 driver with the GLD module. The driver should map registers if neces‐
349 sary and be fully initialized and prepared to accept interrupts before
350 calling gld_register(). The attach(9E) function should add interrupts
351 but not enable the device to generate them. The driver should reset the
352 hardware before calling gld_register() to ensure it is quiescent; the
353 device must not be started or put into a state where it may generate an
354 interrupt before gld_register() is called. That will be done later when
355 GLD calls the driver's gldm_start() entry point described in gld(9E).
356 Once gld_register() succeeds, the gld(9E) entry points may be called by
357 GLD at any time.
358 The attach(9E) routine should return DDI_SUCCESS if gld_register() suc‐
361 ceeds. If gld_register() fails, it returns DDI_FAILURE and the
362 attach(9E) routine should deallocate any resources it allocated before
363 calling gld_register() and then also return DDI_FAILURE. Under no cir‐
364 cumstances should a failed macinfo structure be reused; it should be
365 deallocated using gld_mac_free().
366 The detach(9E) function should attempt to unregister the driver from
369 GLD. This is done by calling gld_unregister() described in gld(9F). The
370 detach(9E) routine can get a pointer to the needed gld_mac_info(9S)
371 structure from the device's private data using ddi_get_driver_pri‐
372 vate(9F). gld_unregister() checks certain conditions that could require
373 that the driver not be detached. If the checks fail, gld_unregister()
374 returns DDI_FAILURE, in which case the driver's detach(9E) routine must
375 leave the device operational and return DDI_FAILURE. If the checks suc‐
376 ceed, gld_unregister() ensures that the device interrupts are stopped,
377 calling the driver's gldm_stop() routine if necessary, unlinks the
378 driver from the GLD framework, and returns DDI_SUCCESS. In this case,
379 the detach(9E) routine should remove interrupts, deallocate any data
380 structures allocated in the attach(9E) routine, using gld_mac_free() to
381 deallocate the macinfo structure, and return DDI_SUCCESS. It is impor‐
382 tant to remove the interrupt before calling gld_mac_free().
383 Network Statistics
385 Solaris network drivers must implement statistics variables. GLD itself
386 tallies some network statistics, but other statistics must be counted
387 by each GLD-based driver. GLD provides support for GLD-based drivers to
388 report a standard set of network driver statistics. Statistics are
389 reported by GLD using the kstat(7D) and kstat(9S) mechanism. The
390 DL_GET_STATISTICS_REQ DLPI command may also be used to retrieve the
391 current statistics counters. All statistics are maintained as unsigned,
392 and all are 32 bits unless otherwise noted.
393 GLD maintains and reports the following statistics.
396 rbytes64 Total bytes successfully received on the interface (64
398 bits).
399 rbytes Total bytes successfully received on the interface.
402 obytes64 Total bytes requested to be transmitted on the interface
405 (64 bits).
406 obytes Total bytes requested to be transmitted on the inter‐
409 face.
410 ipackets64 Total packets successfully received on the interface (64
413 bits).
414 ipackets Total packets successfully received on the interface.
417 opackets64 Total packets requested to be transmitted on the inter‐
420 face (64 bits).
421 opackets Total packets requested to be transmitted on the inter‐
424 face.
425 multircv Multicast packets successfully received, including group
428 and functional addresses (long).
429 multixmt Multicast packets requested to be transmitted, including
432 group and functional addresses (long).
433 brdcstrcv Broadcast packets successfully received (long).
436 brdcstxmt Broadcast packets requested to be transmitted (long).
439 unknowns Valid received packets not accepted by any stream
442 (long).
443 noxmtbuf Packets discarded on output because transmit buffer was
446 busy, or no buffer could be allocated for transmit
447 (long).
448 blocked Times a received packet could not be put up a stream
451 because the queue was flow controlled (long).
452 xmtretry Times transmit was retried after having been delayed due
455 to lack of resources (long).
456 promisc Current ``promiscuous'' state of the interface (string).
459 The device dependent driver counts the following statistics, keeping
463 track of them in a private per-instance structure. When GLD is asked to
464 report statistics, it calls the driver's gldm_get_stats() entry point,
465 as described in gld(9E), to update the device-specific statistics in
466 the gld_stats(9S) structure. GLD then reports the updated statistics
467 using the named statistics variables below.
468 ifspeed Current estimated bandwidth of the interface in bits per
470 second (64 bits).
471 media Current media type in use by the device (string).
474 intr Times interrupt handler was called and claimed the inter‐
477 rupt (long).
478 norcvbuf Times a valid incoming packet was known to have been dis‐
481 carded because no buffer could be allocated for receive
482 (long).
483 ierrors Total packets received that couldn't be processed because
486 they contained errors (long).
487 oerrors Total packets that weren't successfully transmitted
490 because of errors (long).
491 missed Packets known to have been dropped by the hardware on
494 receive (long).
495 uflo Times FIFO underflowed on transmit (long).
498 oflo Times receiver overflowed during receive (long).
501 The following group of statistics applies to networks of type DL_ETHER;
505 these are maintained by device-specific drivers of that type, as above.
506 align_errors Packets received with framing errors (not an
508 integral number of octets) (long).
509 fcs_errors Packets received with CRC errors (long).
512 duplex Current duplex mode of the interface (string).
515 carrier_errors Times carrier was lost or never detected on a
518 transmission attempt (long).
519 collisions Ethernet collisions during transmit (long).
522 ex_collisions Frames where excess collisions occurred on
525 transmit, causing transmit failure (long).
526 tx_late_collisions Times a transmit collision occurred late (after
529 512 bit times) (long).
530 defer_xmts Packets without collisions where first transmit
533 attempt was delayed because the medium was busy
534 (long).
535 first_collisions Packets successfully transmitted with exactly
538 one collision.
539 multi_collisions Packets successfully transmitted with multiple
542 collisions.
543 sqe_errors Times SQE test error was reported.
546 macxmt_errors Packets encountering transmit MAC failures,
549 except carrier and collision failures.
550 macrcv_errors Packets received with MAC errors, except align,
553 fcs, and toolong errors.
554 toolong_errors Packets received larger than the maximum permit‐
557 ted length.
558 runt_errors Packets received smaller than the minimum per‐
561 mitted length (long).
562 The following group of statistics applies to networks of type DL_TPR;
566 these are maintained by device-specific drivers of that type, as above.
567 line_errors Packets received with non-data bits or FCS
569 errors.
570 burst_errors Times an absence of transitions for five half-
573 bit timers was detected.
574 signal_losses Times loss of signal condition on the ring was
577 detected.
578 ace_errors Times an AMP or SMP frame in which A is equal
581 to C is equal to 0, was followed by another
582 such SMP frame without an intervening AMP
583 frame.
584 internal_errors Times the station recognized an internal error.
587 lost_frame_errors Times the TRR timer expired during transmit.
590 frame_copied_errors Times a frame addressed to this station was
593 received with the FS field A bit set to 1.
594 token_errors Times the station acting as the active monitor
597 recognized an error condition that needed a
598 token transmitted.
599 freq_errors Times the frequency of the incoming signal dif‐
602 fered from the expected frequency.
603 The following group of statistics applies to networks of type DL_FDDI;
607 these are maintained by device-specific drivers of that type, as above.
608 mac_errors Frames detected in error by this MAC that had not
610 been detected in error by another MAC.
611 mac_lost_errors Frames received with format errors such that the
614 frame was stripped.
615 mac_tokens Number of tokens received (total of non-restricted
618 and restricted).
619 mac_tvx_expired Number of times that TVX has expired.
622 mac_late Number of TRT expirations since this MAC was reset
625 or a token was received.
626 mac_ring_ops Number of times the ring has entered the
629 ``Ring_Operational'' state from the ``Ring Not
630 Operational'' state.
631
634 /kernel/misc/gld loadable kernel module
635
638 ld(1), kstat(7D), dlpi(7P), attach(9E), gld(9E), open(9E), gld(9F),
639 gld_mac_info(9S), gld_stats(9S), kstat(9S)
640 Writing Device Drivers
643
645 Contrary to the DLPI specification, GLD returns the device's correct
646 address length and broadcast address in DL_INFO_ACK even before the
647 stream has been attached to a PPA.
648 Promiscuous mode may only be entered by streams that are attached to a
651 PPA.
652 The physical address of a PPA may be changed by the superuser while
655 other streams are bound to the same PPA.
656SunOS 5.11 10 Nov 2005 gld(7D)