man/man9e/attach.9e

         te
 Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 ATTACH 9E "Jan 7, 2004"
 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