1ddi_dev_is_needed(9F)    Kernel Functions for Drivers    ddi_dev_is_needed(9F)
2
3
4

NAME

6       ddi_dev_is_needed  -  inform  the  system  that a device's component is
7       required
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13
14
15       int ddi_dev_is_needed(dev_info_t *dip, int component, int level);
16
17

INTERFACE LEVEL

19       Solaris DDI specific (Solaris DDI)
20

PARAMETERS

22       dip          Pointer to the device's dev_info structure.
23
24
25       component    Component of the driver which is needed.
26
27
28       level        Power level at which the component is needed.
29
30

DESCRIPTION

32       The ddi_dev_is_needed() function is obsolete and will be removed  in  a
33       future   release.   It   is   recommended   that   device  drivers  use
34       pm_raise_power(9F) and pm_lower_power(9F).
35
36
37       The ddi_dev_is_needed() function informs the system that a device  com‐
38       ponent  is needed at the specified power level. The level argument must
39       be non-zero.
40
41
42       This function sets a component to  the  required  level  and  sets  all
43       devices which depend on this to their normal power levels.
44
45
46       The state of the device should be examined before each physical access.
47       The ddi_dev_is_needed() function should be called to set a component to
48       the  required power level if the operation to be performed requires the
49       component to be at a power level other than its current level.
50
51
52       The ddi_dev_is_needed() function might cause re-entry  of  the  driver.
53       Deadlock  may  result  if  driver  locks  are  held  across the call to
54       ddi_dev_is_needed().
55

RETURN VALUES

57       The ddi_dev_is_needed() function returns:
58
59       DDI_SUCCESS    Power successfully set to the requested level.
60
61
62       DDI_FAILURE    An error occurred.
63
64

EXAMPLES

66       Example 1 disk driver code
67
68
69       A hypothetical disk driver might include this code:
70
71
72              static int
73         xxdisk_spun_down(struct xxstate *xsp)
74         {
75                   return (xsp->power_level[DISK_COMPONENT] < POWER_SPUN_UP);
76         }
77         static int
78         xxdisk_strategy(struct buf *bp)
79         {
80
81         ...
82
83              mutex_enter(&xxstate_lock);
84              /*
85              * Since we have to drop the mutex, we have to do this in a loop
86              * in case we get preempted and the device gets taken away from
87              * us again
88              */
89              while (device_spun_down(sp)) {
90                   mutex_exit(&xxstate_lock);
91                   if (ddi_dev_is_needed(xsp->mydip,
92                        XXDISK_COMPONENT, XXPOWER_SPUN_UP) != DDI_SUCCESS) {
93                             bioerror(bp,EIO);
94                             biodone(bp);
95                   return (0);
96              }
97                   mutex_enter(&xxstate_lock);
98              }
99              xsp->device_busy++;
100              mutex_exit(&xxstate_lock);
101
102         ...
103
104         }
105
106

CONTEXT

108       This function can be called from user or kernel context.
109

ATTRIBUTES

111       See attributes(5) for descriptions of the following attributes:
112
113
114
115
116       ┌─────────────────────────────┬─────────────────────────────┐
117       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
118       ├─────────────────────────────┼─────────────────────────────┤
119       │Interface Stability          │Obsolete                     │
120       └─────────────────────────────┴─────────────────────────────┘
121

SEE ALSO

123       pm(7D),   pm-components(9P),   attach(9E),    detach(9E),    power(9E),
124       pm_busy_component(9F), pm_idle_component(9F)
125
126
127       Writing Device Drivers
128
129
130
131SunOS 5.11                        7 Dec 2003             ddi_dev_is_needed(9F)
Impressum