gld(9F)




NAME

     gld,     gld_mac_alloc,     gld_mac_free,      gld_register,
     gld_unregister,  gld_recv, gld_sched, gld_intr - Generic LAN
     Driver service routines


SYNOPSIS

     #include <sys/gld.h>

     gld_mac_info_t *gld_mac_alloc(dev_info_t *dip);

     void gld_mac_free(gld_mac_info_t *macinfo);

     int gld_register(dev_info_t *dip, char *name, gld_mac_info_t
     *macinfo);

     int gld_unregister(gld_mac_info_t *macinfo);

     void gld_recv(gld_mac_info_t *macinfo, mblk_t *mp);

     void gld_sched(gld_mac_info_t *macinfo);

     uint_t gld_intr(caddr_t);


INTERFACE LEVEL

     Solaris architecture specific (Solaris DDI).


PARAMETERS

     macinfo
           Pointer to a gld_mac_info(9S) structure.

     dip   Pointer to dev_info structure.

     name  Device interface name.

     mp    Pointer to  a  message  block  containing  a  received
           packet.


DESCRIPTION

     gld_mac_alloc() allocates a new  gld_mac_info(9S)  structure
     and  returns  a  pointer to it. Some of the GLD-private ele-
     ments  of  the   structure   may   be   initialized   before
     gld_mac_alloc()  returns; all other elements are initialized
     to zero. The device driver must  initialize  some  structure
     members,  as  described  in gld_mac_info(9S), before passing
     the mac_info pointer to gld_register().

     gld_mac_free() frees a gld_mac_info(9S) structure previously
     allocated by gld_mac_alloc().

     gld_register() 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  gld_register()  the
     device   driver's   attach(9E)   routine   must   first  use
     gld_mac_alloc() to allocate  a  gld_mac_info(9S)  structure,
     and  initialize  several  of  its  structure  elements.  See
     gld_mac_info(9S) for more information. A successful call  to
     gld_register() performs the following actions:

        o  links the device-specific driver with the GLD system;

        o  sets the device-specific driver's private data pointer
           (using  ddi_set_driver_private(9F))  to  point  to the
           macinfo structure;

        o  creates the minor device node.

     The device interface  name  passed  to  gld_register()  must
     exactly  match the name of the driver module as it exists in
     the filesystem.

     The driver's attach(9E) routine should return DDI_SUCCESS if
     gld_register()    succeeds.    If   gld_register()   returns
     DDI_FAILURE, the attach(9E) routine  should  deallocate  any
     resources  it  allocated  before  calling gld_register() and
     then also return DDI_FAILURE.

     gld_unregister() 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,  calling
           the driver's gldm_stop() routine if necessary;

        o  removes the minor device node;

        o  unlinks the device-specific driver from the  GLD  sys-
           tem.

     If gld_unregister() returns DDI_SUCCESS, the detach(9E) rou-
     tine  should deallocate any data structures allocated in the
     attach(9E) routine, using gld_mac_free() to  deallocate  the
     macinfo    structure,    and    return    DDI_SUCCESS.    If
     gld_unregister()   returns   DDI_FAILURE,    the    driver's
     detach(9E)  routine  must  leave  the device operational and
     return DDI_FAILURE.

     gld_recv() is called by the driver's  interrupt  handler  to
     pass  a  received packet upstream. The driver must construct
     and pass a STREAMS M_DATA message containing the raw packet.
     gld_recv()  determines  which STREAMS queues, if any, should
     receive a copy of the packet, duplicating it  if  necessary.
     It  then formats a DL_UNITDATA_IND message, if required, and
     passes the data up all appropriate streams.

     The driver should avoid holding mutex or other locks  during
     the  call  to gld_recv(). In particular, locks that could be
     taken by a transmit thread may not be held during a call  to
     gld_recv():  the  interrupt thread that calls gld_recv() may
     in some cases carry out processing that includes sending  an
     outgoing  packet,  resulting  in  a  call  to  the  driver's
     gldm_send() routine. If the gldm_send() routine were to  try
     to  acquire a mutex being held by the gldm_intr() routine at
     the time it calls gld_recv(), this could result in  a  panic
     due to recursive mutex entry.

     gld_sched() is called by the  device  driver  to  reschedule
     stalled  outbound packets. Whenever the driver's gldm_send()
     routine has returned GLD_NORESOURCES, the driver must  later
     call  gld_sched() to inform the GLD framework that it should
     retry  the  packets  that  previously  could  not  be  sent.
     gld_sched()  should  be  called  as  soon  as possible after
     resources are again available, to ensure  that  GLD  resumes
     passing outbound packets to the driver's gldm_send() routine
     in a timely way. (If the  driver's  gldm_stop()  routine  is
     called, the driver is absolved from this obligation until it
     later again returns  GLD_NORESOURCES  from  its  gldm_send()
     routine;  however, extra calls to gld_sched() will not cause
     incorrect operation.)

     gld_intr() is GLD's main interrupt handler. Normally  it  is
     specified  as  the  interrupt routine in the device driver's
     call to ddi_add_intr(9F).  The  argument  to  the  interrupt
     handler   (specified  as  int_handler_arg  in  the  call  to
     ddi_add_intr(9F)) must be a pointer to the  gld_mac_info(9S)
     structure.  gld_intr() will, when appropriate, call the dev-
     ice driver's gldm_intr() function, passing that  pointer  to
     the  gld_mac_info(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, gld_intr() may be specified as the  soft
     interrupt handler in the call to ddi_add_softintr().


RETURN VALUES

     gld_mac_alloc() returns a pointer to a new  gld_mac_info(9S)
     structure.

     gld_register() and gld_unregister() return:

     DDI_SUCCESS
           on success.

     DDI_FAILURE
           on failure.

     gld_intr() returns a  value  appropriate  for  an  interrupt
     handler.


SEE ALSO

     gld(7D), gld(9E), gld_mac_info(9S), gld_stats(9S), dlpi(7P),
     attach(9E), ddi_add_intr(9F).

     Writing Device Drivers


Man(1) output converted with man2html