kernel/power/pm.c

   1 /*
   2  *  pm.c - Power management interface
   3  *
   4  *  Copyright (C) 2000 Andrew Henroid
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19  */
  20 #include <linux/init.h>
  21 #include <linux/module.h>
  22 #include <linux/spinlock.h>
  23 #include <linux/mm.h>
  24 #include <linux/slab.h>
  25 #include <linux/pm.h>
  26 #include <linux/pm_legacy.h>
  27 #include <linux/interrupt.h>
  28 #include <linux/mutex.h>
  29
  30 int pm_active;
  31
  32 /*
  33  *      Locking notes:
  34  *              pm_devs_lock can be a semaphore providing pm ops are not called
  35  *      from an interrupt handler (already a bad idea so no change here). Each
  36  *      change must be protected so that an unlink of an entry doesn't clash
  37  *      with a pm send - which is permitted to sleep in the current architecture
  38  *
  39  *      Module unloads clashing with pm events now work out safely, the module
  40  *      unload path will block until the event has been sent. It may well block
  41  *      until a resume but that will be fine.
  42  */
  43
  44 static DEFINE_MUTEX(pm_devs_lock);
  45 static LIST_HEAD(pm_devs);
  46
  47 /**
  48  *      pm_register - register a device with power management
  49  *      @type: device type
  50  *      @id: device ID
  51  *      @callback: callback function
  52  *
  53  *      Add a device to the list of devices that wish to be notified about
  54  *      power management events. A &pm_dev structure is returned on success,
  55  *      on failure the return is %NULL.
  56  *
  57  *      The callback function will be called in process context and
  58  *      it may sleep.
  59  */
  60
  61 struct pm_dev *pm_register(pm_dev_t type,
  62                            unsigned long id,
  63                            pm_callback callback)
  64 {
  65         struct pm_dev *dev = kzalloc(sizeof(struct pm_dev), GFP_KERNEL);
  66         if (dev) {
  67                 dev->type = type;
  68                 dev->id = id;
  69                 dev->callback = callback;
  70
  71                 mutex_lock(&pm_devs_lock);
  72                 list_add(&dev->entry, &pm_devs);
  73                 mutex_unlock(&pm_devs_lock);
  74         }
  75         return dev;
  76 }
  77
  78 /**
  79  *      pm_unregister -  unregister a device with power management
  80  *      @dev: device to unregister
  81  *
  82  *      Remove a device from the power management notification lists. The
  83  *      dev passed must be a handle previously returned by pm_register.
  84  */
  85
  86 void pm_unregister(struct pm_dev *dev)
  87 {
  88         if (dev) {
  89                 mutex_lock(&pm_devs_lock);
  90                 list_del(&dev->entry);
  91                 mutex_unlock(&pm_devs_lock);
  92
  93                 kfree(dev);
  94         }
  95 }
  96
  97 static void __pm_unregister(struct pm_dev *dev)
  98 {
  99         if (dev) {
 100                 list_del(&dev->entry);
 101                 kfree(dev);
 102         }
 103 }
 104
 105 /**
 106  *      pm_unregister_all - unregister all devices with matching callback
 107  *      @callback: callback function pointer
 108  *
 109  *      Unregister every device that would call the callback passed. This
 110  *      is primarily meant as a helper function for loadable modules. It
 111  *      enables a module to give up all its managed devices without keeping
 112  *      its own private list.
 113  */
 114
 115 void pm_unregister_all(pm_callback callback)
 116 {
 117         struct list_head *entry;
 118
 119         if (!callback)
 120                 return;
 121
 122         mutex_lock(&pm_devs_lock);
 123         entry = pm_devs.next;
 124         while (entry != &pm_devs) {
 125                 struct pm_dev *dev = list_entry(entry, struct pm_dev, entry);
 126                 entry = entry->next;
 127                 if (dev->callback == callback)
 128                         __pm_unregister(dev);
 129         }
 130         mutex_unlock(&pm_devs_lock);
 131 }
 132
 133 /**
 134  *      pm_send - send request to a single device
 135  *      @dev: device to send to
 136  *      @rqst: power management request
 137  *      @data: data for the callback
 138  *
 139  *      Issue a power management request to a given device. The
 140  *      %PM_SUSPEND and %PM_RESUME events are handled specially. The
 141  *      data field must hold the intended next state. No call is made
 142  *      if the state matches.
 143  *
 144  *      BUGS: what stops two power management requests occurring in parallel
 145  *      and conflicting.
 146  *
 147  *      WARNING: Calling pm_send directly is not generally recommended, in
 148  *      particular there is no locking against the pm_dev going away. The
 149  *      caller must maintain all needed locking or have 'inside knowledge'
 150  *      on the safety. Also remember that this function is not locked against
 151  *      pm_unregister. This means that you must handle SMP races on callback
 152  *      execution and unload yourself.
 153  */
 154
 155 static int pm_send(struct pm_dev *dev, pm_request_t rqst, void *data)
 156 {
 157         int status = 0;
 158         unsigned long prev_state, next_state;
 159
 160         if (in_interrupt())
 161                 BUG();
 162
 163         switch (rqst) {
 164         case PM_SUSPEND:
 165         case PM_RESUME:
 166                 prev_state = dev->state;
 167                 next_state = (unsigned long) data;
 168                 if (prev_state != next_state) {
 169                         if (dev->callback)
 170                                 status = (*dev->callback)(dev, rqst, data);
 171                         if (!status) {
 172                                 dev->state = next_state;
 173                                 dev->prev_state = prev_state;
 174                         }
 175                 }
 176                 else {
 177                         dev->prev_state = prev_state;
 178                 }
 179                 break;
 180         default:
 181                 if (dev->callback)
 182                         status = (*dev->callback)(dev, rqst, data);
 183                 break;
 184         }
 185         return status;
 186 }
 187
 188 /*
 189  * Undo incomplete request
 190  */
 191 static void pm_undo_all(struct pm_dev *last)
 192 {
 193         struct list_head *entry = last->entry.prev;
 194         while (entry != &pm_devs) {
 195                 struct pm_dev *dev = list_entry(entry, struct pm_dev, entry);
 196                 if (dev->state != dev->prev_state) {
 197                         /* previous state was zero (running) resume or
 198                          * previous state was non-zero (suspended) suspend
 199                          */
 200                         pm_request_t undo = (dev->prev_state
 201                                              ? PM_SUSPEND:PM_RESUME);
 202                         pm_send(dev, undo, (void*) dev->prev_state);
 203                 }
 204                 entry = entry->prev;
 205         }
 206 }
 207
 208 /**
 209  *      pm_send_all - send request to all managed devices
 210  *      @rqst: power management request
 211  *      @data: data for the callback
 212  *
 213  *      Issue a power management request to a all devices. The
 214  *      %PM_SUSPEND events are handled specially. Any device is
 215  *      permitted to fail a suspend by returning a non zero (error)
 216  *      value from its callback function. If any device vetoes a
 217  *      suspend request then all other devices that have suspended
 218  *      during the processing of this request are restored to their
 219  *      previous state.
 220  *
 221  *      WARNING:  This function takes the pm_devs_lock. The lock is not dropped until
 222  *      the callbacks have completed. This prevents races against pm locking
 223  *      functions, races against module unload pm_unregister code. It does
 224  *      mean however that you must not issue pm_ functions within the callback
 225  *      or you will deadlock and users will hate you.
 226  *
 227  *      Zero is returned on success. If a suspend fails then the status
 228  *      from the device that vetoes the suspend is returned.
 229  *
 230  *      BUGS: what stops two power management requests occurring in parallel
 231  *      and conflicting.
 232  */
 233
 234 int pm_send_all(pm_request_t rqst, void *data)
 235 {
 236         struct list_head *entry;
 237
 238         mutex_lock(&pm_devs_lock);
 239         entry = pm_devs.next;
 240         while (entry != &pm_devs) {
 241                 struct pm_dev *dev = list_entry(entry, struct pm_dev, entry);
 242                 if (dev->callback) {
 243                         int status = pm_send(dev, rqst, data);
 244                         if (status) {
 245                                 /* return devices to previous state on
 246                                  * failed suspend request
 247                                  */
 248                                 if (rqst == PM_SUSPEND)
 249                                         pm_undo_all(dev);
 250                                 mutex_unlock(&pm_devs_lock);
 251                                 return status;
 252                         }
 253                 }
 254                 entry = entry->next;
 255         }
 256         mutex_unlock(&pm_devs_lock);
 257         return 0;
 258 }
 259
 260 EXPORT_SYMBOL(pm_register);
 261 EXPORT_SYMBOL(pm_unregister);
 262 EXPORT_SYMBOL(pm_unregister_all);
 263 EXPORT_SYMBOL(pm_send_all);
 264 EXPORT_SYMBOL(pm_active);
 265
 266