Driver Entry Points                                    attach(9E)



NAME
     attach - Attach a device to the system, or resume it

SYNOPSIS
     #include 
     #include 



     int prefixattach(devinfot *dip, ddiattachcmdt cmd);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

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


     cmd    Attach  type.  Possible  values  are  DIATACH  and
            DIRESUME.  Other  values  are  reserved. The driver
            must return DIFAILURE if reserved values are passed
            to it.


DESCRIPTION
     The attach(9E) function is the  device-specific  initializa-
     tion  entry  point. This entry point is required and must be
     written.

  DIATACH
     The DIATACH command must be provided  in  the  attach(9E)
     entry point. DIATACH is used to initialize a given device
     instance.  When  attach(9E)  is  called  with  cmd  set   to
     DIATACH,    all   normal   kernel   services   (such   as
     kmemalloc(9F)) are available for use by the driver.  Device
     interrupts  are  not  blocked when attaching a device to the
     system.


     The attach(9E) function is called once for each instance  of
     the  device  on the system with cmd set to DIATACH. Until
     attach(9E) succeeds, the only driver entry point  which  may
     be called is getinfo(9E). See the Writing Device Drivers for
     more information. The instance number may be obtained  using
     ddigetinstance(9F).


     At attach time, all components of a power-manageable  device
     are  assumed  to be at unknown levels. Before using the dev-
     ice, the driver needs to bring the required component(s)  to
     a  known power level. The pmraisepower(9F) function can be



SunOS 5.11           Last change: 7 Jan 2004                    1






Driver Entry Points                                    attach(9E)



     used to set the power level of a  component.  This  function
     must  not  be  called  before  data structures referenced in
     power(9E) have been initialized.

  DIRESUME
     The  attach()  function  may  be  called  with  cmd  set  to
     DIRESUME  after  detach(9E)  has  been successfully called
     with cmd set to DISUSPEND.


     When called  with  cmd  set  to  DIRESUME,  attach()  must
     restore  the hardware state of a device (power may have been
     removed from the device), allow  pending  requests  to  con-
     tinue,  and  service  new requests. In this case, the driver
     must not  make  any  assumptions  about  the  state  of  the
     hardware,  but  must  restore the state of the device except
     for the power level of components.


     If the device driver uses the automatic device Power Manage-
     ment  interfaces  (driver exports the pm-components(9P) pro-
     perty), the Power Management framework sets  its  notion  of
     the  power  level  of  each component of a device to unknown
     while processing a DIRESUME command.


     The driver can deal with components during DIRESUME in one
     of the following ways:

         1.   If the driver can determine the power level of  the
              component  without having to power it up (for exam-
              ple, by calling ddipeek(9F) or some other  device-
              specific  method)  then  it should notify the power
              level    to    the     framework     by     calling
              pmpowerhaschanged(9F).

         2.   The driver must also set  its  own  notion  of  the
              power level of the component to unknown. The system
              will consider the component idle or busy  based  on
              the  most  recent  call to pmidlecomponent(9F) or
              pmbusycomponent(9F) for that  component.  If  the
              component  is  idle for sufficient time, the frame-
              work will call into the  driver's  power(9E)  entry
              point  to  turn  the  component  off. If the driver
              needs to access  the  device,  then  it  must  call
              pmraisepower(9F) to bring the component up to the
              level needed for the device access to succeed.  The
              driver  must  honor  any  request  to set the power
              level of the component, since it  cannot  make  any
              assumption about what power level the component has
              (or it should have called  pmpowerhaschanged(9F)
              as  outlined above). As a special case of this, the



SunOS 5.11           Last change: 7 Jan 2004                    2






Driver Entry Points                                    attach(9E)



              driver may bring the component  to  a  known  state
              because  it  wants  to  perform an operation on the
              device as part of its DIRESUME  processing  (such
              as  loading firmware so that it can detect hot-plug
              events).

RETURN VALUES
     The attach() function returns:

     DISUCES    Successful completion


     DIFAILURE    Operation failed


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),   detach(9E),
     getinfo(9E),  identify(9E),  open(9E), power(9E), probe(9E),
     ddiaddintr(9F),                 ddicreateminornode(9F),
     ddigetinstance(9F),    ddimapregs(9F),   kmemalloc(9F),
     pmraisepower(9F)


     Writing Device Drivers


















SunOS 5.11           Last change: 7 Jan 2004                    3