1151f4e2bSMauro Carvalho Chehab================================================== 2151f4e2bSMauro Carvalho ChehabRuntime Power Management Framework for I/O Devices 3151f4e2bSMauro Carvalho Chehab================================================== 4151f4e2bSMauro Carvalho Chehab 5151f4e2bSMauro Carvalho Chehab(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. 6151f4e2bSMauro Carvalho Chehab 7151f4e2bSMauro Carvalho Chehab(C) 2010 Alan Stern <stern@rowland.harvard.edu> 8151f4e2bSMauro Carvalho Chehab 9151f4e2bSMauro Carvalho Chehab(C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> 10151f4e2bSMauro Carvalho Chehab 11151f4e2bSMauro Carvalho Chehab1. Introduction 12151f4e2bSMauro Carvalho Chehab=============== 13151f4e2bSMauro Carvalho Chehab 14151f4e2bSMauro Carvalho ChehabSupport for runtime power management (runtime PM) of I/O devices is provided 15151f4e2bSMauro Carvalho Chehabat the power management core (PM core) level by means of: 16151f4e2bSMauro Carvalho Chehab 17151f4e2bSMauro Carvalho Chehab* The power management workqueue pm_wq in which bus types and device drivers can 18151f4e2bSMauro Carvalho Chehab put their PM-related work items. It is strongly recommended that pm_wq be 19151f4e2bSMauro Carvalho Chehab used for queuing all work items related to runtime PM, because this allows 20151f4e2bSMauro Carvalho Chehab them to be synchronized with system-wide power transitions (suspend to RAM, 21151f4e2bSMauro Carvalho Chehab hibernation and resume from system sleep states). pm_wq is declared in 22151f4e2bSMauro Carvalho Chehab include/linux/pm_runtime.h and defined in kernel/power/main.c. 23151f4e2bSMauro Carvalho Chehab 24151f4e2bSMauro Carvalho Chehab* A number of runtime PM fields in the 'power' member of 'struct device' (which 25151f4e2bSMauro Carvalho Chehab is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can 26151f4e2bSMauro Carvalho Chehab be used for synchronizing runtime PM operations with one another. 27151f4e2bSMauro Carvalho Chehab 28151f4e2bSMauro Carvalho Chehab* Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in 29151f4e2bSMauro Carvalho Chehab include/linux/pm.h). 30151f4e2bSMauro Carvalho Chehab 31151f4e2bSMauro Carvalho Chehab* A set of helper functions defined in drivers/base/power/runtime.c that can be 32151f4e2bSMauro Carvalho Chehab used for carrying out runtime PM operations in such a way that the 33151f4e2bSMauro Carvalho Chehab synchronization between them is taken care of by the PM core. Bus types and 34151f4e2bSMauro Carvalho Chehab device drivers are encouraged to use these functions. 35151f4e2bSMauro Carvalho Chehab 36151f4e2bSMauro Carvalho ChehabThe runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM 37151f4e2bSMauro Carvalho Chehabfields of 'struct dev_pm_info' and the core helper functions provided for 38151f4e2bSMauro Carvalho Chehabruntime PM are described below. 39151f4e2bSMauro Carvalho Chehab 40151f4e2bSMauro Carvalho Chehab2. Device Runtime PM Callbacks 41151f4e2bSMauro Carvalho Chehab============================== 42151f4e2bSMauro Carvalho Chehab 43151f4e2bSMauro Carvalho ChehabThere are three device runtime PM callbacks defined in 'struct dev_pm_ops':: 44151f4e2bSMauro Carvalho Chehab 45151f4e2bSMauro Carvalho Chehab struct dev_pm_ops { 46151f4e2bSMauro Carvalho Chehab ... 47151f4e2bSMauro Carvalho Chehab int (*runtime_suspend)(struct device *dev); 48151f4e2bSMauro Carvalho Chehab int (*runtime_resume)(struct device *dev); 49151f4e2bSMauro Carvalho Chehab int (*runtime_idle)(struct device *dev); 50151f4e2bSMauro Carvalho Chehab ... 51151f4e2bSMauro Carvalho Chehab }; 52151f4e2bSMauro Carvalho Chehab 53151f4e2bSMauro Carvalho ChehabThe ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks 54151f4e2bSMauro Carvalho Chehabare executed by the PM core for the device's subsystem that may be either of 55151f4e2bSMauro Carvalho Chehabthe following: 56151f4e2bSMauro Carvalho Chehab 57151f4e2bSMauro Carvalho Chehab 1. PM domain of the device, if the device's PM domain object, dev->pm_domain, 58151f4e2bSMauro Carvalho Chehab is present. 59151f4e2bSMauro Carvalho Chehab 60151f4e2bSMauro Carvalho Chehab 2. Device type of the device, if both dev->type and dev->type->pm are present. 61151f4e2bSMauro Carvalho Chehab 62151f4e2bSMauro Carvalho Chehab 3. Device class of the device, if both dev->class and dev->class->pm are 63151f4e2bSMauro Carvalho Chehab present. 64151f4e2bSMauro Carvalho Chehab 65151f4e2bSMauro Carvalho Chehab 4. Bus type of the device, if both dev->bus and dev->bus->pm are present. 66151f4e2bSMauro Carvalho Chehab 67151f4e2bSMauro Carvalho ChehabIf the subsystem chosen by applying the above rules doesn't provide the relevant 68151f4e2bSMauro Carvalho Chehabcallback, the PM core will invoke the corresponding driver callback stored in 69151f4e2bSMauro Carvalho Chehabdev->driver->pm directly (if present). 70151f4e2bSMauro Carvalho Chehab 71151f4e2bSMauro Carvalho ChehabThe PM core always checks which callback to use in the order given above, so the 72151f4e2bSMauro Carvalho Chehabpriority order of callbacks from high to low is: PM domain, device type, class 73151f4e2bSMauro Carvalho Chehaband bus type. Moreover, the high-priority one will always take precedence over 74151f4e2bSMauro Carvalho Chehaba low-priority one. The PM domain, bus type, device type and class callbacks 75151f4e2bSMauro Carvalho Chehabare referred to as subsystem-level callbacks in what follows. 76151f4e2bSMauro Carvalho Chehab 77151f4e2bSMauro Carvalho ChehabBy default, the callbacks are always invoked in process context with interrupts 78151f4e2bSMauro Carvalho Chehabenabled. However, the pm_runtime_irq_safe() helper function can be used to tell 79151f4e2bSMauro Carvalho Chehabthe PM core that it is safe to run the ->runtime_suspend(), ->runtime_resume() 80151f4e2bSMauro Carvalho Chehaband ->runtime_idle() callbacks for the given device in atomic context with 81151f4e2bSMauro Carvalho Chehabinterrupts disabled. This implies that the callback routines in question must 82151f4e2bSMauro Carvalho Chehabnot block or sleep, but it also means that the synchronous helper functions 83151f4e2bSMauro Carvalho Chehablisted at the end of Section 4 may be used for that device within an interrupt 84151f4e2bSMauro Carvalho Chehabhandler or generally in an atomic context. 85151f4e2bSMauro Carvalho Chehab 86151f4e2bSMauro Carvalho ChehabThe subsystem-level suspend callback, if present, is _entirely_ _responsible_ 87151f4e2bSMauro Carvalho Chehabfor handling the suspend of the device as appropriate, which may, but need not 88151f4e2bSMauro Carvalho Chehabinclude executing the device driver's own ->runtime_suspend() callback (from the 89151f4e2bSMauro Carvalho ChehabPM core's point of view it is not necessary to implement a ->runtime_suspend() 90151f4e2bSMauro Carvalho Chehabcallback in a device driver as long as the subsystem-level suspend callback 91151f4e2bSMauro Carvalho Chehabknows what to do to handle the device). 92151f4e2bSMauro Carvalho Chehab 93151f4e2bSMauro Carvalho Chehab * Once the subsystem-level suspend callback (or the driver suspend callback, 94151f4e2bSMauro Carvalho Chehab if invoked directly) has completed successfully for the given device, the PM 95151f4e2bSMauro Carvalho Chehab core regards the device as suspended, which need not mean that it has been 96151f4e2bSMauro Carvalho Chehab put into a low power state. It is supposed to mean, however, that the 97151f4e2bSMauro Carvalho Chehab device will not process data and will not communicate with the CPU(s) and 98151f4e2bSMauro Carvalho Chehab RAM until the appropriate resume callback is executed for it. The runtime 99151f4e2bSMauro Carvalho Chehab PM status of a device after successful execution of the suspend callback is 100151f4e2bSMauro Carvalho Chehab 'suspended'. 101151f4e2bSMauro Carvalho Chehab 102151f4e2bSMauro Carvalho Chehab * If the suspend callback returns -EBUSY or -EAGAIN, the device's runtime PM 103151f4e2bSMauro Carvalho Chehab status remains 'active', which means that the device _must_ be fully 104151f4e2bSMauro Carvalho Chehab operational afterwards. 105151f4e2bSMauro Carvalho Chehab 106151f4e2bSMauro Carvalho Chehab * If the suspend callback returns an error code different from -EBUSY and 107151f4e2bSMauro Carvalho Chehab -EAGAIN, the PM core regards this as a fatal error and will refuse to run 108151f4e2bSMauro Carvalho Chehab the helper functions described in Section 4 for the device until its status 109151f4e2bSMauro Carvalho Chehab is directly set to either 'active', or 'suspended' (the PM core provides 110151f4e2bSMauro Carvalho Chehab special helper functions for this purpose). 111151f4e2bSMauro Carvalho Chehab 112151f4e2bSMauro Carvalho ChehabIn particular, if the driver requires remote wakeup capability (i.e. hardware 113151f4e2bSMauro Carvalho Chehabmechanism allowing the device to request a change of its power state, such as 114151f4e2bSMauro Carvalho ChehabPCI PME) for proper functioning and device_can_wakeup() returns 'false' for the 115151f4e2bSMauro Carvalho Chehabdevice, then ->runtime_suspend() should return -EBUSY. On the other hand, if 116151f4e2bSMauro Carvalho Chehabdevice_can_wakeup() returns 'true' for the device and the device is put into a 117151f4e2bSMauro Carvalho Chehablow-power state during the execution of the suspend callback, it is expected 118151f4e2bSMauro Carvalho Chehabthat remote wakeup will be enabled for the device. Generally, remote wakeup 119151f4e2bSMauro Carvalho Chehabshould be enabled for all input devices put into low-power states at run time. 120151f4e2bSMauro Carvalho Chehab 121151f4e2bSMauro Carvalho ChehabThe subsystem-level resume callback, if present, is **entirely responsible** for 122151f4e2bSMauro Carvalho Chehabhandling the resume of the device as appropriate, which may, but need not 123151f4e2bSMauro Carvalho Chehabinclude executing the device driver's own ->runtime_resume() callback (from the 124151f4e2bSMauro Carvalho ChehabPM core's point of view it is not necessary to implement a ->runtime_resume() 125151f4e2bSMauro Carvalho Chehabcallback in a device driver as long as the subsystem-level resume callback knows 126151f4e2bSMauro Carvalho Chehabwhat to do to handle the device). 127151f4e2bSMauro Carvalho Chehab 128151f4e2bSMauro Carvalho Chehab * Once the subsystem-level resume callback (or the driver resume callback, if 129151f4e2bSMauro Carvalho Chehab invoked directly) has completed successfully, the PM core regards the device 130151f4e2bSMauro Carvalho Chehab as fully operational, which means that the device _must_ be able to complete 131151f4e2bSMauro Carvalho Chehab I/O operations as needed. The runtime PM status of the device is then 132151f4e2bSMauro Carvalho Chehab 'active'. 133151f4e2bSMauro Carvalho Chehab 134151f4e2bSMauro Carvalho Chehab * If the resume callback returns an error code, the PM core regards this as a 135151f4e2bSMauro Carvalho Chehab fatal error and will refuse to run the helper functions described in Section 136151f4e2bSMauro Carvalho Chehab 4 for the device, until its status is directly set to either 'active', or 137151f4e2bSMauro Carvalho Chehab 'suspended' (by means of special helper functions provided by the PM core 138151f4e2bSMauro Carvalho Chehab for this purpose). 139151f4e2bSMauro Carvalho Chehab 140151f4e2bSMauro Carvalho ChehabThe idle callback (a subsystem-level one, if present, or the driver one) is 141151f4e2bSMauro Carvalho Chehabexecuted by the PM core whenever the device appears to be idle, which is 142151f4e2bSMauro Carvalho Chehabindicated to the PM core by two counters, the device's usage counter and the 143151f4e2bSMauro Carvalho Chehabcounter of 'active' children of the device. 144151f4e2bSMauro Carvalho Chehab 145151f4e2bSMauro Carvalho Chehab * If any of these counters is decreased using a helper function provided by 146151f4e2bSMauro Carvalho Chehab the PM core and it turns out to be equal to zero, the other counter is 147151f4e2bSMauro Carvalho Chehab checked. If that counter also is equal to zero, the PM core executes the 148151f4e2bSMauro Carvalho Chehab idle callback with the device as its argument. 149151f4e2bSMauro Carvalho Chehab 150151f4e2bSMauro Carvalho ChehabThe action performed by the idle callback is totally dependent on the subsystem 151151f4e2bSMauro Carvalho Chehab(or driver) in question, but the expected and recommended action is to check 152151f4e2bSMauro Carvalho Chehabif the device can be suspended (i.e. if all of the conditions necessary for 153151f4e2bSMauro Carvalho Chehabsuspending the device are satisfied) and to queue up a suspend request for the 154151f4e2bSMauro Carvalho Chehabdevice in that case. If there is no idle callback, or if the callback returns 155151f4e2bSMauro Carvalho Chehab0, then the PM core will attempt to carry out a runtime suspend of the device, 156151f4e2bSMauro Carvalho Chehabalso respecting devices configured for autosuspend. In essence this means a 157b7d46644SSakari Ailuscall to __pm_runtime_autosuspend() (do note that drivers needs to update the 158151f4e2bSMauro Carvalho Chehabdevice last busy mark, pm_runtime_mark_last_busy(), to control the delay under 159151f4e2bSMauro Carvalho Chehabthis circumstance). To prevent this (for example, if the callback routine has 160151f4e2bSMauro Carvalho Chehabstarted a delayed suspend), the routine must return a non-zero value. Negative 161151f4e2bSMauro Carvalho Chehaberror return codes are ignored by the PM core. 162151f4e2bSMauro Carvalho Chehab 163151f4e2bSMauro Carvalho ChehabThe helper functions provided by the PM core, described in Section 4, guarantee 164151f4e2bSMauro Carvalho Chehabthat the following constraints are met with respect to runtime PM callbacks for 165151f4e2bSMauro Carvalho Chehabone device: 166151f4e2bSMauro Carvalho Chehab 167151f4e2bSMauro Carvalho Chehab(1) The callbacks are mutually exclusive (e.g. it is forbidden to execute 168151f4e2bSMauro Carvalho Chehab ->runtime_suspend() in parallel with ->runtime_resume() or with another 169151f4e2bSMauro Carvalho Chehab instance of ->runtime_suspend() for the same device) with the exception that 170151f4e2bSMauro Carvalho Chehab ->runtime_suspend() or ->runtime_resume() can be executed in parallel with 171151f4e2bSMauro Carvalho Chehab ->runtime_idle() (although ->runtime_idle() will not be started while any 172151f4e2bSMauro Carvalho Chehab of the other callbacks is being executed for the same device). 173151f4e2bSMauro Carvalho Chehab 174151f4e2bSMauro Carvalho Chehab(2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active' 175151f4e2bSMauro Carvalho Chehab devices (i.e. the PM core will only execute ->runtime_idle() or 176151f4e2bSMauro Carvalho Chehab ->runtime_suspend() for the devices the runtime PM status of which is 177151f4e2bSMauro Carvalho Chehab 'active'). 178151f4e2bSMauro Carvalho Chehab 179151f4e2bSMauro Carvalho Chehab(3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device 180151f4e2bSMauro Carvalho Chehab the usage counter of which is equal to zero _and_ either the counter of 181151f4e2bSMauro Carvalho Chehab 'active' children of which is equal to zero, or the 'power.ignore_children' 182151f4e2bSMauro Carvalho Chehab flag of which is set. 183151f4e2bSMauro Carvalho Chehab 184151f4e2bSMauro Carvalho Chehab(4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the 185151f4e2bSMauro Carvalho Chehab PM core will only execute ->runtime_resume() for the devices the runtime 186151f4e2bSMauro Carvalho Chehab PM status of which is 'suspended'). 187151f4e2bSMauro Carvalho Chehab 188151f4e2bSMauro Carvalho ChehabAdditionally, the helper functions provided by the PM core obey the following 189151f4e2bSMauro Carvalho Chehabrules: 190151f4e2bSMauro Carvalho Chehab 191151f4e2bSMauro Carvalho Chehab * If ->runtime_suspend() is about to be executed or there's a pending request 192151f4e2bSMauro Carvalho Chehab to execute it, ->runtime_idle() will not be executed for the same device. 193151f4e2bSMauro Carvalho Chehab 194151f4e2bSMauro Carvalho Chehab * A request to execute or to schedule the execution of ->runtime_suspend() 195151f4e2bSMauro Carvalho Chehab will cancel any pending requests to execute ->runtime_idle() for the same 196151f4e2bSMauro Carvalho Chehab device. 197151f4e2bSMauro Carvalho Chehab 198151f4e2bSMauro Carvalho Chehab * If ->runtime_resume() is about to be executed or there's a pending request 199151f4e2bSMauro Carvalho Chehab to execute it, the other callbacks will not be executed for the same device. 200151f4e2bSMauro Carvalho Chehab 201151f4e2bSMauro Carvalho Chehab * A request to execute ->runtime_resume() will cancel any pending or 202151f4e2bSMauro Carvalho Chehab scheduled requests to execute the other callbacks for the same device, 203151f4e2bSMauro Carvalho Chehab except for scheduled autosuspends. 204151f4e2bSMauro Carvalho Chehab 205151f4e2bSMauro Carvalho Chehab3. Runtime PM Device Fields 206151f4e2bSMauro Carvalho Chehab=========================== 207151f4e2bSMauro Carvalho Chehab 208151f4e2bSMauro Carvalho ChehabThe following device runtime PM fields are present in 'struct dev_pm_info', as 209151f4e2bSMauro Carvalho Chehabdefined in include/linux/pm.h: 210151f4e2bSMauro Carvalho Chehab 211151f4e2bSMauro Carvalho Chehab `struct timer_list suspend_timer;` 212151f4e2bSMauro Carvalho Chehab - timer used for scheduling (delayed) suspend and autosuspend requests 213151f4e2bSMauro Carvalho Chehab 214151f4e2bSMauro Carvalho Chehab `unsigned long timer_expires;` 215151f4e2bSMauro Carvalho Chehab - timer expiration time, in jiffies (if this is different from zero, the 216151f4e2bSMauro Carvalho Chehab timer is running and will expire at that time, otherwise the timer is not 217151f4e2bSMauro Carvalho Chehab running) 218151f4e2bSMauro Carvalho Chehab 219151f4e2bSMauro Carvalho Chehab `struct work_struct work;` 220151f4e2bSMauro Carvalho Chehab - work structure used for queuing up requests (i.e. work items in pm_wq) 221151f4e2bSMauro Carvalho Chehab 222151f4e2bSMauro Carvalho Chehab `wait_queue_head_t wait_queue;` 223151f4e2bSMauro Carvalho Chehab - wait queue used if any of the helper functions needs to wait for another 224151f4e2bSMauro Carvalho Chehab one to complete 225151f4e2bSMauro Carvalho Chehab 226151f4e2bSMauro Carvalho Chehab `spinlock_t lock;` 227151f4e2bSMauro Carvalho Chehab - lock used for synchronization 228151f4e2bSMauro Carvalho Chehab 229151f4e2bSMauro Carvalho Chehab `atomic_t usage_count;` 230151f4e2bSMauro Carvalho Chehab - the usage counter of the device 231151f4e2bSMauro Carvalho Chehab 232151f4e2bSMauro Carvalho Chehab `atomic_t child_count;` 233151f4e2bSMauro Carvalho Chehab - the count of 'active' children of the device 234151f4e2bSMauro Carvalho Chehab 235151f4e2bSMauro Carvalho Chehab `unsigned int ignore_children;` 236151f4e2bSMauro Carvalho Chehab - if set, the value of child_count is ignored (but still updated) 237151f4e2bSMauro Carvalho Chehab 238151f4e2bSMauro Carvalho Chehab `unsigned int disable_depth;` 239151f4e2bSMauro Carvalho Chehab - used for disabling the helper functions (they work normally if this is 240151f4e2bSMauro Carvalho Chehab equal to zero); the initial value of it is 1 (i.e. runtime PM is 241151f4e2bSMauro Carvalho Chehab initially disabled for all devices) 242151f4e2bSMauro Carvalho Chehab 243151f4e2bSMauro Carvalho Chehab `int runtime_error;` 244151f4e2bSMauro Carvalho Chehab - if set, there was a fatal error (one of the callbacks returned error code 245151f4e2bSMauro Carvalho Chehab as described in Section 2), so the helper functions will not work until 246151f4e2bSMauro Carvalho Chehab this flag is cleared; this is the error code returned by the failing 247151f4e2bSMauro Carvalho Chehab callback 248151f4e2bSMauro Carvalho Chehab 249151f4e2bSMauro Carvalho Chehab `unsigned int idle_notification;` 250151f4e2bSMauro Carvalho Chehab - if set, ->runtime_idle() is being executed 251151f4e2bSMauro Carvalho Chehab 252151f4e2bSMauro Carvalho Chehab `unsigned int request_pending;` 253151f4e2bSMauro Carvalho Chehab - if set, there's a pending request (i.e. a work item queued up into pm_wq) 254151f4e2bSMauro Carvalho Chehab 255151f4e2bSMauro Carvalho Chehab `enum rpm_request request;` 256151f4e2bSMauro Carvalho Chehab - type of request that's pending (valid if request_pending is set) 257151f4e2bSMauro Carvalho Chehab 258151f4e2bSMauro Carvalho Chehab `unsigned int deferred_resume;` 259151f4e2bSMauro Carvalho Chehab - set if ->runtime_resume() is about to be run while ->runtime_suspend() is 260151f4e2bSMauro Carvalho Chehab being executed for that device and it is not practical to wait for the 261151f4e2bSMauro Carvalho Chehab suspend to complete; means "start a resume as soon as you've suspended" 262151f4e2bSMauro Carvalho Chehab 263151f4e2bSMauro Carvalho Chehab `enum rpm_status runtime_status;` 264151f4e2bSMauro Carvalho Chehab - the runtime PM status of the device; this field's initial value is 265151f4e2bSMauro Carvalho Chehab RPM_SUSPENDED, which means that each device is initially regarded by the 266151f4e2bSMauro Carvalho Chehab PM core as 'suspended', regardless of its real hardware status 267151f4e2bSMauro Carvalho Chehab 268c24efa67SRafael J. Wysocki `enum rpm_status last_status;` 269c24efa67SRafael J. Wysocki - the last runtime PM status of the device captured before disabling runtime 270c24efa67SRafael J. Wysocki PM for it (invalid initially and when disable_depth is 0) 271c24efa67SRafael J. Wysocki 272151f4e2bSMauro Carvalho Chehab `unsigned int runtime_auto;` 273151f4e2bSMauro Carvalho Chehab - if set, indicates that the user space has allowed the device driver to 274151f4e2bSMauro Carvalho Chehab power manage the device at run time via the /sys/devices/.../power/control 2751992b66dSBjorn Helgaas `interface;` it may only be modified with the help of the 2761992b66dSBjorn Helgaas pm_runtime_allow() and pm_runtime_forbid() helper functions 277151f4e2bSMauro Carvalho Chehab 278151f4e2bSMauro Carvalho Chehab `unsigned int no_callbacks;` 279151f4e2bSMauro Carvalho Chehab - indicates that the device does not use the runtime PM callbacks (see 280151f4e2bSMauro Carvalho Chehab Section 8); it may be modified only by the pm_runtime_no_callbacks() 281151f4e2bSMauro Carvalho Chehab helper function 282151f4e2bSMauro Carvalho Chehab 283151f4e2bSMauro Carvalho Chehab `unsigned int irq_safe;` 284151f4e2bSMauro Carvalho Chehab - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks 285151f4e2bSMauro Carvalho Chehab will be invoked with the spinlock held and interrupts disabled 286151f4e2bSMauro Carvalho Chehab 287151f4e2bSMauro Carvalho Chehab `unsigned int use_autosuspend;` 288151f4e2bSMauro Carvalho Chehab - indicates that the device's driver supports delayed autosuspend (see 289151f4e2bSMauro Carvalho Chehab Section 9); it may be modified only by the 290151f4e2bSMauro Carvalho Chehab pm_runtime{_dont}_use_autosuspend() helper functions 291151f4e2bSMauro Carvalho Chehab 292151f4e2bSMauro Carvalho Chehab `unsigned int timer_autosuspends;` 293151f4e2bSMauro Carvalho Chehab - indicates that the PM core should attempt to carry out an autosuspend 294151f4e2bSMauro Carvalho Chehab when the timer expires rather than a normal suspend 295151f4e2bSMauro Carvalho Chehab 296151f4e2bSMauro Carvalho Chehab `int autosuspend_delay;` 297151f4e2bSMauro Carvalho Chehab - the delay time (in milliseconds) to be used for autosuspend 298151f4e2bSMauro Carvalho Chehab 299151f4e2bSMauro Carvalho Chehab `unsigned long last_busy;` 300151f4e2bSMauro Carvalho Chehab - the time (in jiffies) when the pm_runtime_mark_last_busy() helper 301151f4e2bSMauro Carvalho Chehab function was last called for this device; used in calculating inactivity 302151f4e2bSMauro Carvalho Chehab periods for autosuspend 303151f4e2bSMauro Carvalho Chehab 304151f4e2bSMauro Carvalho ChehabAll of the above fields are members of the 'power' member of 'struct device'. 305151f4e2bSMauro Carvalho Chehab 306151f4e2bSMauro Carvalho Chehab4. Runtime PM Device Helper Functions 307151f4e2bSMauro Carvalho Chehab===================================== 308151f4e2bSMauro Carvalho Chehab 309151f4e2bSMauro Carvalho ChehabThe following runtime PM helper functions are defined in 310151f4e2bSMauro Carvalho Chehabdrivers/base/power/runtime.c and include/linux/pm_runtime.h: 311151f4e2bSMauro Carvalho Chehab 312151f4e2bSMauro Carvalho Chehab `void pm_runtime_init(struct device *dev);` 313151f4e2bSMauro Carvalho Chehab - initialize the device runtime PM fields in 'struct dev_pm_info' 314151f4e2bSMauro Carvalho Chehab 315151f4e2bSMauro Carvalho Chehab `void pm_runtime_remove(struct device *dev);` 316151f4e2bSMauro Carvalho Chehab - make sure that the runtime PM of the device will be disabled after 317151f4e2bSMauro Carvalho Chehab removing the device from device hierarchy 318151f4e2bSMauro Carvalho Chehab 319151f4e2bSMauro Carvalho Chehab `int pm_runtime_idle(struct device *dev);` 320151f4e2bSMauro Carvalho Chehab - execute the subsystem-level idle callback for the device; returns an 321151f4e2bSMauro Carvalho Chehab error code on failure, where -EINPROGRESS means that ->runtime_idle() is 322151f4e2bSMauro Carvalho Chehab already being executed; if there is no callback or the callback returns 0 323151f4e2bSMauro Carvalho Chehab then run pm_runtime_autosuspend(dev) and return its result 324151f4e2bSMauro Carvalho Chehab 325151f4e2bSMauro Carvalho Chehab `int pm_runtime_suspend(struct device *dev);` 326151f4e2bSMauro Carvalho Chehab - execute the subsystem-level suspend callback for the device; returns 0 on 327151f4e2bSMauro Carvalho Chehab success, 1 if the device's runtime PM status was already 'suspended', or 328151f4e2bSMauro Carvalho Chehab error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt 329151f4e2bSMauro Carvalho Chehab to suspend the device again in future and -EACCES means that 330151f4e2bSMauro Carvalho Chehab 'power.disable_depth' is different from 0 331151f4e2bSMauro Carvalho Chehab 332151f4e2bSMauro Carvalho Chehab `int pm_runtime_autosuspend(struct device *dev);` 333151f4e2bSMauro Carvalho Chehab - same as pm_runtime_suspend() except that the autosuspend delay is taken 334151f4e2bSMauro Carvalho Chehab `into account;` if pm_runtime_autosuspend_expiration() says the delay has 335151f4e2bSMauro Carvalho Chehab not yet expired then an autosuspend is scheduled for the appropriate time 336151f4e2bSMauro Carvalho Chehab and 0 is returned 337151f4e2bSMauro Carvalho Chehab 338151f4e2bSMauro Carvalho Chehab `int pm_runtime_resume(struct device *dev);` 339151f4e2bSMauro Carvalho Chehab - execute the subsystem-level resume callback for the device; returns 0 on 340c24efa67SRafael J. Wysocki success, 1 if the device's runtime PM status is already 'active' (also if 341c24efa67SRafael J. Wysocki 'power.disable_depth' is nonzero, but the status was 'active' when it was 342c24efa67SRafael J. Wysocki changing from 0 to 1) or error code on failure, where -EAGAIN means it may 343c24efa67SRafael J. Wysocki be safe to attempt to resume the device again in future, but 344c24efa67SRafael J. Wysocki 'power.runtime_error' should be checked additionally, and -EACCES means 345c24efa67SRafael J. Wysocki that the callback could not be run, because 'power.disable_depth' was 346151f4e2bSMauro Carvalho Chehab different from 0 347151f4e2bSMauro Carvalho Chehab 3482c412337SAlan Stern `int pm_runtime_resume_and_get(struct device *dev);` 3492c412337SAlan Stern - run pm_runtime_resume(dev) and if successful, increment the device's 3502c412337SAlan Stern usage counter; return the result of pm_runtime_resume 3512c412337SAlan Stern 352151f4e2bSMauro Carvalho Chehab `int pm_request_idle(struct device *dev);` 353151f4e2bSMauro Carvalho Chehab - submit a request to execute the subsystem-level idle callback for the 354151f4e2bSMauro Carvalho Chehab device (the request is represented by a work item in pm_wq); returns 0 on 355151f4e2bSMauro Carvalho Chehab success or error code if the request has not been queued up 356151f4e2bSMauro Carvalho Chehab 357151f4e2bSMauro Carvalho Chehab `int pm_request_autosuspend(struct device *dev);` 358151f4e2bSMauro Carvalho Chehab - schedule the execution of the subsystem-level suspend callback for the 359151f4e2bSMauro Carvalho Chehab device when the autosuspend delay has expired; if the delay has already 360151f4e2bSMauro Carvalho Chehab expired then the work item is queued up immediately 361151f4e2bSMauro Carvalho Chehab 362151f4e2bSMauro Carvalho Chehab `int pm_schedule_suspend(struct device *dev, unsigned int delay);` 363151f4e2bSMauro Carvalho Chehab - schedule the execution of the subsystem-level suspend callback for the 364151f4e2bSMauro Carvalho Chehab device in future, where 'delay' is the time to wait before queuing up a 365151f4e2bSMauro Carvalho Chehab suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work 366151f4e2bSMauro Carvalho Chehab item is queued up immediately); returns 0 on success, 1 if the device's PM 367151f4e2bSMauro Carvalho Chehab runtime status was already 'suspended', or error code if the request 368151f4e2bSMauro Carvalho Chehab hasn't been scheduled (or queued up if 'delay' is 0); if the execution of 369151f4e2bSMauro Carvalho Chehab ->runtime_suspend() is already scheduled and not yet expired, the new 370151f4e2bSMauro Carvalho Chehab value of 'delay' will be used as the time to wait 371151f4e2bSMauro Carvalho Chehab 372151f4e2bSMauro Carvalho Chehab `int pm_request_resume(struct device *dev);` 373151f4e2bSMauro Carvalho Chehab - submit a request to execute the subsystem-level resume callback for the 374151f4e2bSMauro Carvalho Chehab device (the request is represented by a work item in pm_wq); returns 0 on 375151f4e2bSMauro Carvalho Chehab success, 1 if the device's runtime PM status was already 'active', or 376151f4e2bSMauro Carvalho Chehab error code if the request hasn't been queued up 377151f4e2bSMauro Carvalho Chehab 378151f4e2bSMauro Carvalho Chehab `void pm_runtime_get_noresume(struct device *dev);` 379151f4e2bSMauro Carvalho Chehab - increment the device's usage counter 380151f4e2bSMauro Carvalho Chehab 381151f4e2bSMauro Carvalho Chehab `int pm_runtime_get(struct device *dev);` 382151f4e2bSMauro Carvalho Chehab - increment the device's usage counter, run pm_request_resume(dev) and 383151f4e2bSMauro Carvalho Chehab return its result 384151f4e2bSMauro Carvalho Chehab 385151f4e2bSMauro Carvalho Chehab `int pm_runtime_get_sync(struct device *dev);` 386151f4e2bSMauro Carvalho Chehab - increment the device's usage counter, run pm_runtime_resume(dev) and 387c58e7ed2SKrzysztof Kozlowski return its result; 388c58e7ed2SKrzysztof Kozlowski note that it does not drop the device's usage counter on errors, so 389c58e7ed2SKrzysztof Kozlowski consider using pm_runtime_resume_and_get() instead of it, especially 390c58e7ed2SKrzysztof Kozlowski if its return value is checked by the caller, as this is likely to 391c58e7ed2SKrzysztof Kozlowski result in cleaner code. 392151f4e2bSMauro Carvalho Chehab 393151f4e2bSMauro Carvalho Chehab `int pm_runtime_get_if_in_use(struct device *dev);` 394151f4e2bSMauro Carvalho Chehab - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the 395151f4e2bSMauro Carvalho Chehab runtime PM status is RPM_ACTIVE and the runtime PM usage counter is 396151f4e2bSMauro Carvalho Chehab nonzero, increment the counter and return 1; otherwise return 0 without 397151f4e2bSMauro Carvalho Chehab changing the counter 398151f4e2bSMauro Carvalho Chehab 399c0ef3df8SSakari Ailus `int pm_runtime_get_if_active(struct device *dev);` 400c111566bSSakari Ailus - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the 401c0ef3df8SSakari Ailus runtime PM status is RPM_ACTIVE, increment the counter and 402c111566bSSakari Ailus return 1; otherwise return 0 without changing the counter 403c111566bSSakari Ailus 404151f4e2bSMauro Carvalho Chehab `void pm_runtime_put_noidle(struct device *dev);` 405151f4e2bSMauro Carvalho Chehab - decrement the device's usage counter 406151f4e2bSMauro Carvalho Chehab 407151f4e2bSMauro Carvalho Chehab `int pm_runtime_put(struct device *dev);` 408151f4e2bSMauro Carvalho Chehab - decrement the device's usage counter; if the result is 0 then run 409151f4e2bSMauro Carvalho Chehab pm_request_idle(dev) and return its result 410151f4e2bSMauro Carvalho Chehab 411151f4e2bSMauro Carvalho Chehab `int pm_runtime_put_autosuspend(struct device *dev);` 412b7d46644SSakari Ailus - does the same as __pm_runtime_put_autosuspend() for now, but in the 413b7d46644SSakari Ailus future, will also call pm_runtime_mark_last_busy() as well, DO NOT USE! 414b7d46644SSakari Ailus 415b7d46644SSakari Ailus `int __pm_runtime_put_autosuspend(struct device *dev);` 416151f4e2bSMauro Carvalho Chehab - decrement the device's usage counter; if the result is 0 then run 417151f4e2bSMauro Carvalho Chehab pm_request_autosuspend(dev) and return its result 418151f4e2bSMauro Carvalho Chehab 419151f4e2bSMauro Carvalho Chehab `int pm_runtime_put_sync(struct device *dev);` 420151f4e2bSMauro Carvalho Chehab - decrement the device's usage counter; if the result is 0 then run 421151f4e2bSMauro Carvalho Chehab pm_runtime_idle(dev) and return its result 422151f4e2bSMauro Carvalho Chehab 423151f4e2bSMauro Carvalho Chehab `int pm_runtime_put_sync_suspend(struct device *dev);` 424151f4e2bSMauro Carvalho Chehab - decrement the device's usage counter; if the result is 0 then run 425151f4e2bSMauro Carvalho Chehab pm_runtime_suspend(dev) and return its result 426151f4e2bSMauro Carvalho Chehab 427151f4e2bSMauro Carvalho Chehab `int pm_runtime_put_sync_autosuspend(struct device *dev);` 428151f4e2bSMauro Carvalho Chehab - decrement the device's usage counter; if the result is 0 then run 429151f4e2bSMauro Carvalho Chehab pm_runtime_autosuspend(dev) and return its result 430151f4e2bSMauro Carvalho Chehab 431151f4e2bSMauro Carvalho Chehab `void pm_runtime_enable(struct device *dev);` 432151f4e2bSMauro Carvalho Chehab - decrement the device's 'power.disable_depth' field; if that field is equal 433151f4e2bSMauro Carvalho Chehab to zero, the runtime PM helper functions can execute subsystem-level 434151f4e2bSMauro Carvalho Chehab callbacks described in Section 2 for the device 435151f4e2bSMauro Carvalho Chehab 436151f4e2bSMauro Carvalho Chehab `int pm_runtime_disable(struct device *dev);` 437151f4e2bSMauro Carvalho Chehab - increment the device's 'power.disable_depth' field (if the value of that 438151f4e2bSMauro Carvalho Chehab field was previously zero, this prevents subsystem-level runtime PM 439151f4e2bSMauro Carvalho Chehab callbacks from being run for the device), make sure that all of the 440151f4e2bSMauro Carvalho Chehab pending runtime PM operations on the device are either completed or 441151f4e2bSMauro Carvalho Chehab canceled; returns 1 if there was a resume request pending and it was 442151f4e2bSMauro Carvalho Chehab necessary to execute the subsystem-level resume callback for the device 443151f4e2bSMauro Carvalho Chehab to satisfy that request, otherwise 0 is returned 444151f4e2bSMauro Carvalho Chehab 445151f4e2bSMauro Carvalho Chehab `int pm_runtime_barrier(struct device *dev);` 446151f4e2bSMauro Carvalho Chehab - check if there's a resume request pending for the device and resume it 447151f4e2bSMauro Carvalho Chehab (synchronously) in that case, cancel any other pending runtime PM requests 448151f4e2bSMauro Carvalho Chehab regarding it and wait for all runtime PM operations on it in progress to 449151f4e2bSMauro Carvalho Chehab complete; returns 1 if there was a resume request pending and it was 450151f4e2bSMauro Carvalho Chehab necessary to execute the subsystem-level resume callback for the device to 451151f4e2bSMauro Carvalho Chehab satisfy that request, otherwise 0 is returned 452151f4e2bSMauro Carvalho Chehab 453151f4e2bSMauro Carvalho Chehab `void pm_suspend_ignore_children(struct device *dev, bool enable);` 454151f4e2bSMauro Carvalho Chehab - set/unset the power.ignore_children flag of the device 455151f4e2bSMauro Carvalho Chehab 456151f4e2bSMauro Carvalho Chehab `int pm_runtime_set_active(struct device *dev);` 457151f4e2bSMauro Carvalho Chehab - clear the device's 'power.runtime_error' flag, set the device's runtime 458151f4e2bSMauro Carvalho Chehab PM status to 'active' and update its parent's counter of 'active' 459151f4e2bSMauro Carvalho Chehab children as appropriate (it is only valid to use this function if 460151f4e2bSMauro Carvalho Chehab 'power.runtime_error' is set or 'power.disable_depth' is greater than 461151f4e2bSMauro Carvalho Chehab zero); it will fail and return error code if the device has a parent 462151f4e2bSMauro Carvalho Chehab which is not active and the 'power.ignore_children' flag of which is unset 463151f4e2bSMauro Carvalho Chehab 464151f4e2bSMauro Carvalho Chehab `void pm_runtime_set_suspended(struct device *dev);` 465151f4e2bSMauro Carvalho Chehab - clear the device's 'power.runtime_error' flag, set the device's runtime 466151f4e2bSMauro Carvalho Chehab PM status to 'suspended' and update its parent's counter of 'active' 467151f4e2bSMauro Carvalho Chehab children as appropriate (it is only valid to use this function if 468151f4e2bSMauro Carvalho Chehab 'power.runtime_error' is set or 'power.disable_depth' is greater than 469151f4e2bSMauro Carvalho Chehab zero) 470151f4e2bSMauro Carvalho Chehab 471151f4e2bSMauro Carvalho Chehab `bool pm_runtime_active(struct device *dev);` 472151f4e2bSMauro Carvalho Chehab - return true if the device's runtime PM status is 'active' or its 473151f4e2bSMauro Carvalho Chehab 'power.disable_depth' field is not equal to zero, or false otherwise 474151f4e2bSMauro Carvalho Chehab 475151f4e2bSMauro Carvalho Chehab `bool pm_runtime_suspended(struct device *dev);` 476151f4e2bSMauro Carvalho Chehab - return true if the device's runtime PM status is 'suspended' and its 477151f4e2bSMauro Carvalho Chehab 'power.disable_depth' field is equal to zero, or false otherwise 478151f4e2bSMauro Carvalho Chehab 479151f4e2bSMauro Carvalho Chehab `bool pm_runtime_status_suspended(struct device *dev);` 480151f4e2bSMauro Carvalho Chehab - return true if the device's runtime PM status is 'suspended' 481151f4e2bSMauro Carvalho Chehab 482151f4e2bSMauro Carvalho Chehab `void pm_runtime_allow(struct device *dev);` 483151f4e2bSMauro Carvalho Chehab - set the power.runtime_auto flag for the device and decrease its usage 484151f4e2bSMauro Carvalho Chehab counter (used by the /sys/devices/.../power/control interface to 485151f4e2bSMauro Carvalho Chehab effectively allow the device to be power managed at run time) 486151f4e2bSMauro Carvalho Chehab 487151f4e2bSMauro Carvalho Chehab `void pm_runtime_forbid(struct device *dev);` 488151f4e2bSMauro Carvalho Chehab - unset the power.runtime_auto flag for the device and increase its usage 489151f4e2bSMauro Carvalho Chehab counter (used by the /sys/devices/.../power/control interface to 490151f4e2bSMauro Carvalho Chehab effectively prevent the device from being power managed at run time) 491151f4e2bSMauro Carvalho Chehab 492151f4e2bSMauro Carvalho Chehab `void pm_runtime_no_callbacks(struct device *dev);` 493151f4e2bSMauro Carvalho Chehab - set the power.no_callbacks flag for the device and remove the runtime 494151f4e2bSMauro Carvalho Chehab PM attributes from /sys/devices/.../power (or prevent them from being 495151f4e2bSMauro Carvalho Chehab added when the device is registered) 496151f4e2bSMauro Carvalho Chehab 497151f4e2bSMauro Carvalho Chehab `void pm_runtime_irq_safe(struct device *dev);` 498151f4e2bSMauro Carvalho Chehab - set the power.irq_safe flag for the device, causing the runtime-PM 499151f4e2bSMauro Carvalho Chehab callbacks to be invoked with interrupts off 500151f4e2bSMauro Carvalho Chehab 501151f4e2bSMauro Carvalho Chehab `bool pm_runtime_is_irq_safe(struct device *dev);` 502151f4e2bSMauro Carvalho Chehab - return true if power.irq_safe flag was set for the device, causing 503151f4e2bSMauro Carvalho Chehab the runtime-PM callbacks to be invoked with interrupts off 504151f4e2bSMauro Carvalho Chehab 505151f4e2bSMauro Carvalho Chehab `void pm_runtime_mark_last_busy(struct device *dev);` 506151f4e2bSMauro Carvalho Chehab - set the power.last_busy field to the current time 507151f4e2bSMauro Carvalho Chehab 508151f4e2bSMauro Carvalho Chehab `void pm_runtime_use_autosuspend(struct device *dev);` 509151f4e2bSMauro Carvalho Chehab - set the power.use_autosuspend flag, enabling autosuspend delays; call 510151f4e2bSMauro Carvalho Chehab pm_runtime_get_sync if the flag was previously cleared and 511151f4e2bSMauro Carvalho Chehab power.autosuspend_delay is negative 512151f4e2bSMauro Carvalho Chehab 513151f4e2bSMauro Carvalho Chehab `void pm_runtime_dont_use_autosuspend(struct device *dev);` 514151f4e2bSMauro Carvalho Chehab - clear the power.use_autosuspend flag, disabling autosuspend delays; 515151f4e2bSMauro Carvalho Chehab decrement the device's usage counter if the flag was previously set and 516151f4e2bSMauro Carvalho Chehab power.autosuspend_delay is negative; call pm_runtime_idle 517151f4e2bSMauro Carvalho Chehab 518151f4e2bSMauro Carvalho Chehab `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);` 519151f4e2bSMauro Carvalho Chehab - set the power.autosuspend_delay value to 'delay' (expressed in 520151f4e2bSMauro Carvalho Chehab milliseconds); if 'delay' is negative then runtime suspends are 521151f4e2bSMauro Carvalho Chehab prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be 522151f4e2bSMauro Carvalho Chehab called or the device's usage counter may be decremented and 523151f4e2bSMauro Carvalho Chehab pm_runtime_idle called depending on if power.autosuspend_delay is 524151f4e2bSMauro Carvalho Chehab changed to or from a negative value; if power.use_autosuspend is clear, 525151f4e2bSMauro Carvalho Chehab pm_runtime_idle is called 526151f4e2bSMauro Carvalho Chehab 527151f4e2bSMauro Carvalho Chehab `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);` 528151f4e2bSMauro Carvalho Chehab - calculate the time when the current autosuspend delay period will expire, 529151f4e2bSMauro Carvalho Chehab based on power.last_busy and power.autosuspend_delay; if the delay time 530151f4e2bSMauro Carvalho Chehab is 1000 ms or larger then the expiration time is rounded up to the 531151f4e2bSMauro Carvalho Chehab nearest second; returns 0 if the delay period has already expired or 532151f4e2bSMauro Carvalho Chehab power.use_autosuspend isn't set, otherwise returns the expiration time 533151f4e2bSMauro Carvalho Chehab in jiffies 534151f4e2bSMauro Carvalho Chehab 535151f4e2bSMauro Carvalho ChehabIt is safe to execute the following helper functions from interrupt context: 536151f4e2bSMauro Carvalho Chehab 537151f4e2bSMauro Carvalho Chehab- pm_request_idle() 538151f4e2bSMauro Carvalho Chehab- pm_request_autosuspend() 539151f4e2bSMauro Carvalho Chehab- pm_schedule_suspend() 540151f4e2bSMauro Carvalho Chehab- pm_request_resume() 541151f4e2bSMauro Carvalho Chehab- pm_runtime_get_noresume() 542151f4e2bSMauro Carvalho Chehab- pm_runtime_get() 543151f4e2bSMauro Carvalho Chehab- pm_runtime_put_noidle() 544151f4e2bSMauro Carvalho Chehab- pm_runtime_put() 545151f4e2bSMauro Carvalho Chehab- pm_runtime_put_autosuspend() 546b7d46644SSakari Ailus- __pm_runtime_put_autosuspend() 547151f4e2bSMauro Carvalho Chehab- pm_runtime_enable() 548151f4e2bSMauro Carvalho Chehab- pm_suspend_ignore_children() 549151f4e2bSMauro Carvalho Chehab- pm_runtime_set_active() 550151f4e2bSMauro Carvalho Chehab- pm_runtime_set_suspended() 551151f4e2bSMauro Carvalho Chehab- pm_runtime_suspended() 552151f4e2bSMauro Carvalho Chehab- pm_runtime_mark_last_busy() 553151f4e2bSMauro Carvalho Chehab- pm_runtime_autosuspend_expiration() 554151f4e2bSMauro Carvalho Chehab 555151f4e2bSMauro Carvalho ChehabIf pm_runtime_irq_safe() has been called for a device then the following helper 556151f4e2bSMauro Carvalho Chehabfunctions may also be used in interrupt context: 557151f4e2bSMauro Carvalho Chehab 558151f4e2bSMauro Carvalho Chehab- pm_runtime_idle() 559151f4e2bSMauro Carvalho Chehab- pm_runtime_suspend() 560151f4e2bSMauro Carvalho Chehab- pm_runtime_autosuspend() 561151f4e2bSMauro Carvalho Chehab- pm_runtime_resume() 562151f4e2bSMauro Carvalho Chehab- pm_runtime_get_sync() 563151f4e2bSMauro Carvalho Chehab- pm_runtime_put_sync() 564151f4e2bSMauro Carvalho Chehab- pm_runtime_put_sync_suspend() 565151f4e2bSMauro Carvalho Chehab- pm_runtime_put_sync_autosuspend() 566151f4e2bSMauro Carvalho Chehab 567151f4e2bSMauro Carvalho Chehab5. Runtime PM Initialization, Device Probing and Removal 568151f4e2bSMauro Carvalho Chehab======================================================== 569151f4e2bSMauro Carvalho Chehab 570151f4e2bSMauro Carvalho ChehabInitially, the runtime PM is disabled for all devices, which means that the 571151f4e2bSMauro Carvalho Chehabmajority of the runtime PM helper functions described in Section 4 will return 572151f4e2bSMauro Carvalho Chehab-EAGAIN until pm_runtime_enable() is called for the device. 573151f4e2bSMauro Carvalho Chehab 574151f4e2bSMauro Carvalho ChehabIn addition to that, the initial runtime PM status of all devices is 575151f4e2bSMauro Carvalho Chehab'suspended', but it need not reflect the actual physical state of the device. 576151f4e2bSMauro Carvalho ChehabThus, if the device is initially active (i.e. it is able to process I/O), its 577151f4e2bSMauro Carvalho Chehabruntime PM status must be changed to 'active', with the help of 578151f4e2bSMauro Carvalho Chehabpm_runtime_set_active(), before pm_runtime_enable() is called for the device. 579151f4e2bSMauro Carvalho Chehab 580151f4e2bSMauro Carvalho ChehabHowever, if the device has a parent and the parent's runtime PM is enabled, 581151f4e2bSMauro Carvalho Chehabcalling pm_runtime_set_active() for the device will affect the parent, unless 582151f4e2bSMauro Carvalho Chehabthe parent's 'power.ignore_children' flag is set. Namely, in that case the 583151f4e2bSMauro Carvalho Chehabparent won't be able to suspend at run time, using the PM core's helper 584151f4e2bSMauro Carvalho Chehabfunctions, as long as the child's status is 'active', even if the child's 585151f4e2bSMauro Carvalho Chehabruntime PM is still disabled (i.e. pm_runtime_enable() hasn't been called for 586151f4e2bSMauro Carvalho Chehabthe child yet or pm_runtime_disable() has been called for it). For this reason, 587151f4e2bSMauro Carvalho Chehabonce pm_runtime_set_active() has been called for the device, pm_runtime_enable() 588151f4e2bSMauro Carvalho Chehabshould be called for it too as soon as reasonably possible or its runtime PM 589151f4e2bSMauro Carvalho Chehabstatus should be changed back to 'suspended' with the help of 590151f4e2bSMauro Carvalho Chehabpm_runtime_set_suspended(). 591151f4e2bSMauro Carvalho Chehab 592151f4e2bSMauro Carvalho ChehabIf the default initial runtime PM status of the device (i.e. 'suspended') 593151f4e2bSMauro Carvalho Chehabreflects the actual state of the device, its bus type's or its driver's 594151f4e2bSMauro Carvalho Chehab->probe() callback will likely need to wake it up using one of the PM core's 595151f4e2bSMauro Carvalho Chehabhelper functions described in Section 4. In that case, pm_runtime_resume() 596151f4e2bSMauro Carvalho Chehabshould be used. Of course, for this purpose the device's runtime PM has to be 597151f4e2bSMauro Carvalho Chehabenabled earlier by calling pm_runtime_enable(). 598151f4e2bSMauro Carvalho Chehab 599151f4e2bSMauro Carvalho ChehabNote, if the device may execute pm_runtime calls during the probe (such as 60030966309SBjorn Helgaasif it is registered with a subsystem that may call back in) then the 601151f4e2bSMauro Carvalho Chehabpm_runtime_get_sync() call paired with a pm_runtime_put() call will be 602151f4e2bSMauro Carvalho Chehabappropriate to ensure that the device is not put back to sleep during the 603151f4e2bSMauro Carvalho Chehabprobe. This can happen with systems such as the network device layer. 604151f4e2bSMauro Carvalho Chehab 605151f4e2bSMauro Carvalho ChehabIt may be desirable to suspend the device once ->probe() has finished. 606151f4e2bSMauro Carvalho ChehabTherefore the driver core uses the asynchronous pm_request_idle() to submit a 607151f4e2bSMauro Carvalho Chehabrequest to execute the subsystem-level idle callback for the device at that 60830966309SBjorn Helgaastime. A driver that makes use of the runtime autosuspend feature may want to 609151f4e2bSMauro Carvalho Chehabupdate the last busy mark before returning from ->probe(). 610151f4e2bSMauro Carvalho Chehab 611151f4e2bSMauro Carvalho ChehabMoreover, the driver core prevents runtime PM callbacks from racing with the bus 61230966309SBjorn Helgaasnotifier callback in __device_release_driver(), which is necessary because the 613151f4e2bSMauro Carvalho Chehabnotifier is used by some subsystems to carry out operations affecting the 614151f4e2bSMauro Carvalho Chehabruntime PM functionality. It does so by calling pm_runtime_get_sync() before 615151f4e2bSMauro Carvalho Chehabdriver_sysfs_remove() and the BUS_NOTIFY_UNBIND_DRIVER notifications. This 616151f4e2bSMauro Carvalho Chehabresumes the device if it's in the suspended state and prevents it from 617151f4e2bSMauro Carvalho Chehabbeing suspended again while those routines are being executed. 618151f4e2bSMauro Carvalho Chehab 619151f4e2bSMauro Carvalho ChehabTo allow bus types and drivers to put devices into the suspended state by 620151f4e2bSMauro Carvalho Chehabcalling pm_runtime_suspend() from their ->remove() routines, the driver core 621151f4e2bSMauro Carvalho Chehabexecutes pm_runtime_put_sync() after running the BUS_NOTIFY_UNBIND_DRIVER 622151f4e2bSMauro Carvalho Chehabnotifications in __device_release_driver(). This requires bus types and 623151f4e2bSMauro Carvalho Chehabdrivers to make their ->remove() callbacks avoid races with runtime PM directly, 62430966309SBjorn Helgaasbut it also allows more flexibility in the handling of devices during the 625151f4e2bSMauro Carvalho Chehabremoval of their drivers. 626151f4e2bSMauro Carvalho Chehab 627151f4e2bSMauro Carvalho ChehabDrivers in ->remove() callback should undo the runtime PM changes done 628151f4e2bSMauro Carvalho Chehabin ->probe(). Usually this means calling pm_runtime_disable(), 629151f4e2bSMauro Carvalho Chehabpm_runtime_dont_use_autosuspend() etc. 630151f4e2bSMauro Carvalho Chehab 631151f4e2bSMauro Carvalho ChehabThe user space can effectively disallow the driver of the device to power manage 632151f4e2bSMauro Carvalho Chehabit at run time by changing the value of its /sys/devices/.../power/control 633151f4e2bSMauro Carvalho Chehabattribute to "on", which causes pm_runtime_forbid() to be called. In principle, 634151f4e2bSMauro Carvalho Chehabthis mechanism may also be used by the driver to effectively turn off the 635151f4e2bSMauro Carvalho Chehabruntime power management of the device until the user space turns it on. 636151f4e2bSMauro Carvalho ChehabNamely, during the initialization the driver can make sure that the runtime PM 637151f4e2bSMauro Carvalho Chehabstatus of the device is 'active' and call pm_runtime_forbid(). It should be 638151f4e2bSMauro Carvalho Chehabnoted, however, that if the user space has already intentionally changed the 639151f4e2bSMauro Carvalho Chehabvalue of /sys/devices/.../power/control to "auto" to allow the driver to power 640151f4e2bSMauro Carvalho Chehabmanage the device at run time, the driver may confuse it by using 641151f4e2bSMauro Carvalho Chehabpm_runtime_forbid() this way. 642151f4e2bSMauro Carvalho Chehab 643151f4e2bSMauro Carvalho Chehab6. Runtime PM and System Sleep 644151f4e2bSMauro Carvalho Chehab============================== 645151f4e2bSMauro Carvalho Chehab 646151f4e2bSMauro Carvalho ChehabRuntime PM and system sleep (i.e., system suspend and hibernation, also known 647151f4e2bSMauro Carvalho Chehabas suspend-to-RAM and suspend-to-disk) interact with each other in a couple of 648151f4e2bSMauro Carvalho Chehabways. If a device is active when a system sleep starts, everything is 649151f4e2bSMauro Carvalho Chehabstraightforward. But what should happen if the device is already suspended? 650151f4e2bSMauro Carvalho Chehab 651151f4e2bSMauro Carvalho ChehabThe device may have different wake-up settings for runtime PM and system sleep. 652151f4e2bSMauro Carvalho ChehabFor example, remote wake-up may be enabled for runtime suspend but disallowed 653151f4e2bSMauro Carvalho Chehabfor system sleep (device_may_wakeup(dev) returns 'false'). When this happens, 654151f4e2bSMauro Carvalho Chehabthe subsystem-level system suspend callback is responsible for changing the 655151f4e2bSMauro Carvalho Chehabdevice's wake-up setting (it may leave that to the device driver's system 656151f4e2bSMauro Carvalho Chehabsuspend routine). It may be necessary to resume the device and suspend it again 657151f4e2bSMauro Carvalho Chehabin order to do so. The same is true if the driver uses different power levels 658151f4e2bSMauro Carvalho Chehabor other settings for runtime suspend and system sleep. 659151f4e2bSMauro Carvalho Chehab 660151f4e2bSMauro Carvalho ChehabDuring system resume, the simplest approach is to bring all devices back to full 661151f4e2bSMauro Carvalho Chehabpower, even if they had been suspended before the system suspend began. There 662151f4e2bSMauro Carvalho Chehabare several reasons for this, including: 663151f4e2bSMauro Carvalho Chehab 664151f4e2bSMauro Carvalho Chehab * The device might need to switch power levels, wake-up settings, etc. 665151f4e2bSMauro Carvalho Chehab 666151f4e2bSMauro Carvalho Chehab * Remote wake-up events might have been lost by the firmware. 667151f4e2bSMauro Carvalho Chehab 668151f4e2bSMauro Carvalho Chehab * The device's children may need the device to be at full power in order 669151f4e2bSMauro Carvalho Chehab to resume themselves. 670151f4e2bSMauro Carvalho Chehab 671151f4e2bSMauro Carvalho Chehab * The driver's idea of the device state may not agree with the device's 672151f4e2bSMauro Carvalho Chehab physical state. This can happen during resume from hibernation. 673151f4e2bSMauro Carvalho Chehab 674151f4e2bSMauro Carvalho Chehab * The device might need to be reset. 675151f4e2bSMauro Carvalho Chehab 676151f4e2bSMauro Carvalho Chehab * Even though the device was suspended, if its usage counter was > 0 then most 677151f4e2bSMauro Carvalho Chehab likely it would need a runtime resume in the near future anyway. 678151f4e2bSMauro Carvalho Chehab 679151f4e2bSMauro Carvalho ChehabIf the device had been suspended before the system suspend began and it's 680151f4e2bSMauro Carvalho Chehabbrought back to full power during resume, then its runtime PM status will have 681151f4e2bSMauro Carvalho Chehabto be updated to reflect the actual post-system sleep status. The way to do 682151f4e2bSMauro Carvalho Chehabthis is: 683151f4e2bSMauro Carvalho Chehab 684151f4e2bSMauro Carvalho Chehab - pm_runtime_disable(dev); 685151f4e2bSMauro Carvalho Chehab - pm_runtime_set_active(dev); 686151f4e2bSMauro Carvalho Chehab - pm_runtime_enable(dev); 687151f4e2bSMauro Carvalho Chehab 688151f4e2bSMauro Carvalho ChehabThe PM core always increments the runtime usage counter before calling the 689151f4e2bSMauro Carvalho Chehab->suspend() callback and decrements it after calling the ->resume() callback. 690151f4e2bSMauro Carvalho ChehabHence disabling runtime PM temporarily like this will not cause any runtime 691151f4e2bSMauro Carvalho Chehabsuspend attempts to be permanently lost. If the usage count goes to zero 692151f4e2bSMauro Carvalho Chehabfollowing the return of the ->resume() callback, the ->runtime_idle() callback 693151f4e2bSMauro Carvalho Chehabwill be invoked as usual. 694151f4e2bSMauro Carvalho Chehab 695151f4e2bSMauro Carvalho ChehabOn some systems, however, system sleep is not entered through a global firmware 696151f4e2bSMauro Carvalho Chehabor hardware operation. Instead, all hardware components are put into low-power 697151f4e2bSMauro Carvalho Chehabstates directly by the kernel in a coordinated way. Then, the system sleep 698151f4e2bSMauro Carvalho Chehabstate effectively follows from the states the hardware components end up in 699151f4e2bSMauro Carvalho Chehaband the system is woken up from that state by a hardware interrupt or a similar 700151f4e2bSMauro Carvalho Chehabmechanism entirely under the kernel's control. As a result, the kernel never 701151f4e2bSMauro Carvalho Chehabgives control away and the states of all devices during resume are precisely 702151f4e2bSMauro Carvalho Chehabknown to it. If that is the case and none of the situations listed above takes 703151f4e2bSMauro Carvalho Chehabplace (in particular, if the system is not waking up from hibernation), it may 704151f4e2bSMauro Carvalho Chehabbe more efficient to leave the devices that had been suspended before the system 705151f4e2bSMauro Carvalho Chehabsuspend began in the suspended state. 706151f4e2bSMauro Carvalho Chehab 707151f4e2bSMauro Carvalho ChehabTo this end, the PM core provides a mechanism allowing some coordination between 708151f4e2bSMauro Carvalho Chehabdifferent levels of device hierarchy. Namely, if a system suspend .prepare() 709151f4e2bSMauro Carvalho Chehabcallback returns a positive number for a device, that indicates to the PM core 710151f4e2bSMauro Carvalho Chehabthat the device appears to be runtime-suspended and its state is fine, so it 711151f4e2bSMauro Carvalho Chehabmay be left in runtime suspend provided that all of its descendants are also 712151f4e2bSMauro Carvalho Chehableft in runtime suspend. If that happens, the PM core will not execute any 713151f4e2bSMauro Carvalho Chehabsystem suspend and resume callbacks for all of those devices, except for the 71430966309SBjorn Helgaas.complete() callback, which is then entirely responsible for handling the device 715151f4e2bSMauro Carvalho Chehabas appropriate. This only applies to system suspend transitions that are not 716151f4e2bSMauro Carvalho Chehabrelated to hibernation (see Documentation/driver-api/pm/devices.rst for more 717151f4e2bSMauro Carvalho Chehabinformation). 718151f4e2bSMauro Carvalho Chehab 719151f4e2bSMauro Carvalho ChehabThe PM core does its best to reduce the probability of race conditions between 720151f4e2bSMauro Carvalho Chehabthe runtime PM and system suspend/resume (and hibernation) callbacks by carrying 721151f4e2bSMauro Carvalho Chehabout the following operations: 722151f4e2bSMauro Carvalho Chehab 723151f4e2bSMauro Carvalho Chehab * During system suspend pm_runtime_get_noresume() is called for every device 724151f4e2bSMauro Carvalho Chehab right before executing the subsystem-level .prepare() callback for it and 725151f4e2bSMauro Carvalho Chehab pm_runtime_barrier() is called for every device right before executing the 726151f4e2bSMauro Carvalho Chehab subsystem-level .suspend() callback for it. In addition to that the PM core 727151f4e2bSMauro Carvalho Chehab calls __pm_runtime_disable() with 'false' as the second argument for every 728151f4e2bSMauro Carvalho Chehab device right before executing the subsystem-level .suspend_late() callback 729151f4e2bSMauro Carvalho Chehab for it. 730151f4e2bSMauro Carvalho Chehab 731151f4e2bSMauro Carvalho Chehab * During system resume pm_runtime_enable() and pm_runtime_put() are called for 732151f4e2bSMauro Carvalho Chehab every device right after executing the subsystem-level .resume_early() 733151f4e2bSMauro Carvalho Chehab callback and right after executing the subsystem-level .complete() callback 734151f4e2bSMauro Carvalho Chehab for it, respectively. 735151f4e2bSMauro Carvalho Chehab 736151f4e2bSMauro Carvalho Chehab7. Generic subsystem callbacks 737*e6509568SYiwei Lin============================== 738151f4e2bSMauro Carvalho Chehab 739151f4e2bSMauro Carvalho ChehabSubsystems may wish to conserve code space by using the set of generic power 740151f4e2bSMauro Carvalho Chehabmanagement callbacks provided by the PM core, defined in 741151f4e2bSMauro Carvalho Chehabdriver/base/power/generic_ops.c: 742151f4e2bSMauro Carvalho Chehab 743151f4e2bSMauro Carvalho Chehab `int pm_generic_runtime_suspend(struct device *dev);` 744151f4e2bSMauro Carvalho Chehab - invoke the ->runtime_suspend() callback provided by the driver of this 745151f4e2bSMauro Carvalho Chehab device and return its result, or return 0 if not defined 746151f4e2bSMauro Carvalho Chehab 747151f4e2bSMauro Carvalho Chehab `int pm_generic_runtime_resume(struct device *dev);` 748151f4e2bSMauro Carvalho Chehab - invoke the ->runtime_resume() callback provided by the driver of this 749151f4e2bSMauro Carvalho Chehab device and return its result, or return 0 if not defined 750151f4e2bSMauro Carvalho Chehab 751151f4e2bSMauro Carvalho Chehab `int pm_generic_suspend(struct device *dev);` 752151f4e2bSMauro Carvalho Chehab - if the device has not been suspended at run time, invoke the ->suspend() 753151f4e2bSMauro Carvalho Chehab callback provided by its driver and return its result, or return 0 if not 754151f4e2bSMauro Carvalho Chehab defined 755151f4e2bSMauro Carvalho Chehab 756151f4e2bSMauro Carvalho Chehab `int pm_generic_suspend_noirq(struct device *dev);` 757151f4e2bSMauro Carvalho Chehab - if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq() 758151f4e2bSMauro Carvalho Chehab callback provided by the device's driver and return its result, or return 759151f4e2bSMauro Carvalho Chehab 0 if not defined 760151f4e2bSMauro Carvalho Chehab 761151f4e2bSMauro Carvalho Chehab `int pm_generic_resume(struct device *dev);` 762151f4e2bSMauro Carvalho Chehab - invoke the ->resume() callback provided by the driver of this device and, 763151f4e2bSMauro Carvalho Chehab if successful, change the device's runtime PM status to 'active' 764151f4e2bSMauro Carvalho Chehab 765151f4e2bSMauro Carvalho Chehab `int pm_generic_resume_noirq(struct device *dev);` 766151f4e2bSMauro Carvalho Chehab - invoke the ->resume_noirq() callback provided by the driver of this device 767151f4e2bSMauro Carvalho Chehab 768151f4e2bSMauro Carvalho Chehab `int pm_generic_freeze(struct device *dev);` 769151f4e2bSMauro Carvalho Chehab - if the device has not been suspended at run time, invoke the ->freeze() 770151f4e2bSMauro Carvalho Chehab callback provided by its driver and return its result, or return 0 if not 771151f4e2bSMauro Carvalho Chehab defined 772151f4e2bSMauro Carvalho Chehab 773151f4e2bSMauro Carvalho Chehab `int pm_generic_freeze_noirq(struct device *dev);` 774151f4e2bSMauro Carvalho Chehab - if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq() 775151f4e2bSMauro Carvalho Chehab callback provided by the device's driver and return its result, or return 776151f4e2bSMauro Carvalho Chehab 0 if not defined 777151f4e2bSMauro Carvalho Chehab 778151f4e2bSMauro Carvalho Chehab `int pm_generic_thaw(struct device *dev);` 779151f4e2bSMauro Carvalho Chehab - if the device has not been suspended at run time, invoke the ->thaw() 780151f4e2bSMauro Carvalho Chehab callback provided by its driver and return its result, or return 0 if not 781151f4e2bSMauro Carvalho Chehab defined 782151f4e2bSMauro Carvalho Chehab 783151f4e2bSMauro Carvalho Chehab `int pm_generic_thaw_noirq(struct device *dev);` 784151f4e2bSMauro Carvalho Chehab - if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq() 785151f4e2bSMauro Carvalho Chehab callback provided by the device's driver and return its result, or return 786151f4e2bSMauro Carvalho Chehab 0 if not defined 787151f4e2bSMauro Carvalho Chehab 788151f4e2bSMauro Carvalho Chehab `int pm_generic_poweroff(struct device *dev);` 789151f4e2bSMauro Carvalho Chehab - if the device has not been suspended at run time, invoke the ->poweroff() 790151f4e2bSMauro Carvalho Chehab callback provided by its driver and return its result, or return 0 if not 791151f4e2bSMauro Carvalho Chehab defined 792151f4e2bSMauro Carvalho Chehab 793151f4e2bSMauro Carvalho Chehab `int pm_generic_poweroff_noirq(struct device *dev);` 794151f4e2bSMauro Carvalho Chehab - if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq() 795151f4e2bSMauro Carvalho Chehab callback provided by the device's driver and return its result, or return 796151f4e2bSMauro Carvalho Chehab 0 if not defined 797151f4e2bSMauro Carvalho Chehab 798151f4e2bSMauro Carvalho Chehab `int pm_generic_restore(struct device *dev);` 799151f4e2bSMauro Carvalho Chehab - invoke the ->restore() callback provided by the driver of this device and, 800151f4e2bSMauro Carvalho Chehab if successful, change the device's runtime PM status to 'active' 801151f4e2bSMauro Carvalho Chehab 802151f4e2bSMauro Carvalho Chehab `int pm_generic_restore_noirq(struct device *dev);` 803151f4e2bSMauro Carvalho Chehab - invoke the ->restore_noirq() callback provided by the device's driver 804151f4e2bSMauro Carvalho Chehab 80530966309SBjorn HelgaasThese functions are the defaults used by the PM core if a subsystem doesn't 806151f4e2bSMauro Carvalho Chehabprovide its own callbacks for ->runtime_idle(), ->runtime_suspend(), 807151f4e2bSMauro Carvalho Chehab->runtime_resume(), ->suspend(), ->suspend_noirq(), ->resume(), 808151f4e2bSMauro Carvalho Chehab->resume_noirq(), ->freeze(), ->freeze_noirq(), ->thaw(), ->thaw_noirq(), 809151f4e2bSMauro Carvalho Chehab->poweroff(), ->poweroff_noirq(), ->restore(), ->restore_noirq() in the 810151f4e2bSMauro Carvalho Chehabsubsystem-level dev_pm_ops structure. 811151f4e2bSMauro Carvalho Chehab 812151f4e2bSMauro Carvalho ChehabDevice drivers that wish to use the same function as a system suspend, freeze, 813151f4e2bSMauro Carvalho Chehabpoweroff and runtime suspend callback, and similarly for system resume, thaw, 814151f4e2bSMauro Carvalho Chehabrestore, and runtime resume, can achieve this with the help of the 815151f4e2bSMauro Carvalho ChehabUNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its 816151f4e2bSMauro Carvalho Chehablast argument to NULL). 817151f4e2bSMauro Carvalho Chehab 818151f4e2bSMauro Carvalho Chehab8. "No-Callback" Devices 819151f4e2bSMauro Carvalho Chehab======================== 820151f4e2bSMauro Carvalho Chehab 821151f4e2bSMauro Carvalho ChehabSome "devices" are only logical sub-devices of their parent and cannot be 822151f4e2bSMauro Carvalho Chehabpower-managed on their own. (The prototype example is a USB interface. Entire 823151f4e2bSMauro Carvalho ChehabUSB devices can go into low-power mode or send wake-up requests, but neither is 824151f4e2bSMauro Carvalho Chehabpossible for individual interfaces.) The drivers for these devices have no 825151f4e2bSMauro Carvalho Chehabneed of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend() 826151f4e2bSMauro Carvalho Chehaband ->runtime_resume() would always return 0 without doing anything else and 827151f4e2bSMauro Carvalho Chehab->runtime_idle() would always call pm_runtime_suspend(). 828151f4e2bSMauro Carvalho Chehab 829151f4e2bSMauro Carvalho ChehabSubsystems can tell the PM core about these devices by calling 830151f4e2bSMauro Carvalho Chehabpm_runtime_no_callbacks(). This should be done after the device structure is 831151f4e2bSMauro Carvalho Chehabinitialized and before it is registered (although after device registration is 832151f4e2bSMauro Carvalho Chehabalso okay). The routine will set the device's power.no_callbacks flag and 833151f4e2bSMauro Carvalho Chehabprevent the non-debugging runtime PM sysfs attributes from being created. 834151f4e2bSMauro Carvalho Chehab 835151f4e2bSMauro Carvalho ChehabWhen power.no_callbacks is set, the PM core will not invoke the 836151f4e2bSMauro Carvalho Chehab->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks. 837151f4e2bSMauro Carvalho ChehabInstead it will assume that suspends and resumes always succeed and that idle 838151f4e2bSMauro Carvalho Chehabdevices should be suspended. 839151f4e2bSMauro Carvalho Chehab 840151f4e2bSMauro Carvalho ChehabAs a consequence, the PM core will never directly inform the device's subsystem 841151f4e2bSMauro Carvalho Chehabor driver about runtime power changes. Instead, the driver for the device's 842151f4e2bSMauro Carvalho Chehabparent must take responsibility for telling the device's driver when the 843151f4e2bSMauro Carvalho Chehabparent's power state changes. 844151f4e2bSMauro Carvalho Chehab 8454ec4f059SUlf HanssonNote that, in some cases it may not be desirable for subsystems/drivers to call 8464ec4f059SUlf Hanssonpm_runtime_no_callbacks() for their devices. This could be because a subset of 8474ec4f059SUlf Hanssonthe runtime PM callbacks needs to be implemented, a platform dependent PM 8484ec4f059SUlf Hanssondomain could get attached to the device or that the device is power managed 8494ec4f059SUlf Hanssonthrough a supplier device link. For these reasons and to avoid boilerplate code 8504ec4f059SUlf Hanssonin subsystems/drivers, the PM core allows runtime PM callbacks to be 8514ec4f059SUlf Hanssonunassigned. More precisely, if a callback pointer is NULL, the PM core will act 8524ec4f059SUlf Hanssonas though there was a callback and it returned 0. 8534ec4f059SUlf Hansson 854151f4e2bSMauro Carvalho Chehab9. Autosuspend, or automatically-delayed suspends 855151f4e2bSMauro Carvalho Chehab================================================= 856151f4e2bSMauro Carvalho Chehab 857151f4e2bSMauro Carvalho ChehabChanging a device's power state isn't free; it requires both time and energy. 858151f4e2bSMauro Carvalho ChehabA device should be put in a low-power state only when there's some reason to 859151f4e2bSMauro Carvalho Chehabthink it will remain in that state for a substantial time. A common heuristic 860151f4e2bSMauro Carvalho Chehabsays that a device which hasn't been used for a while is liable to remain 861151f4e2bSMauro Carvalho Chehabunused; following this advice, drivers should not allow devices to be suspended 862151f4e2bSMauro Carvalho Chehabat runtime until they have been inactive for some minimum period. Even when 863151f4e2bSMauro Carvalho Chehabthe heuristic ends up being non-optimal, it will still prevent devices from 864151f4e2bSMauro Carvalho Chehab"bouncing" too rapidly between low-power and full-power states. 865151f4e2bSMauro Carvalho Chehab 866151f4e2bSMauro Carvalho ChehabThe term "autosuspend" is an historical remnant. It doesn't mean that the 867151f4e2bSMauro Carvalho Chehabdevice is automatically suspended (the subsystem or driver still has to call 868151f4e2bSMauro Carvalho Chehabthe appropriate PM routines); rather it means that runtime suspends will 869151f4e2bSMauro Carvalho Chehabautomatically be delayed until the desired period of inactivity has elapsed. 870151f4e2bSMauro Carvalho Chehab 871151f4e2bSMauro Carvalho ChehabInactivity is determined based on the power.last_busy field. Drivers should 872151f4e2bSMauro Carvalho Chehabcall pm_runtime_mark_last_busy() to update this field after carrying out I/O, 873b7d46644SSakari Ailustypically just before calling __pm_runtime_put_autosuspend(). The desired 874b7d46644SSakari Ailuslength of the inactivity period is a matter of policy. Subsystems can set this 875b7d46644SSakari Ailuslength initially by calling pm_runtime_set_autosuspend_delay(), but after device 876151f4e2bSMauro Carvalho Chehabregistration the length should be controlled by user space, using the 877151f4e2bSMauro Carvalho Chehab/sys/devices/.../power/autosuspend_delay_ms attribute. 878151f4e2bSMauro Carvalho Chehab 879151f4e2bSMauro Carvalho ChehabIn order to use autosuspend, subsystems or drivers must call 880151f4e2bSMauro Carvalho Chehabpm_runtime_use_autosuspend() (preferably before registering the device), and 881151f4e2bSMauro Carvalho Chehabthereafter they should use the various `*_autosuspend()` helper functions 882151f4e2bSMauro Carvalho Chehabinstead of the non-autosuspend counterparts:: 883151f4e2bSMauro Carvalho Chehab 884151f4e2bSMauro Carvalho Chehab Instead of: pm_runtime_suspend use: pm_runtime_autosuspend; 885151f4e2bSMauro Carvalho Chehab Instead of: pm_schedule_suspend use: pm_request_autosuspend; 886b7d46644SSakari Ailus Instead of: pm_runtime_put use: __pm_runtime_put_autosuspend; 887151f4e2bSMauro Carvalho Chehab Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend. 888151f4e2bSMauro Carvalho Chehab 889151f4e2bSMauro Carvalho ChehabDrivers may also continue to use the non-autosuspend helper functions; they 890151f4e2bSMauro Carvalho Chehabwill behave normally, which means sometimes taking the autosuspend delay into 891151f4e2bSMauro Carvalho Chehabaccount (see pm_runtime_idle). 892151f4e2bSMauro Carvalho Chehab 893151f4e2bSMauro Carvalho ChehabUnder some circumstances a driver or subsystem may want to prevent a device 894151f4e2bSMauro Carvalho Chehabfrom autosuspending immediately, even though the usage counter is zero and the 895151f4e2bSMauro Carvalho Chehabautosuspend delay time has expired. If the ->runtime_suspend() callback 896151f4e2bSMauro Carvalho Chehabreturns -EAGAIN or -EBUSY, and if the next autosuspend delay expiration time is 897151f4e2bSMauro Carvalho Chehabin the future (as it normally would be if the callback invoked 898151f4e2bSMauro Carvalho Chehabpm_runtime_mark_last_busy()), the PM core will automatically reschedule the 899151f4e2bSMauro Carvalho Chehabautosuspend. The ->runtime_suspend() callback can't do this rescheduling 900151f4e2bSMauro Carvalho Chehabitself because no suspend requests of any kind are accepted while the device is 901151f4e2bSMauro Carvalho Chehabsuspending (i.e., while the callback is running). 902151f4e2bSMauro Carvalho Chehab 903151f4e2bSMauro Carvalho ChehabThe implementation is well suited for asynchronous use in interrupt contexts. 904151f4e2bSMauro Carvalho ChehabHowever such use inevitably involves races, because the PM core can't 905151f4e2bSMauro Carvalho Chehabsynchronize ->runtime_suspend() callbacks with the arrival of I/O requests. 906151f4e2bSMauro Carvalho ChehabThis synchronization must be handled by the driver, using its private lock. 907151f4e2bSMauro Carvalho ChehabHere is a schematic pseudo-code example:: 908151f4e2bSMauro Carvalho Chehab 909151f4e2bSMauro Carvalho Chehab foo_read_or_write(struct foo_priv *foo, void *data) 910151f4e2bSMauro Carvalho Chehab { 911151f4e2bSMauro Carvalho Chehab lock(&foo->private_lock); 912151f4e2bSMauro Carvalho Chehab add_request_to_io_queue(foo, data); 913151f4e2bSMauro Carvalho Chehab if (foo->num_pending_requests++ == 0) 914151f4e2bSMauro Carvalho Chehab pm_runtime_get(&foo->dev); 915151f4e2bSMauro Carvalho Chehab if (!foo->is_suspended) 916151f4e2bSMauro Carvalho Chehab foo_process_next_request(foo); 917151f4e2bSMauro Carvalho Chehab unlock(&foo->private_lock); 918151f4e2bSMauro Carvalho Chehab } 919151f4e2bSMauro Carvalho Chehab 920151f4e2bSMauro Carvalho Chehab foo_io_completion(struct foo_priv *foo, void *req) 921151f4e2bSMauro Carvalho Chehab { 922151f4e2bSMauro Carvalho Chehab lock(&foo->private_lock); 923151f4e2bSMauro Carvalho Chehab if (--foo->num_pending_requests == 0) { 924151f4e2bSMauro Carvalho Chehab pm_runtime_mark_last_busy(&foo->dev); 925b7d46644SSakari Ailus __pm_runtime_put_autosuspend(&foo->dev); 926151f4e2bSMauro Carvalho Chehab } else { 927151f4e2bSMauro Carvalho Chehab foo_process_next_request(foo); 928151f4e2bSMauro Carvalho Chehab } 929151f4e2bSMauro Carvalho Chehab unlock(&foo->private_lock); 930151f4e2bSMauro Carvalho Chehab /* Send req result back to the user ... */ 931151f4e2bSMauro Carvalho Chehab } 932151f4e2bSMauro Carvalho Chehab 933151f4e2bSMauro Carvalho Chehab int foo_runtime_suspend(struct device *dev) 934151f4e2bSMauro Carvalho Chehab { 935151f4e2bSMauro Carvalho Chehab struct foo_priv foo = container_of(dev, ...); 936151f4e2bSMauro Carvalho Chehab int ret = 0; 937151f4e2bSMauro Carvalho Chehab 938151f4e2bSMauro Carvalho Chehab lock(&foo->private_lock); 939151f4e2bSMauro Carvalho Chehab if (foo->num_pending_requests > 0) { 940151f4e2bSMauro Carvalho Chehab ret = -EBUSY; 941151f4e2bSMauro Carvalho Chehab } else { 942151f4e2bSMauro Carvalho Chehab /* ... suspend the device ... */ 943151f4e2bSMauro Carvalho Chehab foo->is_suspended = 1; 944151f4e2bSMauro Carvalho Chehab } 945151f4e2bSMauro Carvalho Chehab unlock(&foo->private_lock); 946151f4e2bSMauro Carvalho Chehab return ret; 947151f4e2bSMauro Carvalho Chehab } 948151f4e2bSMauro Carvalho Chehab 949151f4e2bSMauro Carvalho Chehab int foo_runtime_resume(struct device *dev) 950151f4e2bSMauro Carvalho Chehab { 951151f4e2bSMauro Carvalho Chehab struct foo_priv foo = container_of(dev, ...); 952151f4e2bSMauro Carvalho Chehab 953151f4e2bSMauro Carvalho Chehab lock(&foo->private_lock); 954151f4e2bSMauro Carvalho Chehab /* ... resume the device ... */ 955151f4e2bSMauro Carvalho Chehab foo->is_suspended = 0; 956151f4e2bSMauro Carvalho Chehab pm_runtime_mark_last_busy(&foo->dev); 957151f4e2bSMauro Carvalho Chehab if (foo->num_pending_requests > 0) 958151f4e2bSMauro Carvalho Chehab foo_process_next_request(foo); 959151f4e2bSMauro Carvalho Chehab unlock(&foo->private_lock); 960151f4e2bSMauro Carvalho Chehab return 0; 961151f4e2bSMauro Carvalho Chehab } 962151f4e2bSMauro Carvalho Chehab 963151f4e2bSMauro Carvalho ChehabThe important point is that after foo_io_completion() asks for an autosuspend, 964151f4e2bSMauro Carvalho Chehabthe foo_runtime_suspend() callback may race with foo_read_or_write(). 965151f4e2bSMauro Carvalho ChehabTherefore foo_runtime_suspend() has to check whether there are any pending I/O 966151f4e2bSMauro Carvalho Chehabrequests (while holding the private lock) before allowing the suspend to 967151f4e2bSMauro Carvalho Chehabproceed. 968151f4e2bSMauro Carvalho Chehab 969151f4e2bSMauro Carvalho ChehabIn addition, the power.autosuspend_delay field can be changed by user space at 970151f4e2bSMauro Carvalho Chehabany time. If a driver cares about this, it can call 971151f4e2bSMauro Carvalho Chehabpm_runtime_autosuspend_expiration() from within the ->runtime_suspend() 972151f4e2bSMauro Carvalho Chehabcallback while holding its private lock. If the function returns a nonzero 973151f4e2bSMauro Carvalho Chehabvalue then the delay has not yet expired and the callback should return 974151f4e2bSMauro Carvalho Chehab-EAGAIN. 975