patch-2.3.48 linux/Documentation/pm.txt

• Lines: 155
• Date: Wed Feb 23 20:05:12 2000
• Orig file: v2.3.47/linux/Documentation/pm.txt
• Orig date: Thu Feb 10 17:11:02 2000

diff -u --recursive --new-file v2.3.47/linux/Documentation/pm.txt linux/Documentation/pm.txt
@@ -164,3 +164,154 @@
  *          access the device hardware until a call to "pm_access" is made.
  */
 typedef int (*pm_callback)(struct pm_dev *dev, pm_request_t rqst, void *data);
+
+Driver Details
+--------------
+This is just a quick Q&A as a stopgap until a real driver writers'
+power management guide is available.
+
+Q: When is a device suspended?
+
+Devices can be suspended based on direct user request (eg. laptop lid
+closes), system power policy (eg.  sleep after 30 minutes of console
+inactivity), or device power policy (eg. power down device after 5
+minutes of inactivity)
+
+Q: Must a driver honor a suspend request?
+
+No, a driver can return -EBUSY from a suspend request and this
+will stop the system from suspending.  When a suspend request
+fails, all suspended devices are resumed and the system continues
+to run.  Suspend can be retried at a later time.
+
+Q: Can the driver block suspend/resume requests?
+
+Yes, a driver can delay its return from a suspend or resume
+request until the device is ready to handle requests.  It
+is advantageous to return as quickly as possible from a
+request as suspend/resume are done serially.
+
+Q: What context is a suspend/resume initiated from?
+
+A suspend or resume is initiated from a kernel thread context.
+It is safe to block, allocate memory, initiate requests
+or anything else you can do within the kernel.
+
+Q: Will requests continue to arrive after a suspend?
+
+Possibly.  It is the driver's responsibility to queue(*),
+fail, or drop any requests that arrive after returning
+success to a suspend request.  It is important that the
+driver not access its device until after it receives
+a resume request as the device's bus may no longer
+be active.
+
+(*) If a driver queues requests for processing after
+    resume be aware that the device, network, etc.
+    might be in a different state than at suspend time.
+    It's probably better to drop requests unless
+    the driver is a storage device.
+
+Q: Do I have to manage bus-specific power management registers
+
+No.  It is the responsibility of the bus driver to manage
+PCI, USB, etc. power management registers.  The bus driver
+or the power management subsystem will also enable any
+wake-on functionality that the device has.
+
+Q: So, really, what do I need to do to support suspend/resume?
+
+You need to save any device context that would
+be lost if the device was powered off and then restore
+it at resume time.  When ACPI is active, there are
+three levels of device suspend states; D1, D2, and D3.
+(The suspend state is passed as the "data" argument
+to the device callback.)  With D3, the device is powered
+off and loses all context, D1 and D2 are shallower power
+states and require less device context to be saved.  To
+play it safe, just save everything at suspend and restore
+everything at resume.
+
+Q: Where do I store device context for suspend?
+
+Anywhere in memory, kmalloc a buffer or store it
+in the device descriptor.  You are guaranteed that the
+contents of memory will be restored and accessible
+before resume, even when the system suspends to disk.
+
+Q: What do I need to do for ACPI vs. APM vs. etc?
+
+Drivers need not be aware of the specific power management
+technology that is active.  They just need to be aware
+of when the overlying power management system requests
+that they suspend or resume.
+
+Q: What about device dependencies?
+
+When a driver registers a device, the power management
+subsystem uses the information provided to build a
+tree of device dependencies (eg. USB device X is on
+USB controller Y which is on PCI bus Z)  When power
+management wants to suspend a device, it first sends
+a suspend request to its driver, then the bus driver,
+and so on up to the system bus.  Device resumes
+proceed in the opposite direction.
+
+Q: Who do I contact for additional information about
+   enabling power management for my specific driver/device?
+
+ACPI4Linux mailing list: acpi@phobos.fs.tum.de
+Linux ACPI maintainer: andy_henroid@yahoo.com
+
+System Interface
+----------------
+If you are providing new power management support to Linux (ie.
+adding support for something like APM or ACPI), you should
+communicate with drivers through the existing generic power
+management interface.
+
+/*
+ * Send a request to a single device
+ *
+ * Parameters:
+ *   dev - PM device previously returned from pm_register or pm_find
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          See "pm_callback" return for errors
+ *
+ * Details: Forward request to device callback and, if a suspend
+ *          or resume request, update the pm_dev "state" field
+ *          appropriately
+ */
+int pm_send(struct pm_dev *dev, pm_request_t rqst, void *data);
+
+/*
+ * Send a request to all devices
+ *
+ * Parameters:
+ *   rqst - request type
+ *   data - data, if any, associated with the request
+ *
+ * Returns: 0 if the request is successful
+ *          See "pm_callback" return for errors
+ *
+ * Details: Walk list of registered devices and call pm_send
+ *          for each until complete or an error is encountered.
+ *          If an error is encountered for a suspend request,
+ *          return all devices to the state they were in before
+ *          the suspend request.
+ */
+int pm_send_all(pm_request_t rqst, void *data);
+
+/*
+ * Find a matching device
+ *
+ * Parameters:
+ *   type - device type (PCI device, system device, or 0 to match all devices)
+ *   from - previous match or NULL to start from the beginning
+ *
+ * Returns: Matching device or NULL if none found
+ */
+struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from);