1gld(9F) Kernel Functions for Drivers gld(9F)
2
6 gld, gld_mac_alloc, gld_mac_free, gld_register, gld_unregister,
7 gld_recv, gld_sched, gld_intr - Generic LAN Driver service routines
8
10 #include <sys/gld.h>
11 gld_mac_info_t *gld_mac_alloc(dev_info_t *dip);
13 void gld_mac_free(gld_mac_info_t *macinfo);
16 int gld_register(dev_info_t *dip, char *name, gld_mac_info_t *macinfo);
19 int gld_unregister(gld_mac_info_t *macinfo);
22 void gld_recv(gld_mac_info_t *macinfo, mblk_t *mp);
25 void gld_sched(gld_mac_info_t *macinfo);
28 uint_t gld_intr(caddr_t);
31 void gld_linkstate(gld_mac_info_t *macinfo, int32_t newstate);
34
37 Solaris architecture specific (Solaris DDI).
38
40 macinfo Pointer to a gld_mac_info(9S) structure.
41 dip Pointer to dev_info structure.
44 name Device interface name.
47 mp Pointer to a message block containing a received packet.
50 newstate Media link state.
53
56 gld_mac_alloc() allocates a new gld_mac_info(9S) structure and returns
57 a pointer to it. Some of the GLD-private elements of the structure may
58 be initialized before gld_mac_alloc() returns; all other elements are
59 initialized to zero. The device driver must initialize some structure
60 members, as described in gld_mac_info(9S), before passing the mac_info
61 pointer to gld_register().
62 gld_mac_free() frees a gld_mac_info(9S) structure previously allocated
65 by gld_mac_alloc().
66 gld_register() is called from the device driver's attach(9E) routine,
69 and is used to link the GLD-based device driver with the GLD framework.
70 Before calling gld_register() the device driver's attach(9E) routine
71 must first use gld_mac_alloc() to allocate a gld_mac_info(9S) struc‐
72 ture, and initialize several of its structure elements. See
73 gld_mac_info(9S) for more information. A successful call to gld_regis‐
74 ter() performs the following actions:
75 o links the device-specific driver with the GLD system;
77 o sets the device-specific driver's private data pointer
79 (using ddi_set_driver_private(9F)) to point to the macinfo
80 structure;
81 o creates the minor device node.
83 The device interface name passed to gld_register() must exactly match
86 the name of the driver module as it exists in the filesystem.
87 The driver's attach(9E) routine should return DDI_SUCCESS if gld_regis‐
90 ter() succeeds. If gld_register() returns DDI_FAILURE, the attach(9E)
91 routine should deallocate any resources it allocated before calling
92 gld_register() and then also return DDI_FAILURE.
93 gld_unregister() is called by the device driver's detach(9E) function,
96 and if successful, performs the following tasks:
97 o ensures the device's interrupts are stopped, calling the
99 driver's gldm_stop() routine if necessary;
100 o removes the minor device node;
102 o unlinks the device-specific driver from the GLD system.
104 If gld_unregister() returns DDI_SUCCESS, the detach(9E) routine should
107 deallocate any data structures allocated in the attach(9E) routine,
108 using gld_mac_free() to deallocate the macinfo structure, and return
109 DDI_SUCCESS. If gld_unregister() returns DDI_FAILURE, the driver's
110 detach(9E) routine must leave the device operational and return
111 DDI_FAILURE.
112 gld_recv() is called by the driver's interrupt handler to pass a
115 received packet upstream. The driver must construct and pass a STREAMS
116 M_DATA message containing the raw packet. gld_recv() determines which
117 STREAMS queues, if any, should receive a copy of the packet, duplicat‐
118 ing it if necessary. It then formats a DL_UNITDATA_IND message, if
119 required, and passes the data up all appropriate streams.
120 The driver should avoid holding mutex or other locks during the call to
123 gld_recv(). In particular, locks that could be taken by a transmit
124 thread may not be held during a call to gld_recv(): the interrupt
125 thread that calls gld_recv() may in some cases carry out processing
126 that includes sending an outgoing packet, resulting in a call to the
127 driver's gldm_send() routine. If the gldm_send() routine were to try to
128 acquire a mutex being held by the gldm_intr() routine at the time it
129 calls gld_recv(), this could result in a panic due to recursive mutex
130 entry.
131 gld_sched() is called by the device driver to reschedule stalled out‐
134 bound packets. Whenever the driver's gldm_send() routine has returned
135 GLD_NORESOURCES, the driver must later call gld_sched() to inform the
136 GLD framework that it should retry the packets that previously could
137 not be sent. gld_sched() should be called as soon as possible after
138 resources are again available, to ensure that GLD resumes passing out‐
139 bound packets to the driver's gldm_send() routine in a timely way. (If
140 the driver's gldm_stop() routine is called, the driver is absolved from
141 this obligation until it later again returns GLD_NORESOURCES from its
142 gldm_send() routine; however, extra calls to gld_sched() will not cause
143 incorrect operation.)
144 gld_intr() is GLD's main interrupt handler. Normally it is specified as
147 the interrupt routine in the device driver's call to ddi_add_intr(9F).
148 The argument to the interrupt handler (specified as int_handler_arg in
149 the call to ddi_add_intr(9F)) must be a pointer to the gld_mac_info(9S)
150 structure. gld_intr() will, when appropriate, call the device driver's
151 gldm_intr() function, passing that pointer to the gld_mac_info(9S)
152 structure. However, if the driver uses a high-level interrupt, it must
153 provide its own high-level interrupt handler, and trigger a soft inter‐
154 rupt from within that. In this case, gld_intr() may be specified as the
155 soft interrupt handler in the call to ddi_add_softintr().
156 gld_linkstate() is called by the device driver to notify GLD of changes
159 in the media link state. The newstate argument should be set to one of
160 the following:
161 GLD_LINKSTATE_DOWN The media link is unavailable.
163 GLD_LINKSTATE_UP The media link is unavailable.
166 GLD_LINKSTATE_UNKNOWN The status of the media link is unknown.
169 If a driver calls gld_linkstate(), it must also set the
173 GLD_CAP_LINKSTATE bit in the gldm_capabilties field of the
174 gld_mac_info(9S) structure.
175
177 gld_mac_alloc() returns a pointer to a new gld_mac_info(9S) structure.
178 gld_register() and gld_unregister() return:
181 DDI_SUCCESS on success.
183 DDI_FAILURE on failure.
186 gld_intr() returns a value appropriate for an interrupt handler.
190
192 gld(7D), gld(9E), gld_mac_info(9S), gld_stats(9S), dlpi(7P),
193 attach(9E), ddi_add_intr(9F).
194 Writing Device Drivers
197SunOS 5.11 28 Aug 2003 gld(9F)