Manual Pages for UNIX Operating System command usage for man ddi_get_iblock_cookie

Kernel Functions for Drivers                     ddi_add_intr(9F)



NAME
     ddi_add_intr,   ddi_get_iblock_cookie,   ddi_remove_intr   -
     hardware interrupt handling routines

SYNOPSIS
     #include 
     #include 
     #include 
     #include 



     int ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber,
           ddi_iblock_cookie_t *iblock_cookiep);


     int ddi_add_intr(dev_info_t *dip, uint_t inumber,
          ddi_iblock_cookie_t *iblock_cookiep,
          ddi_idevice_cookie_t *idevice_cookiep,
          uint_t (*int_handler) (caddr_t),
          caddr_t int_handler_arg);


     void ddi_remove_intr(dev_info_t *dip,
          uint_t inumber, ddi_iblock_cookie_t iblock_cookie);


INTERFACE LEVEL
     Solaris DDI specific (Solaris  DDI).  These  interfaces  are
     obsolete.  Use  the  new  interrupt interfaces referenced in
     Intro(9F). Refer to Writing Device Drivers for more informa-
     tion.

PARAMETERS
     For ddi_get_iblock_cookie():

     dip               Pointer to dev_info structure.


     inumber           Interrupt number.


     iblock_cookiep    Pointer to an interrupt block cookie.



     For ddi_add_intr():

     dip                Pointer to dev_info structure.






SunOS 5.11          Last change: 19 Oct 2005                    1






Kernel Functions for Drivers                     ddi_add_intr(9F)



     inumber            Interrupt number.


     iblock_cookiep     Optional pointer to  an  interrupt  block
                        cookie  where  a returned interrupt block
                        cookie is stored.


     idevice_cookiep    Optional pointer to an  interrupt  device
                        cookie  where a returned interrupt device
                        cookie is stored.


     int_handler        Pointer to interrupt handler.


     int_handler_arg    Argument for interrupt handler.



     For ddi_remove_intr():

     dip              Pointer to dev_info structure.


     inumber          Interrupt number.


     iblock_cookie    Block cookie which identifies the interrupt
                      handler to be removed.


DESCRIPTION
  ddi_get_iblock_cookie()
     ddi_get_iblock_cookie() retrieves the interrupt block cookie
     associated  with  a particular interrupt specification. This
     routine should be called before ddi_add_intr()  to  retrieve
     the  interrupt  block  cookie  needed  to  initialize  locks
     (mutex(9F), rwlock(9F)) used by the interrupt  routine.  The
     interrupt  number  inumber  determines  for  which interrupt
     specification to retrieve the cookie. inumber is  associated
     with information provided either by the device (see sbus(4))
     or the hardware configuration file (see  sysbus(4),  isa(4),
     and  driver.conf(4)).  If  only  one interrupt is associated
     with the device, inumber should be 0.


     On a successful return, *iblock_cookiep contains information
     needed  for initializing locks associated with the interrupt
     specification corresponding to inumber  (see  mutex_init(9F)
     and  rw_init(9F)).  The  driver  can  then  initialize locks
     acquired   by   the   interrupt   routine   before   calling



SunOS 5.11          Last change: 19 Oct 2005                    2






Kernel Functions for Drivers                     ddi_add_intr(9F)



     ddi_add_intr()  which  prevents  a  possible  race condition
     where the driver's interrupt handler is  called  immediately
     after  the  driver  has called ddi_add_intr() but before the
     driver has initialized the locks. This may  happen  when  an
     interrupt  for  a different device occurs on the same inter-
     rupt level. If  the  interrupt  routine  acquires  the  lock
     before the lock has been initialized, undefined behavior may
     result.

  ddi_add_intr()
     ddi_add_intr() adds an interrupt handler to the system.  The
     interrupt  number  inumber  determines  which  interrupt the
     handler    will    be    associated    with.    (Refer    to
     ddi_get_iblock_cookie() above.)


     On a successful return, iblock_cookiep contains  information
     used  for  initializing locks associated with this interrupt
     specification (see  mutex_init(9F)  and  rw_init(9F)).  Note
     that  the  interrupt  block cookie is usually obtained using
     ddi_get_iblock_cookie()  to  avoid   the   race   conditions
     described  above  (refer  to ddi_get_iblock_cookie() above).
     For this reason, iblock_cookiep  is  no  longer  useful  and
     should be set to NULL.


     On a successful return, idevice_cookiep contains  a  pointer
     to      a      ddi_idevice_cookie_t      structure      (see
     ddi_idevice_cookie(9S)) containing  information  useful  for
     some   devices   that   have   programmable  interrupts.  If
     idevice_cookiep is set to NULL, no value is returned.


     The routine intr_handler, with its argument int_handler_arg,
     is  called  upon  receipt  of the appropriate interrupt. The
     interrupt handler  should  return  DDI_INTR_CLAIMED  if  the
     interrupt was claimed, DDI_INTR_UNCLAIMED otherwise.


     If successful, ddi_add_intr() returns  DDI_SUCCESS.  If  the
     interrupt information cannot be found on the sun4u architec-
     ture,  either  DDI_INTR_NOTFOUND  or  DDI_FAILURE   can   be
     returned. On i86pc and sun4m architectures, if the interrupt
     information cannot be found, DDI_INTR_NOTFOUND is returned.

  ddi_remove_intr()
     ddi_remove_intr() removes an interrupt handler from the sys-
     tem.  Unloadable  drivers  should  call  this routine during
     their detach(9E) routine to remove their  interrupt  handler
     from the system.





SunOS 5.11          Last change: 19 Oct 2005                    3






Kernel Functions for Drivers                     ddi_add_intr(9F)



     The device interrupt routine for this instance of the device
     will    not   execute   after   ddi_remove_intr()   returns.
     ddi_remove_intr() may need to wait for the device  interrupt
     routine  to  complete  before  returning.  Therefore,  locks
     acquired by the interrupt handler should not be held  across
     the call to ddi_remove_intr() or deadlock may result.

  For All Three Functions:
     For certain bus types, you can call these DDI functions from
     a  high-interrupt  context. These types include ISA and SBus
     buses. See sysbus(4), isa(4), and sbus(4) for details.

RETURN VALUES
     ddi_add_intr() and ddi_get_iblock_cookie() return:

     DDI_SUCCESS          On success.


     DDI_INTR_NOTFOUND    On failure to find the interrupt.


     DDI_FAILURE          On failure.  DDI_FAILURE  can  also  be
                          returned  on  failure to find interrupt
                          (sun4u).


CONTEXT
     ddi_add_intr(),            ddi_remove_intr(),            and
     ddi_get_iblock_cookie()  can  be  called from user or kernel
     context.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Obsolete                    |
    |_____________________________|_____________________________|


SEE ALSO
     driver.conf(4),  isa(4),  sbus(4),  sysbus(4),   attach(9E),
     detach(9E),   ddi_intr_hilevel(9F),   Intro(9F),  mutex(9F),
     mutex_init(9F),           rw_init(9F),           rwlock(9F),
     ddi_idevice_cookie(9S)






SunOS 5.11          Last change: 19 Oct 2005                    4






Kernel Functions for Drivers                     ddi_add_intr(9F)



     Writing Device Drivers

NOTES
     ddi_get_iblock_cookie() must not be called after the  driver
     adds  an  interrupt  handler for the interrupt specification
     corresponding to inumber.


     All consumers of these interfaces,  checking  return  codes,
     should  verify  return_code  !=  DDI_SUCCESS.  Checking  for
     specific failure codes can result in inconsistent  behaviors
     among platforms.

BUGS
     The idevice_cookiep should really point to a data  structure
     that  is  specific  to  the bus architecture that the device
     operates on. Currently the SBus and PCI buses are  supported
     and a single data structure is used to describe both.





































SunOS 5.11          Last change: 19 Oct 2005                    5