NAME

detach - detach a device

SYNOPSIS

#include <sys/ddi.h>

#include <sys/sunddi.h>

int prefixdetach(dev_info_t * dip, ddi_detach_cmd_t cmd);

INTERFACE LEVEL

Solaris DDI specific (Solaris DDI). This entry point is required. It can be nodev.

ARGUMENTS

dip

A pointer to the device's dev_info structure.

cmd

Type of detach; the driver should return DDI_FAILURE if any value other than DDI_DETACH is passed to it.

DESCRIPTION

detach( ) is the complement of the attach(9E) routine. It is used to remove all the states associated with a given instance of a device node prior to the removal of that instance from the system. The dev_info nodes that belong to a driver are removed as part of the process of unloading a device driver from the system.

Depending on what was created in the drivers' attach(9E) routine, this might mean calling ddi_unmap_regs( ) (see ddi_map_regs(9F)) to remove mappings, calling ddi_remove_intr( ) (see ddi_add_intr(9F)) to unregister interrupt handlers, calling kmem_free(9F) to free any heap allocations, and so forth. This should also include putting the underlying device into a quiescent state so that it will not generate interrupts.

If detach( ) determines that the particular instance of the device cannot be removed when requested, for example, because of some exceptional condition, detach( ) returns DDI_FAILURE, which prevents the particular device instance from being removed. This will also prevent the driver from being unloaded.

Drivers that set up timeout(9F) routines should ensure that they are cancelled before returning DDI_SUCCESS from detach( ).

The system guarantees that the function will only be called for a particular dev_info node after (and not concurrently with) a successful attach(9E) of that device. The system also guarantees that detach( ) will only be called when there are no outstanding open(9E) calls on the device.

RETURN VALUES

DDI_SUCCESS

The state associated with the given device was successfully removed.

DDI_FAILURE

The operation failed or the request was not understood. The associated state is unchanged.

CONTEXT

This function is called from user context only.

SEE ALSO

attach(9E), open(9E), ddi_add_intr(9F), ddi_map_regs(9F), kmem_free(9F), timeout(9F)

Writing Device Drivers