attach(9E)
NAME
attach - Attach a device to the system, or resume it
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
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,
DDI_PM_RESUME (obsolete) , 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 will be 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
points which may be called are open(9E) and 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
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_PM_RESUME
The DDI_PM_RESUME command is required only if the device
driver uses original Power Management interfaces (driver
calls pm_create_components(9F)). This entry point is not
needed if the device driver uses new automatic device Power
Management interfaces (driver exports pm-components(9P) pro-
perty instead of calling pm_create_components(9F)). The
DDI_PM_RESUME command is obsolete and will be removed in a
future release.
The attach() function may be called with cmd set to
DDI_PM_RESUME after detach(9E) has been successfully called
with cmd set to DDI_PM_SUSPEND. When called with cmd set to
DDI_PM_RESUME, attach() must restore the hardware state of a
device (power may have been removed from the device), allow
pending requests to continue, and service new requests.
The driver must not make any assumptions about the state of
the hardware, but must restore it to the state it had when
the detach(9E) entry point was called with DDI_PM_SUSPEND.
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 original Power Management inter-
faces (driver calls pm_create_components(9F)) and device is
still suspended by DDI_PM_SUSPEND, the only effect of
DDI_RESUME is to allow the driver to call
ddi_dev_is_needed(9F) for any new or pending requests, as a
subsequent call to attach() will be made with cmd set to
DDI_PM_RESUME to restore the hardware state.
If the device driver uses the new automatic device Power
Management interfaces (driver exports pm-components(9P) pro-
perty instead of calling pm_create_components(9F)), then
while processing a DDI_RESUME command, the Power Management
framework sets its notion of the power level of each com-
ponent of a device to unknown.
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 com-
ponent without having to power it up (for example, 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 con-
sider 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 suffi-
cient time, the framework 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 com-
ponent, 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 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 | Evolving (DDI_PM_RESUME is|
| | obsolete) |
|__________________________|________________________________|
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_create_components(9F), pm_raise_power(9F)
Writing Device Drivers
Man(1) output converted with
man2html