share/man/man9/pmf.9

   1 .\" $NetBSD: pmf.9,v 1.11 2009/05/14 23:05:21 dyoung Exp $
   2 .\"
   3 .\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd May 14, 2009
  28 .Dt PMF 9
  29 .Os
  30 .Sh NAME
  31 .Nm PMF ,
  32 .Nm pmf_device_register ,
  33 .Nm pmf_device_register1 ,
  34 .Nm pmf_device_deregister ,
  35 .Nm pmf_device_suspend ,
  36 .Nm pmf_device_resume ,
  37 .Nm pmf_device_recursive_suspend ,
  38 .Nm pmf_device_recursive_resume ,
  39 .Nm pmf_device_resume_subtree ,
  40 .Nm pmf_class_network_register ,
  41 .Nm pmf_class_input_register ,
  42 .Nm pmf_class_display_register ,
  43 .Nm pmf_system_suspend ,
  44 .Nm pmf_system_resume ,
  45 .Nm pmf_system_shutdown ,
  46 .Nm pmf_event_register ,
  47 .Nm pmf_event_deregister ,
  48 .Nm pmf_event_inject ,
  49 .Nm pmf_set_platform ,
  50 .Nm pmf_get_platform
  51 .Nd power management and inter-driver messaging framework
  52 .Sh SYNOPSIS
  53 .In sys/device.h
  54 .Ft bool
  55 .Fn pmf_device_register "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)"
  56 .Ft bool
  57 .Fn pmf_device_register1 "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)" "bool (*shutdown)(device_t dev, int how)"
  58 .Ft void
  59 .Fn pmf_device_deregister "device_t dev"
  60 .Ft bool
  61 .Fn pmf_device_suspend "device_t dev"
  62 .Ft bool
  63 .Fn pmf_device_resume "device_t dev"
  64 .Ft bool
  65 .Fn pmf_device_recursive_suspend "device_t dev"
  66 .Ft bool
  67 .Fn pmf_device_recursive_resume "device_t dev"
  68 .Ft bool
  69 .Fn pmf_device_resume_subtree "device_t dev"
  70 .Ft void
  71 .Fn pmf_class_network_register "device_t dev" "struct ifnet *ifp"
  72 .Ft bool
  73 .Fn pmf_class_input_register "device_t dev"
  74 .Ft bool
  75 .Fn pmf_class_display_register "device_t dev"
  76 .Ft bool
  77 .Fn pmf_system_suspend "void"
  78 .Ft bool
  79 .Fn pmf_system_resume "void"
  80 .Ft void
  81 .Fn pmf_system_shutdown "int"
  82 .Ft bool
  83 .Fn pmf_event_register "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global"
  84 .Ft void
  85 .Fn pmf_event_deregister "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global"
  86 .Ft bool
  87 .Fn pmf_event_inject "device_t dev" "pmf_generic_event_t ev"
  88 .Ft bool
  89 .Fn pmf_set_platform "const char *key" "const char *value"
  90 .Ft const char *
  91 .Fn pmf_get_platform "const char *key"
  92 .Sh DESCRIPTION
  93 The machine-independent
  94 .Nm
  95 framework provides power management and inter-driver messaging support
  96 for device drivers.
  97 .Sh DATA TYPES
  98 Drivers for devices implementing
  99 .Nm
 100 may make use of the following data type:
 101 .Bl -tag -width compact
 102 .It Fa pmf_generic_event_t
 103 A device driver can register as a listener for specific events, or inject
 104 events into the message queue.
 105 The following message types are defined:
 106 .Bl -item -compact -offset indent
 107 .It
 108 .Dv PMFE_DISPLAY_ON
 109 .It
 110 .Dv PMFE_DISPLAY_REDUCED
 111 .It
 112 .Dv PMFE_DISPLAY_STANDBY
 113 .It
 114 .Dv PMFE_DISPLAY_SUSPEND
 115 .It
 116 .Dv PMFE_DISPLAY_OFF
 117 .It
 118 .Dv PMFE_DISPLAY_BRIGHTNESS_UP
 119 .It
 120 .Dv PMFE_DISPLAY_BRIGHTNESS_DOWN
 121 .It
 122 .Dv PMFE_AUDIO_VOLUME_UP
 123 .It
 124 .Dv PMFE_AUDIO_VOLUME_DOWN
 125 .It
 126 .Dv PMFE_AUDIO_VOLUME_TOGGLE
 127 .It
 128 .Dv PMFE_CHASSIS_LID_CLOSE
 129 .It
 130 .Dv PMFE_CHASSIS_LID_OPEN
 131 .El
 132 .El
 133 .Sh FUNCTIONS
 134 .Bl -tag -width compact
 135 .It Fn pmf_device_register "dev" "suspend" "resume"
 136 Register a device with the power management framework.
 137 .Fa suspend
 138 and
 139 .Fa resume
 140 are passed
 141 .Fa dev
 142 and they return
 143 .Dv true
 144 on success and
 145 .Dv false
 146 on failure.
 147 If either
 148 .Fa suspend
 149 or
 150 .Fa resume
 151 is
 152 .Dv NULL
 153 then it is assumed that device state does not need to be captured and
 154 resumed on a power transition.
 155 Bus and class-level power management will still be performed.
 156 Returns
 157 .Dv false
 158 if there was an error.
 159 .It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown"
 160 Like
 161 .Fn pmf_device_register ,
 162 but additionally registers a shutdown handler.
 163 During system shutdown,
 164 .Fn pmf_system_shutdown
 165 calls
 166 .Fa shutdown
 167 on
 168 .Fa dev
 169 with the
 170 .Xr reboot 2
 171 .Dq howto
 172 in the second argument.
 173 .Fa shutdown
 174 should return
 175 .Dv true
 176 on success and
 177 .Dv false
 178 on failure.
 179 .It Fn pmf_device_deregister "dev"
 180 Deregister a device with the power management framework.
 181 .It Fn pmf_device_suspend "dev"
 182 Suspend a device by first calling the class suspend handler, followed by
 183 the driver suspend handler, and finally the bus suspend handler.
 184 .It Fn pmf_device_resume "dev"
 185 Resume a device by first calling the bus resume handler, followed by the
 186 driver resume handler, and finally the class resume handler.
 187 .It Fn pmf_device_recursive_suspend "dev"
 188 As
 189 .Fn pmf_device_suspend ,
 190 but ensures that all child devices of
 191 .Fa dev
 192 are suspended.
 193 .It Fn pmf_device_recursive_resume "dev"
 194 As
 195 .Fn pmf_device_resume ,
 196 but ensures that all parent devices of
 197 .Fa dev
 198 are resumed.
 199 .It Fn pmf_device_resume_subtree "dev"
 200 As
 201 .Fn pmf_device_resume ,
 202 but ensures that all child devices of
 203 .Fa dev
 204 are resumed.
 205 .It Fn pmf_class_network_register "dev" "ifp"
 206 Register a device with the power management framework as a network-class
 207 device.
 208 .It Fn pmf_class_input_register "dev"
 209 Register a device with the power management framework as an input-class
 210 device.
 211 .It Fn pmf_class_display_register "dev"
 212 Register a device with the power management framework as a display-class
 213 device.
 214 .It Fn pmf_system_suspend "void"
 215 Suspend all attached devices.
 216 Devices are suspended by traversing the
 217 autoconfiguration tree beginning with the leaf nodes.
 218 This function will fail if any attached drivers do not support the power
 219 management framework.
 220 .It Fn pmf_system_resume "void"
 221 Resume all attached devices.
 222 Devices are resumed by traversing the
 223 autoconfiguration tree beginning with devices that do not have a parent.
 224 This function will fail if any attached drivers do not support the power
 225 management framework.
 226 .It Fn pmf_system_shutdown "int"
 227 Shutdown all attached devices.
 228 Devices are shut down by traversing the
 229 autoconfiguration tree beginning with the leaf nodes.
 230 The integer argument is passed to the driver shutdown functions.
 231 It should contain the
 232 .Xr reboot 2
 233 .Dq howto
 234 argument.
 235 This function ignores the presence of attached drivers that do not support the
 236 power management framework.
 237 .It Fn pmf_event_register "dev" "ev" "handler" "global"
 238 Register the callback
 239 .Fa handler
 240 to be called whenever an
 241 .Fa ev
 242 event is triggered.
 243 If
 244 .Fa global
 245 is
 246 .Dv true ,
 247 .Fa handler
 248 accepts anonymous events from
 249 .Fn pmf_event_inject .
 250 .It Fn pmf_event_deregister "dev" "ev" "handler" "global"
 251 Deregister the callback previously registered with
 252 .Fn pmf_event_register .
 253 .It Fn pmf_event_inject "dev" "ev"
 254 Inject an inter-driver message into the message queue.
 255 If
 256 .Fa dev
 257 is
 258 .Dv NULL ,
 259 the event is considered to be anonymous and one or more drivers
 260 may handle this event, otherwise the event is delivered directly to
 261 the callback registered by
 262 .Fa dev .
 263 .It Fn pmf_set_platform "key" "value"
 264 Insert a name-value pair into the platform information database.
 265 .It Fn pmf_get_platform "key"
 266 Retrieve the value for
 267 .Fa key
 268 from the platform information database.
 269 Returns
 270 .Dv NULL
 271 if the key is not present.
 272 .El
 273 .Sh CODE REFERENCES
 274 This section describes places within the
 275 .Nx
 276 source tree where actual code implementing or using the power management
 277 framework can be found.
 278 All pathnames are relative to
 279 .Pa /usr/src .
 280 .Pp
 281 The power management framework is implemented within the files
 282 .Pa sys/sys/pmf.h ,
 283 .Pa sys/sys/device.h ,
 284 .Pa sys/kern/kern_pmf.c ,
 285 and
 286 .Pa sys/kern/subr_autoconf.c .
 287 .Sh SEE ALSO
 288 .Xr autoconf 9 ,
 289 .Xr driver 9
 290 .Sh HISTORY
 291 The
 292 .Nm
 293 framework appeared in
 294 .Nx 5.0 .
 295 .Sh AUTHORS
 296 .An Jared D. McNeill Aq jmcneill@NetBSD.org
 297 .An Joerg Sonnenberger Aq joerg@NetBSD.org