1.\" $NetBSD: pmf.9,v 1.23 2024/03/09 05:22:05 riastradh 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 March 9, 2024 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, const pmf_qual_t *qual)" "bool (*resume)(device_t dev, const pmf_qual_t *qual)" 56.Ft bool 57.Fn pmf_device_register1 "device_t dev" "bool (*suspend)(device_t dev, const pmf_qual_t *qual)" "bool (*resume)(device_t dev, const pmf_qual_t *qual)" "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" "const pmf_qual_t *qual" 62.Ft bool 63.Fn pmf_device_resume "device_t dev" "const pmf_qual_t *qual" 64.Ft bool 65.Fn pmf_device_recursive_suspend "device_t dev" "const pmf_qual_t *qual" 66.Ft bool 67.Fn pmf_device_recursive_resume "device_t dev" "const pmf_qual_t *qual" 68.Ft bool 69.Fn pmf_device_subtree_resume "device_t dev" "const pmf_qual_t *qual" 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 "const pmf_qual_t *qual" 78.Ft bool 79.Fn pmf_system_resume "const pmf_qual_t *qual" 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 93The machine-independent 94.Nm 95framework provides power management and inter-driver messaging support 96for device drivers. 97.Sh DATA TYPES 98Drivers for devices implementing 99.Nm 100may make use of the following data type: 101.Bl -tag -width compact 102.It Fa pmf_qual_t 103An opaque aggregate of qualifications on a 104.Nm 105suspend or resume call. 106.It Fa pmf_generic_event_t 107A device driver can register as a listener for specific events, or inject 108events into the message queue. 109The following message types are defined: 110.Bl -item -compact -offset indent 111.It 112.Dv PMFE_DISPLAY_ON 113.It 114.Dv PMFE_DISPLAY_REDUCED 115.It 116.Dv PMFE_DISPLAY_STANDBY 117.It 118.Dv PMFE_DISPLAY_SUSPEND 119.It 120.Dv PMFE_DISPLAY_OFF 121.It 122.Dv PMFE_DISPLAY_BRIGHTNESS_UP 123.It 124.Dv PMFE_DISPLAY_BRIGHTNESS_DOWN 125.It 126.Dv PMFE_AUDIO_VOLUME_UP 127.It 128.Dv PMFE_AUDIO_VOLUME_DOWN 129.It 130.Dv PMFE_AUDIO_VOLUME_TOGGLE 131.It 132.Dv PMFE_CHASSIS_LID_CLOSE 133.It 134.Dv PMFE_CHASSIS_LID_OPEN 135.El 136.El 137.Sh FUNCTIONS 138.Bl -tag -width compact 139.It Fn pmf_device_register "dev" "suspend" "resume" 140Register a device with the power management framework. 141The 142.Fa suspend 143and 144.Fa resume 145functions are passed 146.Fa dev 147and a 148.Fa pmf_qual_t , 149and will be called when the system state changes; 150they should return 151.Dv true 152on success and 153.Dv false 154on failure. 155If either 156.Fa suspend 157or 158.Fa resume 159is 160.Dv NULL 161then it is assumed that device state does not need to be captured and 162resumed on a power transition. 163Bus and class-level power management will still be performed. 164.Pp 165.Fn pmf_device_register 166always returns true. 167Callers should ignore the return value. 168.It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown" 169Like 170.Fn pmf_device_register , 171but additionally registers a shutdown handler. 172During system shutdown, 173.Fn pmf_system_shutdown 174calls 175.Fa shutdown 176on 177.Fa dev 178with the 179.Xr reboot 2 180.Dq howto 181in the second argument. 182.Fa shutdown 183should return 184.Dv true 185on success and 186.Dv false 187on failure. 188.Pp 189.Fn pmf_device_register1 190always returns true. 191Callers should ignore the return value. 192.It Fn pmf_device_deregister "dev" 193Deregister a device with the power management framework. 194.It Fn pmf_device_suspend "dev" "qual" 195Suspend a device by first calling the class suspend handler, followed by 196the driver suspend handler, and finally the bus suspend handler. 197.It Fn pmf_device_resume "dev" "qual" 198Resume a device by first calling the bus resume handler, followed by the 199driver resume handler, and finally the class resume handler. 200.It Fn pmf_device_recursive_suspend "dev" "qual" 201As 202.Fn pmf_device_suspend , 203but ensures that all child devices of 204.Fa dev 205are suspended. 206.It Fn pmf_device_recursive_resume "dev" "qual" 207As 208.Fn pmf_device_resume , 209but ensures that all parent devices of 210.Fa dev 211are resumed. 212.It Fn pmf_device_subtree_resume "dev" "qual" 213As 214.Fn pmf_device_resume , 215but ensures that all child devices of 216.Fa dev 217are resumed. 218.It Fn pmf_class_network_register "dev" "ifp" 219Register a device with the power management framework as a network-class 220device. 221.It Fn pmf_class_input_register "dev" 222Register a device with the power management framework as an input-class 223device. 224.It Fn pmf_class_display_register "dev" 225Register a device with the power management framework as a display-class 226device. 227.It Fn pmf_system_suspend "qual" 228Suspend all attached devices. 229Devices are suspended by traversing the autoconfiguration tree 230beginning with the leaf nodes. 231This function will fail if any attached drivers do not support the power 232management framework. 233.It Fn pmf_system_resume "qual" 234Resume all attached devices. 235Devices are resumed by traversing the 236autoconfiguration tree beginning with devices that do not have a parent. 237This function will fail if any attached drivers do not support the power 238management framework. 239.It Fn pmf_system_shutdown "int" 240Shutdown all attached devices. 241Devices are shut down by traversing the 242autoconfiguration tree beginning with the leaf nodes. 243The integer argument is passed to the driver shutdown functions. 244It should contain the 245.Xr reboot 2 246.Dq howto 247argument. 248This function ignores the presence of attached drivers that do not support the 249power management framework. 250.It Fn pmf_event_register "dev" "ev" "handler" "global" 251Register the callback 252.Fa handler 253to be called whenever an 254.Fa ev 255event is triggered. 256If 257.Fa global 258is 259.Dv true , 260.Fa handler 261accepts anonymous events from 262.Fn pmf_event_inject . 263.It Fn pmf_event_deregister "dev" "ev" "handler" "global" 264Deregister the callback previously registered with 265.Fn pmf_event_register . 266.It Fn pmf_event_inject "dev" "ev" 267Inject an inter-driver message into the message queue. 268If 269.Fa dev 270is 271.Dv NULL , 272the event is considered to be anonymous and one or more drivers 273may handle this event, otherwise the event is delivered directly to 274the callback registered by 275.Fa dev . 276.It Fn pmf_set_platform "key" "value" 277Insert a name-value pair into the platform information database. 278.It Fn pmf_get_platform "key" 279Retrieve the value for 280.Fa key 281from the platform information database. 282Returns 283.Dv NULL 284if the key is not present. 285.El 286.Sh CODE REFERENCES 287The power management framework is implemented within the files 288.Pa sys/sys/pmf.h , 289.Pa sys/sys/device.h , 290.Pa sys/kern/kern_pmf.c , 291and 292.Pa sys/kern/subr_autoconf.c . 293.Sh SEE ALSO 294.Xr autoconf 9 , 295.Xr driver 9 296.Sh HISTORY 297The 298.Nm 299framework appeared in 300.Nx 5.0 . 301.Sh AUTHORS 302.An Jared D. McNeill Aq Mt jmcneill@NetBSD.org 303.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org 304.Sh BUGS 305.Fn pmf_device_register 306and 307.Fn pmf_device_register1 308never fail and should return void, but until all callers are updated to 309ignore the return value, they must continue to return bool: 310.Lk "https://gnats.NetBSD.org/57575" "PR kern/57575" 311