1gld(9F)                  Kernel Functions for Drivers                  gld(9F)
2
3
4

NAME

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

SYNOPSIS

10       #include <sys/gld.h>
11
12       gld_mac_info_t *gld_mac_alloc(dev_info_t *dip);
13
14
15       void gld_mac_free(gld_mac_info_t *macinfo);
16
17
18       int gld_register(dev_info_t *dip, char *name, gld_mac_info_t *macinfo);
19
20
21       int gld_unregister(gld_mac_info_t *macinfo);
22
23
24       void gld_recv(gld_mac_info_t *macinfo, mblk_t *mp);
25
26
27       void gld_sched(gld_mac_info_t *macinfo);
28
29
30       uint_t gld_intr(caddr_t);
31
32
33       void gld_linkstate(gld_mac_info_t *macinfo, int32_t newstate);
34
35

INTERFACE LEVEL

37       Solaris architecture specific (Solaris DDI).
38

PARAMETERS

40       macinfo      Pointer to a gld_mac_info(9S) structure.
41
42
43       dip          Pointer to dev_info structure.
44
45
46       name         Device interface name.
47
48
49       mp           Pointer to a message block containing a received packet.
50
51
52       newstate     Media link state.
53
54

DESCRIPTION

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
63
64       gld_mac_free()  frees a gld_mac_info(9S) structure previously allocated
65       by gld_mac_alloc().
66
67
68       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
76           o      links the device-specific driver with the GLD system;
77
78           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
82           o      creates the minor device node.
83
84
85       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
88
89       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
94
95       gld_unregister() is called by the device driver's detach(9E)  function,
96       and if successful, performs the following tasks:
97
98           o      ensures  the  device's  interrupts  are stopped, calling the
99                  driver's gldm_stop() routine if necessary;
100
101           o      removes the minor device node;
102
103           o      unlinks the device-specific driver from the GLD system.
104
105
106       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
113
114       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
121
122       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
132
133       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
145
146       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
157
158       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
162       GLD_LINKSTATE_DOWN        The media link is unavailable.
163
164
165       GLD_LINKSTATE_UP          The media link is unavailable.
166
167
168       GLD_LINKSTATE_UNKNOWN     The status of the media link is unknown.
169
170
171
172       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

RETURN VALUES

177       gld_mac_alloc() returns a pointer to a new gld_mac_info(9S) structure.
178
179
180       gld_register() and gld_unregister() return:
181
182       DDI_SUCCESS     on success.
183
184
185       DDI_FAILURE     on failure.
186
187
188
189       gld_intr() returns a value appropriate for an interrupt handler.
190

SEE ALSO

192       gld(7D),    gld(9E),    gld_mac_info(9S),    gld_stats(9S),   dlpi(7P),
193       attach(9E), ddi_add_intr(9F).
194
195
196       Writing Device Drivers
197
198
199
200SunOS 5.11                        28 Aug 2003                          gld(9F)
Impressum