ATTACH(9E) Driver Entry Points 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
illumos DDI specific (illumos 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 initialization 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 device, 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_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 continue, 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 Management
interfaces (driver exports the
pm-components(9P) property), 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 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 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
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 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 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(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
SEE ALSO
cpr(4),
pm(4D),
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),
pm(9P),
pm-components(9P) Writing Device Drivers January 7, 2004
ATTACH(9E)