Manual Pages for UNIX Operating System command usage for man attach

Driver Entry Points                                    attach(9E)



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

SYNOPSIS
     #include 
     #include 



     int prefixattach(dev_info_t *dip, ddi_attach_cmd_t cmd);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

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


     cmd    Attach  type.  Possible  values  are  DDI_ATTACH  and
            DDI_RESUME.  Other  values  are  reserved. The driver
            must return DDI_FAILURE 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.

  DDI_ATTACH
     The DDI_ATTACH command must be provided  in  the  attach(9E)
     entry point. DDI_ATTACH is used to initialize a given device
     instance.  When  attach(9E)  is  called  with  cmd  set   to
     DDI_ATTACH,    all   normal   kernel   services   (such   as
     kmem_alloc(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 DDI_ATTACH. 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
     ddi_get_instance(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 pm_raise_power(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.

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


     When called  with  cmd  set  to  DDI_RESUME,  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 DDI_RESUME command.


     The driver can deal with components during DDI_RESUME 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 ddi_peek(9F) or some other  device-
              specific  method)  then  it should notify the power
              level    to    the     framework     by     calling
              pm_power_has_changed(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 pm_idle_component(9F) or
              pm_busy_component(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
              pm_raise_power(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  pm_power_has_changed(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 DDI_RESUME  processing  (such
              as  loading firmware so that it can detect hot-plug
              events).

RETURN VALUES
     The attach() function returns:

     DDI_SUCCESS    Successful completion


     DDI_FAILURE    Operation failed


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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE 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),
     ddi_add_intr(9F),                 ddi_create_minor_node(9F),
     ddi_get_instance(9F),    ddi_map_regs(9F),   kmem_alloc(9F),
     pm_raise_power(9F)


     Writing Device Drivers


















SunOS 5.11           Last change: 7 Jan 2004                    3