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