Driver Entry Points                                    detach(9E)



NAME
     detach - detach or suspend a device

SYNOPSIS
     #include 
     #include 



     int prefix detach(devinfot dip, ddidetachcmdt cmd);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     dip    A pointer to the device's devinfo structure.


     cmd    Type of detach; the driver should return  DIFAILURE
            if  any value other than DIDETACH or DISUSPEND is
            passed to it.


DESCRIPTION
     The detach() function complements the attach(9E) routine.

  DIDETACH
     If cmd is set to DIDETACH, detach() is used to remove  the
     state  associated  with  a  given  instance of a device node
     prior to the removal of that instance from the system.


     The detach() function will be called once for each  instance
     of  the  device  for  which  there  has  been  a  successful
     attach(), once there are no longer any opens on the  device.
     An  attached  instance  of  a  driver  can  be  successfully
     detached only once. The detach() function  should  clean  up
     any  per  instance  data  initialized in attach(9E) and call
     kmemfree(9F) to free any heap allocations. For  information
     on    how    to    unregister    interrupt   handlers,   see
     ddiaddintr(9F).  This  should  also  include  putting  the
     underlying device into a quiescent state so that it will not
     generate interrupts.


     Drivers that set up timeout(9F) routines should ensure  that
     they   are   cancelled  before  returning  DISUCES  from
     detach().






SunOS 5.11           Last change: 7 Dec 2003                    1






Driver Entry Points                                    detach(9E)



     If detach() determines a particular instance of  the  device
     cannot be removed when requested because of some exceptional
     condition, detach() must return DIFAILURE, which  prevents
     the  particular  device  instance  from being detached. This
     also prevents the  driver  from  being  unloaded.  A  driver
     instance failing the detach must ensure that no per instance
     data or state is modified or freed that would compromise the
     system or subsequent driver operation.


     The system guarantees that the function will only be  called
     for  a  particular devinfo node after (and not concurrently
     with) a successful attach(9E) of  that  device.  The  system
     also guarantees that detach() will only be called when there
     are no outstanding open(9E) calls on the device.

  DISUSPEND
     The DISUSPEND cmd is issued  when  the  entire  system  is
     being suspended and power removed from it or when the system
     must be made quiescent. It will be issued  only  to  devices
     which  have  a  reg  property or which export a pm-hardware-
     state property with the value needs-suspend-resume.


     If cmd is set to DISUSPEND, detach() is  used  to  suspend
     all  activity of a device before power is (possibly) removed
     from the device. The steps associated with  suspension  must
     include putting the underlying device into a quiescent state
     so that it will not generate interrupts or modify or  access
     memory.  Once  quiescence has been obtained, detach() can be
     called with outstanding open(9E) requests. It must save  the
     hardware state of the device to memory and block incoming or
     existing requests until attach() is called with DIRESUME.


     If the device is used to  store  file  systems,  then  after
     DISUSPEND   is  issued,  the  device  should  still  honor
     dump(9E) requests  as  this  entry  point  may  be  used  by
     suspend-resume operation (see cpr(7)) to save state file. It
     must do this, however, without disturbing the saved hardware
     state of the device.


     If the device driver uses automatic device Power  Management
     interfaces  (driver  exports pm-components(9P) property), it
     might need to call pmraisepower(9F) if the  current  power
     level  is  lower  than  required  to  complete  the dump(9E)
     request.


     Before returning successfully from a call to detach() with a
     command   of   DISUSPEND,   the  driver  must  cancel  any



SunOS 5.11           Last change: 7 Dec 2003                    2






Driver Entry Points                                    detach(9E)



     outstanding timeouts and make any driver threads quiescent.


     If DIFAILURE is returned for the DISUSPEND  cmd,  either
     the  operation to suspend the system or to make it quiescent
     will be aborted.

RETURN VALUES
     DISUCES    For DIDETACH, the state associated with the
                    given  device  was  successfully removed. For
                    DISUSPEND,  the  driver  was   successfully
                    suspended.


     DIFAILURE    The operation failed or the request  was  not
                    understood.    The    associated   state   is
                    unchanged.


CONTEXT
     This function is called from user context only.

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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Committed                   
    


SEE ALSO
     cpr(7),  pm(7D),  pm(9P),   pm-components(9P),   attach(9E),
     dump(9E),     open(9E),     power(9E),     ddiaddintr(9F),
     ddidevisneeded(9F),   ddimapregs(9F),    kmemfree(9F),
     pmraisepower(9F), timeout(9F)


     Writing Device Drivers












SunOS 5.11           Last change: 7 Dec 2003                    3