Documentation/arm/omap/omap_pm.rst

   1 =====================
   2 The OMAP PM interface
   3 =====================
   4
   5 This document describes the temporary OMAP PM interface.  Driver
   6 authors use these functions to communicate minimum latency or
   7 throughput constraints to the kernel power management code.
   8 Over time, the intention is to merge features from the OMAP PM
   9 interface into the Linux PM QoS code.
  10
  11 Drivers need to express PM parameters which:
  12
  13 - support the range of power management parameters present in the TI SRF;
  14
  15 - separate the drivers from the underlying PM parameter
  16   implementation, whether it is the TI SRF or Linux PM QoS or Linux
  17   latency framework or something else;
  18
  19 - specify PM parameters in terms of fundamental units, such as
  20   latency and throughput, rather than units which are specific to OMAP
  21   or to particular OMAP variants;
  22
  23 - allow drivers which are shared with other architectures (e.g.,
  24   DaVinci) to add these constraints in a way which won't affect non-OMAP
  25   systems,
  26
  27 - can be implemented immediately with minimal disruption of other
  28   architectures.
  29
  30
  31 This document proposes the OMAP PM interface, including the following
  32 five power management functions for driver code:
  33
  34 1. Set the maximum MPU wakeup latency::
  35
  36    (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t)
  37
  38 2. Set the maximum device wakeup latency::
  39
  40    (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t)
  41
  42 3. Set the maximum system DMA transfer start latency (CORE pwrdm)::
  43
  44    (*pdata->set_max_sdma_lat)(struct device *dev, long t)
  45
  46 4. Set the minimum bus throughput needed by a device::
  47
  48    (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r)
  49
  50 5. Return the number of times the device has lost context::
  51
  52    (*pdata->get_dev_context_loss_count)(struct device *dev)
  53
  54
  55 Further documentation for all OMAP PM interface functions can be
  56 found in arch/arm/plat-omap/include/mach/omap-pm.h.
  57
  58
  59 The OMAP PM layer is intended to be temporary
  60 ---------------------------------------------
  61
  62 The intention is that eventually the Linux PM QoS layer should support
  63 the range of power management features present in OMAP3.  As this
  64 happens, existing drivers using the OMAP PM interface can be modified
  65 to use the Linux PM QoS code; and the OMAP PM interface can disappear.
  66
  67
  68 Driver usage of the OMAP PM functions
  69 -------------------------------------
  70
  71 As the 'pdata' in the above examples indicates, these functions are
  72 exposed to drivers through function pointers in driver .platform_data
  73 structures.  The function pointers are initialized by the `board-*.c`
  74 files to point to the corresponding OMAP PM functions:
  75
  76 - set_max_dev_wakeup_lat will point to
  77   omap_pm_set_max_dev_wakeup_lat(), etc.  Other architectures which do
  78   not support these functions should leave these function pointers set
  79   to NULL.  Drivers should use the following idiom::
  80
  81         if (pdata->set_max_dev_wakeup_lat)
  82             (*pdata->set_max_dev_wakeup_lat)(dev, t);
  83
  84 The most common usage of these functions will probably be to specify
  85 the maximum time from when an interrupt occurs, to when the device
  86 becomes accessible.  To accomplish this, driver writers should use the
  87 set_max_mpu_wakeup_lat() function to constrain the MPU wakeup
  88 latency, and the set_max_dev_wakeup_lat() function to constrain the
  89 device wakeup latency (from clk_enable() to accessibility).  For
  90 example::
  91
  92         /* Limit MPU wakeup latency */
  93         if (pdata->set_max_mpu_wakeup_lat)
  94             (*pdata->set_max_mpu_wakeup_lat)(dev, tc);
  95
  96         /* Limit device powerdomain wakeup latency */
  97         if (pdata->set_max_dev_wakeup_lat)
  98             (*pdata->set_max_dev_wakeup_lat)(dev, td);
  99
 100         /* total wakeup latency in this example: (tc + td) */
 101
 102 The PM parameters can be overwritten by calling the function again
 103 with the new value.  The settings can be removed by calling the
 104 function with a t argument of -1 (except in the case of
 105 set_max_bus_tput(), which should be called with an r argument of 0).
 106
 107 The fifth function above, omap_pm_get_dev_context_loss_count(),
 108 is intended as an optimization to allow drivers to determine whether the
 109 device has lost its internal context.  If context has been lost, the
 110 driver must restore its internal context before proceeding.
 111
 112
 113 Other specialized interface functions
 114 -------------------------------------
 115
 116 The five functions listed above are intended to be usable by any
 117 device driver.  DSPBridge and CPUFreq have a few special requirements.
 118 DSPBridge expresses target DSP performance levels in terms of OPP IDs.
 119 CPUFreq expresses target MPU performance levels in terms of MPU
 120 frequency.  The OMAP PM interface contains functions for these
 121 specialized cases to convert that input information (OPPs/MPU
 122 frequency) into the form that the underlying power management
 123 implementation needs:
 124
 125 6. `(*pdata->dsp_get_opp_table)(void)`
 126
 127 7. `(*pdata->dsp_set_min_opp)(u8 opp_id)`
 128
 129 8. `(*pdata->dsp_get_opp)(void)`
 130
 131 9. `(*pdata->cpu_get_freq_table)(void)`
 132
 133 10. `(*pdata->cpu_set_freq)(unsigned long f)`
 134
 135 11. `(*pdata->cpu_get_freq)(void)`
 136
 137 Customizing OPP for platform
 138 ============================
 139 Defining CONFIG_PM should enable OPP layer for the silicon
 140 and the registration of OPP table should take place automatically.
 141 However, in special cases, the default OPP table may need to be
 142 tweaked, for e.g.:
 143
 144  * enable default OPPs which are disabled by default, but which
 145    could be enabled on a platform
 146  * Disable an unsupported OPP on the platform
 147  * Define and add a custom opp table entry
 148    in these cases, the board file needs to do additional steps as follows:
 149
 150 arch/arm/mach-omapx/board-xyz.c::
 151
 152         #include "pm.h"
 153         ....
 154         static void __init omap_xyz_init_irq(void)
 155         {
 156                 ....
 157                 /* Initialize the default table */
 158                 omapx_opp_init();
 159                 /* Do customization to the defaults */
 160                 ....
 161         }
 162
 163 NOTE:
 164   omapx_opp_init will be omap3_opp_init or as required
 165   based on the omap family.