detach(9e) - osol9

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

NAME

6       detach - detach or suspend a device
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int prefix detach(dev_info_t dip, ddi_detach_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    Type  of  detach;  the  driver  should return DDI_FAILURE if any
25              value other than DDI_DETACH or DDI_SUSPEND is passed to it.
26
27

DESCRIPTION

29       The detach() function complements the attach(9E) routine.
30
31   DDI_DETACH
32       If cmd is set to DDI_DETACH, detach() is used to remove the state asso‐
33       ciated  with  a given instance of a device node prior to the removal of
34       that instance from the system.
35
36
37       The detach() function will be called once  for  each  instance  of  the
38       device  for  which there has been a successful attach(), once there are
39       no longer any opens on the device. An attached instance of a driver can
40       be  successfully detached only once. The detach() function should clean
41       up  any  per  instance  data  initialized  in   attach(9E)   and   call
42       kmem_free(9F)  to  free any heap allocations. For information on how to
43       unregister interrupt handlers, see ddi_add_intr(9F). This  should  also
44       include putting the underlying device into a quiescent state so that it
45       will not generate interrupts.
46
47
48       Drivers that set up timeout(9F) routines should ensure  that  they  are
49       cancelled before returning DDI_SUCCESS from detach().
50
51
52       If  detach()  determines  a particular instance of the device cannot be
53       removed when requested because of some exceptional condition,  detach()
54       must  return DDI_FAILURE, which prevents the particular device instance
55       from being detached. This also prevents the driver from being unloaded.
56       A  driver  instance failing the detach must ensure that no per instance
57       data or state is modified or freed that would compromise the system  or
58       subsequent driver operation.
59
60
61       The  system guarantees that the function will only be called for a par‐
62       ticular dev_info node after (and not concurrently  with)  a  successful
63       attach(9E)  of  that  device.  The system also guarantees that detach()
64       will only be called when there are no outstanding open(9E) calls on the
65       device.
66
67   DDI_SUSPEND
68       The DDI_SUSPEND cmd is issued when the entire system is being suspended
69       and power removed from it or when the system must be made quiescent. It
70       will  be  issued  only  to  devices  which have a reg property or which
71       export a  pm-hardware-state  property  with  the  value  needs-suspend-
72       resume.
73
74
75       If  cmd is set to DDI_SUSPEND, detach() is used to suspend all activity
76       of a device before power is (possibly) removed  from  the  device.  The
77       steps  associated  with  suspension must include putting the underlying
78       device into a quiescent state so that it will not  generate  interrupts
79       or modify or access memory. Once quiescence has been obtained, detach()
80       can be called with outstanding open(9E)  requests.  It  must  save  the
81       hardware  state  of the device to memory and block incoming or existing
82       requests until attach() is called with DDI_RESUME.
83
84
85       If the device is used to store file systems, then after DDI_SUSPEND  is
86       issued,  the  device should still honor dump(9E) requests as this entry
87       point may be used by suspend-resume  operation  (see  cpr(7))  to  save
88       state  file.  It  must  do  this, however, without disturbing the saved
89       hardware state of the device.
90
91
92       If the device driver uses automatic device Power Management  interfaces
93       (driver  exports  pm-components(9P)  property),  it  might need to call
94       pm_raise_power(9F) if the current power level is lower than required to
95       complete the dump(9E) request.
96
97
98       Before returning successfully from a call to detach() with a command of
99       DDI_SUSPEND, the driver must cancel any outstanding timeouts  and  make
100       any driver threads quiescent.
101
102
103       If  DDI_FAILURE  is returned for the DDI_SUSPEND cmd, either the opera‐
104       tion to suspend the system or to make it quiescent will be aborted.
105

RETURN VALUES

107       DDI_SUCCESS    For DDI_DETACH, the  state  associated  with  the  given
108                      device  was  successfully  removed. For DDI_SUSPEND, the
109                      driver was successfully suspended.
110
111
112       DDI_FAILURE    The operation failed or the request was not  understood.
113                      The associated state is unchanged.
114
115

CONTEXT

117       This function is called from user context only.
118

ATTRIBUTES

120       See attributes(5) for descriptions of the following attributes:
121
122
123
124
125       ┌─────────────────────────────┬─────────────────────────────┐
126       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
127       ├─────────────────────────────┼─────────────────────────────┤
128       │Interface Stability          │Committed                    │
129       └─────────────────────────────┴─────────────────────────────┘
130