1gld(9E)                       Driver Entry Points                      gld(9E)
2
3
4

NAME

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

SYNOPSIS

11       #include <sys/gld.h>
12
13       int prefix_reset(gld_mac_info_t *macinfo);
14
15
16       int prefix_start(gld_mac_info_t *macinfo);
17
18
19       int prefix_stop(gld_mac_info_t *
20            macinfo);
21
22
23       int prefix_set_mac_addr(gld_mac_info_t *
24            macinfo, unsigned char *macaddr);
25
26
27       int prefix_set_multicast(gld_mac_info_t *
28            macinfo, unsigned char *multicastaddr,
29            int multiflag);
30
31
32       int prefix_set_promiscuous(gld_mac_info_t *macinfo,
33             int promiscflag);
34
35
36       int prefix_send(gld_mac_info_t *macinfo,
37            mblk_t *mp);
38
39
40       uint_t prefix_intr(gld_mac_info_t *macinfo);
41
42
43       int prefix_get_stats(gld_mac_info_t *macinfo,
44            struct gld_stats *stats);
45
46
47       int prefix_ioctl(gld_mac_info_t *macinfo,
48            queue_t *q, mblk_t *mp);
49
50

INTERFACE LEVEL

52       Solaris architecture specific (Solaris DDI).
53

PARAMETERS

55       macinfo           Pointer to a gld_mac_info(9S) structure.
56
57
58       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
63
64       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
70
71       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
76
77       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
82
83       mp                Pointer to a STREAMS  message  block  containing  the
84                         packet to be transmitted or the ioctl to be executed.
85
86
87       stats             Pointer  to a gld_stats(9S) structure to be filled in
88                         with the current values of statistics counters.
89
90
91       q                 Pointer to the queue(9S) structure to be used in  the
92                         reply to the ioctl.
93
94

DESCRIPTION

96       These  entry  points  must  be implemented by a device-specific network
97       driver designed to interface with the Generic LAN Driver (GLD).
98
99
100       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
107
108       gldm_reset() resets the hardware to its initial state.
109
110
111       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
114
115       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
120
121       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
125
126       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
133
134       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
146
147       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
154
155       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
165
166       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
173
174       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
178
179       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
190
191       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
201
202       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
214
215       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
225
226       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
231
232       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
242
243       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
247
248       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
256
257       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

RETURN VALUES

268       gldm_intr() must return:
269
270       DDI_INTR_CLAIMED       if and only  if  the  device  definitely  inter‐
271                              rupted.
272
273
274       DDI_INTR_UNCLAIMED     if the device did not interrupt.
275
276
277
278       The other functions must return:
279
280       GLD_SUCCESS          on  success.  gldm_stop()  and gldm_ioctl() should
281                            always return this value.
282
283
284       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
290
291       GLD_NOLINK           if gldm_send() is called when there is no physical
292                            connection to a network or link partner.
293
294
295       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
299
300       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
304
305       GLD_FAILURE          on hardware failure.
306
307

SEE ALSO

309       gld(7D),    gld(9F),    gld_mac_info(9S),    gld_stats(9S),   dlpi(7P),
310       attach(9E), ddi_add_intr(9F)
311
312
313       Writing Device Drivers
314
315
316
317SunOS 5.11                        3 Jan 2001                           gld(9E)
Impressum