1gld(9E) Driver Entry Points gld(9E)
2
6 gld, gldm_reset, gldm_start, gldm_stop, gldm_set_mac_addr,
7 gldm_set_multicast, gldm_set_promiscuous, gldm_send, gldm_intr,
8 gldm_get_stats, gldm_ioctl - Generic LAN Driver entry points
9
11 #include <sys/gld.h>
12 int prefix_reset(gld_mac_info_t *macinfo);
14 int prefix_start(gld_mac_info_t *macinfo);
17 int prefix_stop(gld_mac_info_t *
20 macinfo);
21 int prefix_set_mac_addr(gld_mac_info_t *
24 macinfo, unsigned char *macaddr);
25 int prefix_set_multicast(gld_mac_info_t *
28 macinfo, unsigned char *multicastaddr,
29 int multiflag);
30 int prefix_set_promiscuous(gld_mac_info_t *macinfo,
33 int promiscflag);
34 int prefix_send(gld_mac_info_t *macinfo,
37 mblk_t *mp);
38 uint_t prefix_intr(gld_mac_info_t *macinfo);
41 int prefix_get_stats(gld_mac_info_t *macinfo,
44 struct gld_stats *stats);
45 int prefix_ioctl(gld_mac_info_t *macinfo,
48 queue_t *q, mblk_t *mp);
49
52 Solaris architecture specific (Solaris DDI).
53
55 macinfo Pointer to a gld_mac_info(9S) structure.
56 macaddr Pointer to the beginning of a character array con‐
59 taining a valid MAC address. The array will be of the
60 length specified by the driver in the gldm_addrlen
61 element of the gld_mac_info(9S) structure.
62 multicastaddr Pointer to the beginning of a character array con‐
65 taining a multicast, group, or functional address.
66 The array will be of the length specified by the
67 driver in the gldm_addrlen element of the
68 gld_mac_info(9S) structure.
69 multiflag A flag indicating whether reception of the multicast
72 address is to be enabled or disabled. This argument
73 is specified as GLD_MULTI_ENABLE or GLD_MULTI_DIS‐
74 ABLE.
75 promiscflag A flag indicating what type of promiscuous mode, if
78 any, is to be enabled. This argument is specified as
79 GLD_MAC_PROMISC_PHYS, GLD_MAC_PROMISC_MULTI, or
80 GLD_MAC_PROMISC_NONE.
81 mp Pointer to a STREAMS message block containing the
84 packet to be transmitted or the ioctl to be executed.
85 stats Pointer to a gld_stats(9S) structure to be filled in
88 with the current values of statistics counters.
89 q Pointer to the queue(9S) structure to be used in the
92 reply to the ioctl.
93
96 These entry points must be implemented by a device-specific network
97 driver designed to interface with the Generic LAN Driver (GLD).
98 As described in gld(7D), the main data structure for communication
101 between the device-specific driver and the GLD module is the
102 gld_mac_info(9S) structure. Some of the elements in that structure are
103 function pointers to the entry points described here. The device-spe‐
104 cific driver must, in its attach(9E) routine, initialize these function
105 pointers before calling gld_register().
106 gldm_reset() resets the hardware to its initial state.
109 gldm_start() enables the device to generate interrupts and prepares the
112 driver to call gld_recv() for delivering received data packets to GLD.
113 gldm_stop() disables the device from generating any interrupts and
116 stops the driver from calling gld_recv() for delivering data packets to
117 GLD. GLD depends on the gldm_stop() routine to ensure that the device
118 will no longer interrupt, and it must do so without fail.
119 gldm_set_mac_addr() sets the physical address that the hardware is to
122 use for receiving data. This function should program the device to the
123 passed MAC address macaddr.
124 gldm_set_multicast() enables and disables device-level reception of
127 specific multicast addresses. If the third argument multiflag is set to
128 GLD_MULTI_ENABLE, then the function sets the interface to receive pack‐
129 ets with the multicast address pointed to by the second argument; if
130 multiflag is set to GLD_MULTI_DISABLE, the driver is allowed to disable
131 reception of the specified multicast address.
132 This function is called whenever GLD wants to enable or disable recep‐
135 tion of a multicast, group, or functional address. GLD makes no assump‐
136 tions about how the device does multicast support and calls this func‐
137 tion to enable or disable a specific multicast address. Some devices
138 may use a hash algorithm and a bitmask to enable collections of multi‐
139 cast addresses; this is allowed, and GLD will filter out any superflu‐
140 ous packets that are not required. If disabling an address could result
141 in disabling more than one address at the device level, it is the
142 responsibility of the device driver to keep whatever information it
143 needs to avoid disabling an address that GLD has enabled but not dis‐
144 abled.
145 gldm_set_multicast() will not be called to enable a particular multi‐
148 cast address that is already enabled, nor to disable an address that is
149 not currently enabled. GLD keeps track of multiple requests for the
150 same multicast address and only calls the driver's entry point when the
151 first request to enable, or the last request to disable a particular
152 multicast address is made.
153 gldm_set_promiscuous() enables and disables promiscuous mode. This
156 function is called whenever GLD wants to enable or disable the recep‐
157 tion of all packets on the medium, or all multicast packets on the
158 medium. If the second argument promiscflag is set to the value of
159 GLD_MAC_PROMISC_PHYS, then the function enables physical-level promis‐
160 cuous mode, resulting in the reception of all packets on the medium. If
161 promiscflag is set to GLD_MAC_PROMISC_MULTI, then reception of all mul‐
162 ticast packets will be enabled. If promiscflag is set to
163 GLD_MAC_PROMISC_NONE, then promiscuous mode is disabled.
164 In the case of a request for promiscuous multicast mode, drivers for
167 devices that have no multicast-only promiscuous mode must set the
168 device to physical promiscuous mode to ensure that all multicast pack‐
169 ets are received. In this case the routine should return GLD_SUCCESS.
170 The GLD software will filter out any superfluous packets that are not
171 required.
172 For forward compatibility, gldm_set_promiscuous() routines should treat
175 any unrecognized values for promiscflag as though they were
176 GLD_MAC_PROMISC_PHYS.
177 gldm_send() queues a packet to the device for transmission. This rou‐
180 tine is passed a STREAMS message containing the packet to be sent. The
181 message may comprise multiple message blocks, and the send routine must
182 chain through all the message blocks in the message to access the
183 entire packet to be sent. The driver should be prepared to handle and
184 skip over any zero-length message continuation blocks in the chain. The
185 driver should check to ensure that the packet does not exceed the maxi‐
186 mum allowable packet size, and must pad the packet, if necessary, to
187 the minimum allowable packet size. If the send routine successfully
188 transmits or queues the packet, it should return GLD_SUCCESS.
189 The send routine should return GLD_NORESOURCES if it cannot immediately
192 accept the packet for transmission; in this case GLD will retry it
193 later. If gldm_send() ever returns GLD_NORESOURCES, the driver must, at
194 a later time when resources have become available, call gld_sched() to
195 inform GLD that it should retry packets that the driver previously
196 failed to queue for transmission. (If the driver's gldm_stop() routine
197 is called, the driver is absolved from this obligation until it later
198 again returns GLD_NORESOURCES from its gldm_send() routine; however,
199 extra calls to gld_sched() will not cause incorrect operation.)
200 If the driver's send routine returns GLD_SUCCESS, then the driver is
203 responsible for freeing the message when the driver and the hardware no
204 longer need it. If the send routine copied the message into the device,
205 or into a private buffer, then the send routine may free the message
206 after the copy is made. If the hardware uses DMA to read the data
207 directly out of the message data blocks, then the driver must not free
208 the message until the hardware has completed reading the data. In this
209 case the driver will probably free the message in the interrupt rou‐
210 tine, or in a buffer-reclaim operation at the beginning of a future
211 send operation. If the send routine returns anything other than
212 GLD_SUCCESS, then the driver must not free the message.
213 gldm_intr() is called when the device might have interrupted. Since it
216 is possible to share interrupts with other devices, the driver must
217 check the device status to determine whether it actually caused an
218 interrupt. If the device that the driver controls did not cause the
219 interrupt, then this routine must return DDI_INTR_UNCLAIMED. Otherwise
220 it must service the interrupt and should return DDI_INTR_CLAIMED. If
221 the interrupt was caused by successful receipt of a packet, this rou‐
222 tine should put the received packet into a STREAMS message of type
223 M_DATA and pass that message to gld_recv().
224 gld_recv() will pass the inbound packet upstream to the appropriate
227 next layer of the network protocol stack. It is important to correctly
228 set the b_rptr and b_wptr members of the STREAMS message before calling
229 gld_recv().
230 The driver should avoid holding mutex or other locks during the call to
233 gld_recv(). In particular, locks that could be taken by a transmit
234 thread may not be held during a call to gld_recv(): the interrupt
235 thread that calls gld_recv() may in some cases carry out processing
236 that includes sending an outgoing packet, resulting in a call to the
237 driver's gldm_send() routine. If the gldm_send() routine were to try to
238 acquire a mutex being held by the gldm_intr() routine at the time it
239 calls gld_recv(), this could result in a panic due to recursive mutex
240 entry.
241 The interrupt code should increment statistics counters for any errors.
244 This includes failure to allocate a buffer needed for the received data
245 and any hardware-specific errors such as CRC errors or framing errors.
246 gldm_get_stats() gathers statistics from the hardware and/or driver
249 private counters, and updates the gld_stats(9S) structure pointed to by
250 stats. This routine is called by GLD when it gets a request for statis‐
251 tics, and provides the mechanism by which GLD acquires device dependent
252 statistics from the driver before composing its reply to the statistics
253 request. See gld_stats(9S) and gld(7D) for a description of the defined
254 statistics counters.
255 gldm_ioctl() implements any device-specific ioctl commands. This ele‐
258 ment may be specified as NULL if the driver does not implement any
259 ioctl functions. The driver is responsible for converting the message
260 block into an ioctl reply message and calling the qreply(9F) function
261 before returning GLD_SUCCESS. This function should always return
262 GLD_SUCCESS; any errors the driver may wish to report should be
263 returned via the message passed to qreply(9F). If the gldm_ioctl ele‐
264 ment is specified as NULL, GLD will return a message of type M_IOCNAK
265 with an error of EINVAL.
266
268 gldm_intr() must return:
269 DDI_INTR_CLAIMED if and only if the device definitely inter‐
271 rupted.
272 DDI_INTR_UNCLAIMED if the device did not interrupt.
275 The other functions must return:
279 GLD_SUCCESS on success. gldm_stop() and gldm_ioctl() should
281 always return this value.
282 GLD_NORESOURCES if there are insufficient resources to carry out
285 the request at this time. Only
286 gldm_set_mac_addr(), gldm_set_multicast(),
287 gldm_set_promiscuous(), and gldm_send() may return
288 this value.
289 GLD_NOLINK if gldm_send() is called when there is no physical
292 connection to a network or link partner.
293 GLD_NOTSUPPORTED if the requested function is not supported. Only
296 gldm_set_mac_addr(), gldm_set_multicast(), and
297 gldm_set_promiscuous() may return this value.
298 GLD_BADARG if the function detected an unsuitable argument,
301 for example, a bad multicast address, a bad MAC
302 address, or a bad packet or packet length.
303 GLD_FAILURE on hardware failure.
306
309 gld(7D), gld(9F), gld_mac_info(9S), gld_stats(9S), dlpi(7P),
310 attach(9E), ddi_add_intr(9F)
311 Writing Device Drivers
314SunOS 5.11 3 Jan 2001 gld(9E)