attach(9e) - osol9

1attach(9E)                    Driver Entry Points                   attach(9E)
2
3
4

NAME

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

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int prefixattach(dev_info_t *dip, ddi_attach_cmd_t cmd);
15
16

INTERFACE LEVEL

18       Solaris DDI specific (Solaris DDI)
19

PARAMETERS

21       dip    A pointer to the device's dev_info structure.
22
23
24       cmd    Attach  type.  Possible  values  are  DDI_ATTACH and DDI_RESUME.
25              Other values are reserved. The driver must return DDI_FAILURE if
26              reserved values are passed to it.
27
28

DESCRIPTION

30       The  attach(9E)  function  is  the device-specific initialization entry
31       point. This entry point is required and must be written.
32
33   DDI_ATTACH
34       The DDI_ATTACH command must be provided in the attach(9E) entry  point.
35       DDI_ATTACH  is  used  to  initialize  a  given  device  instance.  When
36       attach(9E) is called with cmd set to DDI_ATTACH, all normal kernel ser‐
37       vices  (such  as  kmem_alloc(9F))  are available for use by the driver.
38       Device interrupts are not blocked when attaching a device to  the  sys‐
39       tem.
40
41
42       The  attach(9E) function is called once for each instance of the device
43       on the system with cmd set to DDI_ATTACH.  Until  attach(9E)  succeeds,
44       the only driver entry point which may be called is getinfo(9E). See the
45       Writing Device Drivers for more information. The instance number may be
46       obtained using ddi_get_instance(9F).
47
48
49       At attach time, all components of a power-manageable device are assumed
50       to be at unknown levels. Before using the device, the driver  needs  to
51       bring   the   required   component(s)  to  a  known  power  level.  The
52       pm_raise_power(9F) function can be used to set the  power  level  of  a
53       component. This function must not be called before data structures ref‐
54       erenced in power(9E) have been initialized.
55
56   DDI_RESUME
57       The attach() function may be called with cmd set  to  DDI_RESUME  after
58       detach(9E) has been successfully called with cmd set to DDI_SUSPEND.
59
60
61       When called with cmd set to DDI_RESUME, attach() must restore the hard‐
62       ware state of a device (power may have been removed from  the  device),
63       allow  pending  requests to continue, and service new requests. In this
64       case, the driver must not make any assumptions about the state  of  the
65       hardware, but must restore the state of the device except for the power
66       level of components.
67
68
69       If the device driver uses the automatic device Power Management  inter‐
70       faces  (driver  exports the pm-components(9P) property), the Power Man‐
71       agement framework sets its notion of the power level of each  component
72       of a device to unknown while processing a DDI_RESUME command.
73
74
75       The  driver  can  deal  with components during DDI_RESUME in one of the
76       following ways:
77
78           1.     If the driver can determine the power level of the component
79                  without  having  to  power  it  up  (for example, by calling
80                  ddi_peek(9F) or some other device-specific method)  then  it
81                  should  notify  the  power level to the framework by calling
82                  pm_power_has_changed(9F).
83
84           2.     The driver must also set its own notion of the  power  level
85                  of  the  component  to unknown. The system will consider the
86                  component idle or busy based on  the  most  recent  call  to
87                  pm_idle_component(9F) or pm_busy_component(9F) for that com‐
88                  ponent. If the component is idle for  sufficient  time,  the
89                  framework  will call into the driver's power(9E) entry point
90                  to turn the component off. If the driver needs to access the
91                  device,  then  it  must call pm_raise_power(9F) to bring the
92                  component up to the level needed for the  device  access  to
93                  succeed.  The driver must honor any request to set the power
94                  level of the component, since it cannot make any  assumption
95                  about  what power level the component has (or it should have
96                  called pm_power_has_changed(9F) as  outlined  above).  As  a
97                  special  case of this, the driver may bring the component to
98                  a known state because it wants to perform  an  operation  on
99                  the  device  as  part  of its DDI_RESUME processing (such as
100                  loading firmware so that it can detect hot-plug events).
101

RETURN VALUES

103       The attach() function returns:
104
105       DDI_SUCCESS    Successful completion
106
107
108       DDI_FAILURE    Operation failed
109
110

ATTRIBUTES

112       See attributes(5) for descriptions of the following attributes:
113
114
115
116
117       ┌─────────────────────────────┬─────────────────────────────┐
118       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
119       ├─────────────────────────────┼─────────────────────────────┤
120       │Interface Stability          │Committed                    │
121       └─────────────────────────────┴─────────────────────────────┘
122