gld man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

gld(9E)			      Driver Entry Points		       gld(9E)

NAME
       gld,	gldm_reset,    gldm_start,    gldm_stop,    gldm_set_mac_addr,
       gldm_set_multicast,   gldm_set_promiscuous,    gldm_send,    gldm_intr,
       gldm_get_stats, gldm_ioctl - Generic LAN Driver entry points

SYNOPSIS
       #include <sys/gld.h>

       int prefix_reset(gld_mac_info_t *macinfo);

       int prefix_start(gld_mac_info_t *macinfo);

       int prefix_stop(gld_mac_info_t *
	    macinfo);

       int prefix_set_mac_addr(gld_mac_info_t *
	    macinfo, unsigned char *macaddr);

       int prefix_set_multicast(gld_mac_info_t *
	    macinfo, unsigned char *multicastaddr,
	    int multiflag);

       int prefix_set_promiscuous(gld_mac_info_t *macinfo,
	     int promiscflag);

       int prefix_send(gld_mac_info_t *macinfo,
	    mblk_t *mp);

       uint_t prefix_intr(gld_mac_info_t *macinfo);

       int prefix_get_stats(gld_mac_info_t *macinfo,
	    struct gld_stats *stats);

       int prefix_ioctl(gld_mac_info_t *macinfo,
	    queue_t *q, mblk_t *mp);

INTERFACE LEVEL
       Solaris architecture specific (Solaris DDI).

PARAMETERS
       macinfo		 Pointer to a gld_mac_info(9S) structure.

       macaddr		 Pointer  to  the  beginning of a character array con‐
			 taining a valid MAC address. The array will be of the
			 length	 specified  by	the driver in the gldm_addrlen
			 element of the gld_mac_info(9S) structure.

       multicastaddr	 Pointer to the beginning of a	character  array  con‐
			 taining  a  multicast,	 group, or functional address.
			 The array will be of  the  length  specified  by  the
			 driver	  in   the   gldm_addrlen   element   of   the
			 gld_mac_info(9S) structure.

       multiflag	 A flag indicating whether reception of the  multicast
			 address  is  to be enabled or disabled. This argument
			 is specified as  GLD_MULTI_ENABLE  or	GLD_MULTI_DIS‐
			 ABLE.

       promiscflag	 A  flag  indicating what type of promiscuous mode, if
			 any, is to be enabled. This argument is specified  as
			 GLD_MAC_PROMISC_PHYS,	  GLD_MAC_PROMISC_MULTI,    or
			 GLD_MAC_PROMISC_NONE.

       mp		 Pointer to a STREAMS  message	block  containing  the
			 packet to be transmitted or the ioctl to be executed.

       stats		 Pointer  to a gld_stats(9S) structure to be filled in
			 with the current values of statistics counters.

       q		 Pointer to the queue(9S) structure to be used in  the
			 reply to the ioctl.

DESCRIPTION
       These  entry  points  must  be implemented by a device-specific network
       driver designed to interface with the Generic LAN Driver (GLD).

       As described in gld(7D), the  main  data	 structure  for	 communication
       between	 the   device-specific	driver	and  the  GLD  module  is  the
       gld_mac_info(9S) structure. Some of the elements in that structure  are
       function	 pointers  to the entry points described here. The device-spe‐
       cific driver must, in its attach(9E) routine, initialize these function
       pointers before calling gld_register().

       gldm_reset() resets the hardware to its initial state.

       gldm_start() enables the device to generate interrupts and prepares the
       driver to call gld_recv() for delivering received data packets to GLD.

       gldm_stop() disables the device	from  generating  any  interrupts  and
       stops the driver from calling gld_recv() for delivering data packets to
       GLD. GLD depends on the gldm_stop() routine to ensure that  the	device
       will no longer interrupt, and it must do so without fail.

       gldm_set_mac_addr()  sets  the physical address that the hardware is to
       use for receiving data. This function should program the device to  the
       passed MAC address macaddr.

       gldm_set_multicast()  enables  and  disables  device-level reception of
       specific multicast addresses. If the third argument multiflag is set to
       GLD_MULTI_ENABLE, then the function sets the interface to receive pack‐
       ets with the multicast address pointed to by the	 second	 argument;  if
       multiflag is set to GLD_MULTI_DISABLE, the driver is allowed to disable
       reception of the specified multicast address.

       This function is called whenever GLD wants to enable or disable	recep‐
       tion of a multicast, group, or functional address. GLD makes no assump‐
       tions about how the device does multicast support and calls this	 func‐
       tion  to	 enable	 or disable a specific multicast address. Some devices
       may use a hash algorithm and a bitmask to enable collections of	multi‐
       cast  addresses; this is allowed, and GLD will filter out any superflu‐
       ous packets that are not required. If disabling an address could result
       in  disabling  more  than  one  address	at the device level, it is the
       responsibility of the device driver to  keep  whatever  information  it
       needs  to  avoid disabling an address that GLD has enabled but not dis‐
       abled.

       gldm_set_multicast() will not be called to enable a  particular	multi‐
       cast address that is already enabled, nor to disable an address that is
       not currently enabled. GLD keeps track of  multiple  requests  for  the
       same multicast address and only calls the driver's entry point when the
       first request to enable, or the last request to	disable	 a  particular
       multicast address is made.

       gldm_set_promiscuous()  enables	and  disables  promiscuous  mode. This
       function is called whenever GLD wants to enable or disable  the	recep‐
       tion  of	 all  packets  on  the medium, or all multicast packets on the
       medium. If the second argument promiscflag  is  set  to	the  value  of
       GLD_MAC_PROMISC_PHYS,  then the function enables physical-level promis‐
       cuous mode, resulting in the reception of all packets on the medium. If
       promiscflag is set to GLD_MAC_PROMISC_MULTI, then reception of all mul‐
       ticast  packets	will  be   enabled.   If   promiscflag	 is   set   to
       GLD_MAC_PROMISC_NONE, then promiscuous mode is disabled.

       In  the	case  of a request for promiscuous multicast mode, drivers for
       devices that have no  multicast-only  promiscuous  mode	must  set  the
       device  to physical promiscuous mode to ensure that all multicast pack‐
       ets are received. In this case the routine should  return  GLD_SUCCESS.
       The  GLD	 software will filter out any superfluous packets that are not
       required.

       For forward compatibility, gldm_set_promiscuous() routines should treat
       any   unrecognized   values   for   promiscflag	as  though  they  were
       GLD_MAC_PROMISC_PHYS.

       gldm_send() queues a packet to the device for transmission.  This  rou‐
       tine  is passed a STREAMS message containing the packet to be sent. The
       message may comprise multiple message blocks, and the send routine must
       chain  through  all  the	 message  blocks  in the message to access the
       entire packet to be sent. The driver should be prepared to  handle  and
       skip over any zero-length message continuation blocks in the chain. The
       driver should check to ensure that the packet does not exceed the maxi‐
       mum  allowable  packet  size, and must pad the packet, if necessary, to
       the minimum allowable packet size. If  the  send	 routine  successfully
       transmits or queues the packet, it should return GLD_SUCCESS.

       The send routine should return GLD_NORESOURCES if it cannot immediately
       accept the packet for transmission; in this  case  GLD  will  retry  it
       later. If gldm_send() ever returns GLD_NORESOURCES, the driver must, at
       a later time when resources have become available, call gld_sched()  to
       inform  GLD  that  it  should  retry packets that the driver previously
       failed to queue for transmission. (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.)

       If  the	driver's  send routine returns GLD_SUCCESS, then the driver is
       responsible for freeing the message when the driver and the hardware no
       longer need it. If the send routine copied the message into the device,
       or into a private buffer, then the send routine may  free  the  message
       after  the  copy	 is  made.  If	the hardware uses DMA to read the data
       directly out of the message data blocks, then the driver must not  free
       the  message until the hardware has completed reading the data. In this
       case the driver will probably free the message in  the  interrupt  rou‐
       tine,  or  in  a	 buffer-reclaim operation at the beginning of a future
       send operation.	If  the	 send  routine	returns	 anything  other  than
       GLD_SUCCESS, then the driver must not free the message.

       gldm_intr()  is called when the device might have interrupted. Since it
       is possible to share interrupts with other  devices,  the  driver  must
       check  the  device  status  to  determine whether it actually caused an
       interrupt. If the device that the driver controls  did  not  cause  the
       interrupt,  then this routine must return DDI_INTR_UNCLAIMED. Otherwise
       it must service the interrupt and should	 return	 DDI_INTR_CLAIMED.  If
       the  interrupt  was caused by successful receipt of a packet, this rou‐
       tine should put the received packet into	 a  STREAMS  message  of  type
       M_DATA and pass that message to gld_recv().

       gld_recv()  will	 pass  the  inbound packet upstream to the appropriate
       next layer of the network protocol stack. It is important to  correctly
       set the b_rptr and b_wptr members of the STREAMS message before calling
       gld_recv().

       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.

       The interrupt code should increment statistics counters for any errors.
       This includes failure to allocate a buffer needed for the received data
       and any hardware-specific errors such as CRC errors or framing errors.

       gldm_get_stats() gathers statistics from	 the  hardware	and/or	driver
       private counters, and updates the gld_stats(9S) structure pointed to by
       stats. This routine is called by GLD when it gets a request for statis‐
       tics, and provides the mechanism by which GLD acquires device dependent
       statistics from the driver before composing its reply to the statistics
       request. See gld_stats(9S) and gld(7D) for a description of the defined
       statistics counters.

       gldm_ioctl() implements any device-specific ioctl commands.  This  ele‐
       ment  may  be  specified	 as  NULL if the driver does not implement any
       ioctl functions. The driver is responsible for converting  the  message
       block  into  an ioctl reply message and calling the qreply(9F) function
       before  returning  GLD_SUCCESS.	This  function	should	always	return
       GLD_SUCCESS;  any  errors  the  driver  may  wish  to  report should be
       returned via the message passed to qreply(9F). If the  gldm_ioctl  ele‐
       ment  is	 specified as NULL, GLD will return a message of type M_IOCNAK
       with an error of EINVAL.

RETURN VALUES
       gldm_intr() must return:

       DDI_INTR_CLAIMED	      if and only  if  the  device  definitely	inter‐
			      rupted.

       DDI_INTR_UNCLAIMED     if the device did not interrupt.

       The other functions must return:

       GLD_SUCCESS	    on	success.  gldm_stop()  and gldm_ioctl() should
			    always return this value.

       GLD_NORESOURCES	    if there are insufficient resources to  carry  out
			    the	    request	at     this	time.	  Only
			    gldm_set_mac_addr(),	 gldm_set_multicast(),
			    gldm_set_promiscuous(), and gldm_send() may return
			    this value.

       GLD_NOLINK	    if gldm_send() is called when there is no physical
			    connection to a network or link partner.

       GLD_NOTSUPPORTED	    if	the  requested function is not supported. Only
			    gldm_set_mac_addr(),   gldm_set_multicast(),   and
			    gldm_set_promiscuous() may return this value.

       GLD_BADARG	    if	the  function detected an unsuitable argument,
			    for example, a bad multicast address,  a  bad  MAC
			    address, or a bad packet or packet length.

       GLD_FAILURE	    on hardware failure.

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

       Writing Device Drivers

SunOS 5.11			  3 Jan 2001			       gld(9E)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net