Kernel Functions for Drivers gld(9F)
NAME
gld, gldmacalloc, gldmacfree, gldregister,
gldunregister, gldrecv, gldsched, gldintr - Generic LAN
Driver service routines
SYNOPSIS
#include
gldmacinfot *gldmacalloc(devinfot *dip);
void gldmacfree(gldmacinfot *macinfo);
int gldregister(devinfot *dip, char *name, gldmacinfot *macinfo);
int gldunregister(gldmacinfot *macinfo);
void gldrecv(gldmacinfot *macinfo, mblkt *mp);
void gldsched(gldmacinfot *macinfo);
uintt gldintr(caddrt);
void gldlinkstate(gldmacinfot *macinfo, int32t newstate);
INTERFACE LEVEL
Solaris architecture specific (Solaris DI).
PARAMETERS
macinfo Pointer to a gldmacinfo(9S) structure.
dip Pointer to devinfo structure.
name Device interface name.
mp Pointer to a message block containing a
received packet.
newstate Media link state.
SunOS 5.11 Last change: 28 Aug 2003 1
Kernel Functions for Drivers gld(9F)
DESCRIPTION
gldmacalloc() allocates a new gldmacinfo(9S) structure
and returns a pointer to it. Some of the GLD-private ele-
ments of the structure may be initialized before
gldmacalloc() returns; all other elements are initialized
to zero. The device driver must initialize some structure
members, as described in gldmacinfo(9S), before passing
the macinfo pointer to gldregister().
gldmacfree() frees a gldmacinfo(9S) structure previously
allocated by gldmacalloc().
gldregister() is called from the device driver's attach(9E)
routine, and is used to link the GLD-based device driver
with the GLD framework. Before calling gldregister() the
device driver's attach(9E) routine must first use
gldmacalloc() to allocate a gldmacinfo(9S) structure,
and initialize several of its structure elements. See
gldmacinfo(9S) for more information. A successful call to
gldregister() performs the following actions:
o links the device-specific driver with the GLD sys-
tem;
o sets the device-specific driver's private data
pointer (using ddisetdriverprivate(9F)) to point
to the macinfo structure;
o creates the minor device node.
The device interface name passed to gldregister() must
exactly match the name of the driver module as it exists in
the filesystem.
The driver's attach(9E) routine should return DISUCES if
gldregister() succeeds. If gldregister() returns
DIFAILURE, the attach(9E) routine should deallocate any
resources it allocated before calling gldregister() and
then also return DIFAILURE.
gldunregister() is called by the device driver's detach(9E)
function, and if successful, performs the following tasks:
o ensures the device's interrupts are stopped, cal-
ling the driver's gldmstop() routine if necessary;
o removes the minor device node;
SunOS 5.11 Last change: 28 Aug 2003 2
Kernel Functions for Drivers gld(9F)
o unlinks the device-specific driver from the GLD
system.
If gldunregister() returns DISUCES, the detach(9E) rou-
tine should deallocate any data structures allocated in the
attach(9E) routine, using gldmacfree() to deallocate the
macinfo structure, and return DISUCES. If
gldunregister() returns DIFAILURE, the driver's
detach(9E) routine must leave the device operational and
return DIFAILURE.
gldrecv() is called by the driver's interrupt handler to
pass a received packet upstream. The driver must construct
and pass a STREAMS MDATA message containing the raw packet.
gldrecv() determines which STREAMS queues, if any, should
receive a copy of the packet, duplicating it if necessary.
It then formats a DLUNITDATAIND message, if required, and
passes the data up all appropriate streams.
The driver should avoid holding mutex or other locks during
the call to gldrecv(). In particular, locks that could be
taken by a transmit thread may not be held during a call to
gldrecv(): the interrupt thread that calls gldrecv() may
in some cases carry out processing that includes sending an
outgoing packet, resulting in a call to the driver's
gldmsend() routine. If the gldmsend() routine were to try
to acquire a mutex being held by the gldmintr() routine at
the time it calls gldrecv(), this could result in a panic
due to recursive mutex entry.
gldsched() is called by the device driver to reschedule
stalled outbound packets. Whenever the driver's gldmsend()
routine has returned GLDNORESOURCES, the driver must later
call gldsched() to inform the GLD framework that it should
retry the packets that previously could not be sent.
gldsched() should be called as soon as possible after
resources are again available, to ensure that GLD resumes
passing outbound packets to the driver's gldmsend() routine
in a timely way. (If the driver's gldmstop() routine is
called, the driver is absolved from this obligation until it
later again returns GLDNORESOURCES from its gldmsend()
routine; however, extra calls to gldsched() will not cause
incorrect operation.)
gldintr() is GLD's main interrupt handler. Normally it is
specified as the interrupt routine in the device driver's
call to ddiaddintr(9F). The argument to the interrupt
SunOS 5.11 Last change: 28 Aug 2003 3
Kernel Functions for Drivers gld(9F)
handler (specified as inthandlerarg in the call to
ddiaddintr(9F)) must be a pointer to the gldmacinfo(9S)
structure. gldintr() will, when appropriate, call the dev-
ice driver's gldmintr() function, passing that pointer to
the gldmacinfo(9S) structure. However, if the driver uses
a high-level interrupt, it must provide its own high-level
interrupt handler, and trigger a soft interrupt from within
that. In this case, gldintr() may be specified as the soft
interrupt handler in the call to ddiaddsoftintr().
gldlinkstate() is called by the device driver to notify GLD
of changes in the media link state. The newstate argument
should be set to one of the following:
GLDLINKSTATEDOWN The media link is unavailable.
GLDLINKSTATEUP The media link is unavailable.
GLDLINKSTATEUNKNOWN The status of the media link is
unknown.
If a driver calls gldlinkstate(), it must also set the
GLDCAPLINKSTATE bit in the gldmcapabilties field of the
gldmacinfo(9S) structure.
RETURN VALUES
gldmacalloc() returns a pointer to a new gldmacinfo(9S)
structure.
gldregister() and gldunregister() return:
DISUCES on success.
DIFAILURE on failure.
gldintr() returns a value appropriate for an interrupt
handler.
SEE ALSO
gld(7D), gld(9E), gldmacinfo(9S), gldstats(9S), dlpi(7P),
attach(9E), ddiaddintr(9F).
SunOS 5.11 Last change: 28 Aug 2003 4
Kernel Functions for Drivers gld(9F)
Writing Device Drivers
SunOS 5.11 Last change: 28 Aug 2003 5
|
