Linux功耗管理(17)_Linux PM domain framework(1)_概述和使用流程

1. 前言

在复杂的片上系统（SOC）中，设计者一般会将系统的供电分为多个独立的block，这称作电源域（Power Domain），这样做有很多好处，例如：

1）将不同功能模块的供电分开，减小相互之间的干扰（如模拟和数字分开）。

2）不同功能所需的电压大小不同：小电压能量损耗低，但对信号质量的要求较高；大电压能量损耗高，对信号质量的要求较低。因此可以根据实际情况，使用不同的电压供电，例如CPU core只需1.2v左右即可，而大部分的I/O则需要3.3v左右。

3）系统运行的大部分时间，并不需要所有模块都处于power on状态，因此可以通过关闭不工作模块的供电，将它们的耗电降为最低。

4）等等

虽然电源域的好处多多，却不是越多越好，因为划分电源域是需要成本的（需要在PMU中使用模拟电路完成，包括金钱成本和空间成本）。因此，大多数系统会根据功能，设置有限的几个电源域，例如：CPU core（1、2、3…）；GPU；NAND；DDR；USB；Display；Codec；等等。

这种设计引出一个问题：存在多个模块共用一个电源域的情况。因而要求在对模块power on/off的时候，考虑power共用的情况：只要一个模块工作，就要power on；直到所有模块停止工作，才能power off。

Kernel的PM domain framework（位于drivers/base/power/domain.c中），提供了管理和使用系统power domain的统一方法，在解决上面提到的问题的同时，结合kernel的suspend、runtime pm、clock framework等机制，以非常巧妙、灵活的方式，管理系统供电，以达到高效、节能的目的。

同样，作为一个framework，我们可以从三个角度分析：使用者（consumer）的角度；提供者（provider）的角度；内部实现。具体如下。

注：本文的linux kernel版本为3.18-rc4。一般情况下，对于那些相对稳定的framework，蜗蜗不会说明文章所使用的kernel版本，但本文是个例外，因为PM domain很多方便、易用的patch，只能在最新版本（当前为3.18-rc4）kernel上才能看到。

2. 怎么使用（从consumer的角度看）

借助device tree，pm domain的使用很简单（非常类似clock的使用，详见“clock framework的分析文章”），步骤如下：

1）检查pm domain provider提供的DTS的node名（下面的红色字体）：

powergate: power-domain@e012e000 {

        compatible = "xxx,xxx-pm-domains";

        reg = <0 0xe012e000 0 0x1000>;

        #power-domain-cells = <1>;

};

各个字段和clock framework类似，也可参考“Documentation/devicetree/bindings/power/power_domain.txt”，这里不再详细描述。

2）大部分情况下，power-domain-cells为1，因此需要得到所需使用的power domain的编号（可能会在include/dt-bindings/*中定义），如POWER_DOMAIN_USB。

3）在模块自己的DTS中，添加对power domian的引用描述，如下面红色字体：

power-domain-example@e028e000 {

        compatible = "xxx,xxx-dummy";

        reg = <0 0xe0280000 0 0x1000>;

        power-domains = <&powergate POWER_DOMAIN_USB>;

};

其中：“power-domains”为pm domain framework的关键字，由framework core负责解析（由名称可知，可以指定多个power domain）；“&powergate”为provider提供的DTS node名；“POWER_DOMAIN_USB”具体的domain标识，也是由provider提供。

4）借助runtime pm，在需要使用模块时，增加引用计数（可调用pm_runtime_get），不需要使用时，减少引用计数（可调用pm_runtime_put）。剩下的事情，就交给PM core了。

注2：PM core会在设备的引用计数为0时，自动调用PM domain的接口，尝试power off设备。同理，会在引用计数从0到1时，尝试power on设备。整个过程不需要设备的driver关心任何细节。同时，runtime pm也会处理idle、suspend、resume等相关的电源状态切换，如果driver只想使用PM domain功能，可以在probe中get一次，在remove中put一次，其效果和常规的power on/power off类似。

3. 怎么编写PM domain驱动（从provider的角度看）

从接口层面看，编写PM domain driver相当简单，只需要三个步骤：

1）将所有的domain，以struct generic_pm_domain（PM domain framework提供的）形式抽象出来，并填充数据结构中需要由provider提供的内容。

2）调用pm_genpd_init，初始化struct generic_pm_domain变量中其余的内容。

3）调用__of_genpd_add_provider接口，将所有的domain（由struct generic_pm_domain变量抽象）添加到kernel中，同时提供一个根据DTS node获得对应的domain指针的回调函数（类似clock framework）。

很显然，这三个步骤对我们编写pm domain driver没有任何帮助，因为其复杂度都被掩盖在struct generic_pm_domain结构体中了。让我们分析完内部逻辑后，再回来。

4. 基本流程分析

4.1 一些数据结构

1）我们先回到“Linux设备模型(5)_device和device driver”中，那篇文章我们留下了很多“未解之谜”，其中之一就是pm_domain指针，如下：

   1:  

   2: struct device {

   3:     ...

   4:     struct dev_pm_domain    *pm_domain;

   5:     ...

   6: };

struct dev_pm_domain结构很简单，只有一个struct dev_pm_ops类型的变量，该结构在“Linux电源管理(4)_Power Management Interface”中已有详细描述，是设备电源管理相关的操作函数集，包括idle、suspend/resume、runtime pm等有关的回调函数。

那这个结构和PM domain有什么关系呢？不着急，先看看struct generic_pm_domain结构。

2）struct generic_pm_domain

struct generic_pm_domain结构用于抽象PM domain，在include/linux/pm_domain.h中定义，如下：

   1: /* include/linux/pm_domain.h */

   2: struct generic_pm_domain {

   3:         struct dev_pm_domain domain;    /* PM domain operations */

   4:         struct list_head gpd_list_node; /* Node in the global PM domains list */

   5:         struct list_head master_links;  /* Links with PM domain as a master */

   6:         struct list_head slave_links;   /* Links with PM domain as a slave */

   7:         struct list_head dev_list;      /* List of devices */

   8:         struct mutex lock;

   9:         struct dev_power_governor *gov;

  10:         struct work_struct power_off_work;

  11:         const char *name;

  12:         unsigned int in_progress;       /* Number of devices being suspended now */

  13:         atomic_t sd_count;      /* Number of subdomains with power "on" */

  14:         enum gpd_status status; /* Current state of the domain */

  15:         wait_queue_head_t status_wait_queue;

  16:         struct task_struct *poweroff_task;      /* Powering off task */

  17:         unsigned int resume_count;      /* Number of devices being resumed */

  18:         unsigned int device_count;      /* Number of devices */

  19:         unsigned int suspended_count;   /* System suspend device counter */

  20:         unsigned int prepared_count;    /* Suspend counter of prepared devices */

  21:         bool suspend_power_off; /* Power status before system suspend */

  22:         int (*power_off)(struct generic_pm_domain *domain);

  23:         s64 power_off_latency_ns;

  24:         int (*power_on)(struct generic_pm_domain *domain);

  25:         s64 power_on_latency_ns;

  26:         struct gpd_dev_ops dev_ops;

  27:         s64 max_off_time_ns;    /* Maximum allowed "suspended" time. */

  28:         bool max_off_time_changed;

  29:         bool cached_power_down_ok;

  30:         struct gpd_cpuidle_data *cpuidle_data;

  31:         void (*attach_dev)(struct device *dev);

  32:         void (*detach_dev)(struct device *dev);

  33: };

这个结构很复杂，包括很多参数，不过：对consumer来说，不需要关心该结构；对provider而言，只需要关心有限的参数；大部分参数，framework内部使用。

对provider来说，需要为每个power domain定义一个struct generic_pm_domain变量，并至少提供如下字段：

name，该power domain的名称；

power_off/power_on，该power domain的on/off接口；

其它的字段，这里做一个大概的介绍（后续代码逻辑分析时会更为细致的说明）：

domain，struct dev_pm_domain类型的变量，再回忆一下struct device中的pm_domain指针，这二者一定有些关系，后面再详细描述；

gpd_list_node，用于将该domain添加到一个全局的domain链表（gpd_list）中；

master_links/slave_links，power domain可以有从属关系，例如一个power domain，通过一些器件，分出另外几个power domain，那么这个domain称作master domain，分出来的domain称作slave domain（也成subdomain）。这两个list用于组成master link和slave link，后面再详细描述；

dev_list，该domain下所有device的列表；

gov，struct dev_power_governor指针，后面再解释；

power_off_work，用于执行power off的wrok queue；

in_progress，该domain下正在suspend的device个数；

sd_count，记录处于power on状态的subdomain的个数；

status/status_wait_queue，power domain的状态，以及用于等待状态切换的wait queue；

power_off_task，

resume_count/device_count/suspended_count/prepared_count，

suspend_power_off，一个struct task_struct指针，记录正在执行power off操作的任务；

power_on_latency_ns/power_off_latency_ns，执行power on和power off操作时需要等待的时间，一般由provider提供；

dev_ops，struct gpd_dev_ops类型的变量，提供一些回调函数，后面再详细解释；

max_off_time_ns/max_off_timer_changed，和PM domain governor有关的变量，后面再详细解释；

cached_power_down_ok，同上；

cpuidle_data，可以把cpuidle和PM domain连接起来，这个指针用于保存CPU idle相关的数据； 

attach_dev/detach_dev，当device和pm domain关联/去关联时，调用这两个回调函数。如果provider需要做一些处理，可以提供。

我相信读者一定被这个数据结构搞晕了，不要着急，太复杂的话，我们先放一下，去看一些简单的。下面一节我们先从整体流程上，看一下power domain framework怎么工作的（最简单的case），然后再回到这些细节上。

4.2 PM domain的工作流程

结合第二章、第三章的说明，PM domain的工作流程包括：

1）Provider在DTS中定义power domain有关的device tree node，并在provider的初始化接口（可以是一个platform driver的probe，也可以是其它形式）中，定义、初始化并注册所有的power domain。

2）PM domain的初始化和注册

provider需要为每个domain定义一个struct generic_pm_domain变量，并初始化必要的字段和回调函数，然后调用pm_genpd_init接口，初始化其余的字段，如下：

   1: /**

   2:  * pm_genpd_init - Initialize a generic I/O PM domain object.

   3:  * @genpd: PM domain object to initialize.

   4:  * @gov: PM domain governor to associate with the domain (may be NULL).

   5:  * @is_off: Initial value of the domain's power_is_off field.

   6:  */

   7: void pm_genpd_init(struct generic_pm_domain *genpd,

   8:            struct dev_power_governor *gov, bool is_off)

   9: {

  10:     if (IS_ERR_OR_NULL(genpd))

  11:         return;

  12:  

  13:     INIT_LIST_HEAD(&genpd->master_links);

  14:     INIT_LIST_HEAD(&genpd->slave_links);

  15:     INIT_LIST_HEAD(&genpd->dev_list);

  16:     mutex_init(&genpd->lock);

  17:     genpd->gov = gov;

  18:     INIT_WORK(&genpd->power_off_work, genpd_power_off_work_fn);

  19:     genpd->in_progress = 0;

  20:     atomic_set(&genpd->sd_count, 0);

  21:     genpd->status = is_off ? GPD_STATE_POWER_OFF : GPD_STATE_ACTIVE;

  22:     init_waitqueue_head(&genpd->status_wait_queue);

  23:     genpd->poweroff_task = NULL;

  24:     genpd->resume_count = 0;

  25:     genpd->device_count = 0;

  26:     genpd->max_off_time_ns = -1;

  27:     genpd->max_off_time_changed = true;

  28:     genpd->domain.ops.runtime_suspend = pm_genpd_runtime_suspend;

  29:     genpd->domain.ops.runtime_resume = pm_genpd_runtime_resume;

  30:     genpd->domain.ops.prepare = pm_genpd_prepare;

  31:     genpd->domain.ops.suspend = pm_genpd_suspend;

  32:     genpd->domain.ops.suspend_late = pm_genpd_suspend_late;

  33:     genpd->domain.ops.suspend_noirq = pm_genpd_suspend_noirq;

  34:     genpd->domain.ops.resume_noirq = pm_genpd_resume_noirq;

  35:     genpd->domain.ops.resume_early = pm_genpd_resume_early;

  36:     genpd->domain.ops.resume = pm_genpd_resume;

  37:     genpd->domain.ops.freeze = pm_genpd_freeze;

  38:     genpd->domain.ops.freeze_late = pm_genpd_freeze_late;

  39:     genpd->domain.ops.freeze_noirq = pm_genpd_freeze_noirq;

  40:     genpd->domain.ops.thaw_noirq = pm_genpd_thaw_noirq;

  41:     genpd->domain.ops.thaw_early = pm_genpd_thaw_early;

  42:     genpd->domain.ops.thaw = pm_genpd_thaw;

  43:     genpd->domain.ops.poweroff = pm_genpd_suspend;

  44:     genpd->domain.ops.poweroff_late = pm_genpd_suspend_late;

  45:     genpd->domain.ops.poweroff_noirq = pm_genpd_suspend_noirq;

  46:     genpd->domain.ops.restore_noirq = pm_genpd_restore_noirq;

  47:     genpd->domain.ops.restore_early = pm_genpd_resume_early;

  48:     genpd->domain.ops.restore = pm_genpd_resume;

  49:     genpd->domain.ops.complete = pm_genpd_complete;

  50:     genpd->dev_ops.save_state = pm_genpd_default_save_state;

  51:     genpd->dev_ops.restore_state = pm_genpd_default_restore_state;

  52:     mutex_lock(&gpd_list_lock);

  53:     list_add(&genpd->gpd_list_node, &gpd_list);

  54:     mutex_unlock(&gpd_list_lock);

  55: }

该接口可接受三个参数：genpd为需要初始化的power domain指针；gov为governor，可以留空，我们先不考虑它；is_off，指明该power domain在注册时的状态，是on还是off，以便framework正确设置该domain的status字段。

它的逻辑比较简单，值得注意的是genpd->domain.ops中各个回调函数的初始化，这些以”pm_genqd_”为前缀的函数，都是pm domain framework提供的帮助函数，用于power domain级别的电源管理，包括power on/off、suspend/resume、runtime pm等。

回忆一下“Linux电源管理(4)_Power Management Interface”中有关struct dev_pm_ops的描述，bus_type、device_driver、class、device_type、device等结构，都可以包括dev pm ops，而PM core进行相关的电源状态切换时，只会调用其中的一个。选择哪个，是有优先顺序的，其中优先级最高的，就是device结构中pm_domain指针的。

那么，我们再思考一下，device中可是一个指针哦，具体的变量哪来的？你一定猜到了，来自struct generic_pm_domain变量，就是这个函数初始化的内容。后面再详细介绍。

3）完成所有domain的初始化后，调用__of_genpd_add_provider接口，将它们添加到kernel中。从该接口的命名上，我们可以猜到，它和DTS有关（of是Open Firmware的缩写），定义如下：

   1: /**

   2:  * __of_genpd_add_provider() - Register a PM domain provider for a node

   3:  * @np: Device node pointer associated with the PM domain provider.

   4:  * @xlate: Callback for decoding PM domain from phandle arguments.

   5:  * @data: Context pointer for @xlate callback.

   6:  */

   7: int __of_genpd_add_provider(struct device_node *np, genpd_xlate_t xlate,

   8:                         void *data)

   9: {

  10:         struct of_genpd_provider *cp;

  11:  

  12:         cp = kzalloc(sizeof(*cp), GFP_KERNEL);

  13:         if (!cp)

  14:                 return -ENOMEM;

  15:  

  16:         cp->node = of_node_get(np);

  17:         cp->data = data;

  18:         cp->xlate = xlate;

  19:  

  20:         mutex_lock(&of_genpd_mutex);

  21:         list_add(&cp->link, &of_genpd_providers);

  22:         mutex_unlock(&of_genpd_mutex);

  23:         pr_debug("Added domain provider from %s\n", np->full_name);

  24:  

  25:         return 0;

  26: }

也许您会奇怪，该接口的三个参数没有一个和struct generic_pm_domain所代表的power domain有关啊！不着急，我们慢慢分析。

参数1，np，是一个device node指针，哪来的？想一下第2章pm domain provider提供的DTS，就是它生成的指针；

参数2，xlate，一个用于解析power domain的回调函数，定义如下：

typedef struct generic_pm_domain *(*genpd_xlate_t)(struct of_phandle_args *args, void *data);

该回调函数的第二个参数，就是__of_genpd_add_provider接口的参数3。它会返回一个power domain指针；

参数3，data，一个包含了所有power domain信息的指针，具体的形式，由provider自行定义，反正最终会传给同样由provider提供的回调函数中，provider根据实际情况，获得对应的power domain指针，并返回给调用者。

注3：这是device tree的惯用伎俩，consumer在DTS中对所使用的资源（这里为power domain，如power-domains = <&powergate POWER_DOMAIN_USB>;）的声明，最终会由对应的framework（这里为pm domain framework）解析，并调用provider提供的回调函数，最终返回给consumer该资源的句柄（这里为一个struct generic_pm_domain指针）。所有的framework都是这样做的，包括前面所讲的clock framework，这里的pm domain framework，等等。具体的解析过程，后面会详细描述。

4）pm domain framework对consumer DTS中的power domain的解析

先把第2章的例子搬过来：

power-domain-example@e028e000 {

        …

        power-domains = <&powergate POWER_DOMAIN_USB>;

};

怎么解析呢？让我们从设备模型的platform_drv_probe接口开始。

由Linux设备模型相关的文章可知，platform设备的枚举从platform_drv_probe开始。而所有在DTS中描述的设备，最终会生成一个platform设备，这个设备的driver的执行，也会从platform_drv_probe开始，该接口进而会调用platform driver的probe。如下：

   1: static int platform_drv_probe(struct device *_dev)

   2: {

   3:         struct platform_driver *drv = to_platform_driver(_dev->driver);

   4:         struct platform_device *dev = to_platform_device(_dev);

   5:         int ret;

   6:  

   7:         ret = of_clk_set_defaults(_dev->of_node, false);

   8:         if (ret < 0)

   9:                 return ret;

  10:  

  11:         ret = dev_pm_domain_attach(_dev, true);

  12:         if (ret != -EPROBE_DEFER) {

  13:                 ret = drv->probe(dev);

  14:                 if (ret)

  15:                         dev_pm_domain_detach(_dev, true);

  16:         }

  17:  

  18:         if (drv->prevent_deferred_probe && ret == -EPROBE_DEFER) {

  19:                 dev_warn(_dev, "probe deferral not supported\n");

  20:                 ret = -ENXIO;

  21:         }

  22:  

  23:         return ret;

  24: }

在执行driver的probe之前，会先调用dev_pm_domain_attach接口，将该设备attach到指定的power domain上（如果有的话）。该接口位于drivers/base/power/common.c中，实现如下：

   1: int dev_pm_domain_attach(struct device *dev, bool power_on)

   2: {

   3:         int ret;

   4:  

   5:         ret = acpi_dev_pm_attach(dev, power_on);

   6:         if (ret)

   7:                 ret = genpd_dev_pm_attach(dev);

   8:  

   9:         return ret;

  10: }

  11: EXPORT_SYMBOL_GPL(dev_pm_domain_attach);

先不考虑ACPI设备，会直接调用genpd_dev_pm_attach接口（呵呵，回到pm domain framework了），该接口位于drivers/base/power/domain.c，如下：

   1: /**

   2:  * genpd_dev_pm_attach - Attach a device to its PM domain using DT.

   3:  * @dev: Device to attach.

   4:  *

   5:  * Parse device's OF node to find a PM domain specifier. If such is found,

   6:  * attaches the device to retrieved pm_domain ops.

   7:  *

   8:  * Both generic and legacy Samsung-specific DT bindings are supported to keep

   9:  * backwards compatibility with existing DTBs.

  10:  *

  11:  * Returns 0 on successfully attached PM domain or negative error code.

  12:  */

  13: int genpd_dev_pm_attach(struct device *dev)

  14: {

  15:     struct of_phandle_args pd_args;

  16:     struct generic_pm_domain *pd;

  17:     int ret;

  18:  

  19:     if (!dev->of_node)

  20:         return -ENODEV;

  21:  

  22:     if (dev->pm_domain)

  23:         return -EEXIST;

  24:  

  25:     ret = of_parse_phandle_with_args(dev->of_node, "power-domains",

  26:                     "#power-domain-cells", 0, &pd_args);

  27:     if (ret < 0) {

  28:         if (ret != -ENOENT)

  29:             return ret;

  30:  

  31:         /*

  32:          * Try legacy Samsung-specific bindings

  33:          * (for backwards compatibility of DT ABI)

  34:          */

  35:         pd_args.args_count = 0;

  36:         pd_args.np = of_parse_phandle(dev->of_node,

  37:                         "samsung,power-domain", 0);

  38:         if (!pd_args.np)

  39:             return -ENOENT;

  40:     }

  41:  

  42:     pd = of_genpd_get_from_provider(&pd_args);

  43:     if (IS_ERR(pd)) {

  44:         dev_dbg(dev, "%s() failed to find PM domain: %ld\n",

  45:             __func__, PTR_ERR(pd));

  46:         of_node_put(dev->of_node);

  47:         return PTR_ERR(pd);

  48:     }

  49:  

  50:     dev_dbg(dev, "adding to PM domain %s\n", pd->name);

  51:  

  52:     while (1) {

  53:         ret = pm_genpd_add_device(pd, dev);

  54:         if (ret != -EAGAIN)

  55:             break;

  56:         cond_resched();

  57:     }

  58:  

  59:     if (ret < 0) {

  60:         dev_err(dev, "failed to add to PM domain %s: %d",

  61:             pd->name, ret);

  62:         of_node_put(dev->of_node);

  63:         return ret;

  64:     }

  65:  

  66:     dev->pm_domain->detach = genpd_dev_pm_detach;

  67:  

  68:     return 0;

  69: }

  70: EXPORT_SYMBOL_GPL(genpd_dev_pm_attach);

还蛮复杂，我们先不管细节，看一个大概的过程：

a）of_parse_phandle_with_args负责从device_node指针中，解析指定名称的字段，其中”power-domains”是consumer DTS中的关键字，最终会解出一个struct of_phandle_args类型的变量（回忆一下上面的genpd_xlate_t函数指针，第一个参数就是该类型指针）。

b）解析完成后，调用of_genpd_get_from_provider接口，获取power domain指针。

c）最后调用pm_genpd_add_device接口，将该设备添加到该power domain相应的链表中。

of_genpd_get_from_provider负责最终的domain解析，实现如下：

   1: static struct generic_pm_domain *of_genpd_get_from_provider(

   2:                                         struct of_phandle_args *genpdspec)

   3: {

   4:         struct generic_pm_domain *genpd = ERR_PTR(-ENOENT);

   5:         struct of_genpd_provider *provider;

   6:  

   7:         mutex_lock(&of_genpd_mutex);

   8:  

   9:         /* Check if we have such a provider in our array */

  10:         list_for_each_entry(provider, &of_genpd_providers, link) {

  11:                 if (provider->node == genpdspec->np)

  12:                         genpd = provider->xlate(genpdspec, provider->data);

  13:                 if (!IS_ERR(genpd))

  14:                         break;

  15:         }

  16:  

  17:         mutex_unlock(&of_genpd_mutex);

  18:  

  19:         return genpd;

  20: }

找到一个provider，以data指针为参数，调用xlate回调，剩下的事情，就交给provider自己了。

5）power domain的使用

device获得自己的power domain后，可以利用pm_runtime_get_xxx/pm_runtime_put_xxx接口，增加或减少引用计数，runtime pm core会在合适的时机，调用pm domain提供的power on/off提供的接口，power on或者power off设备。

当然，如果不想使用runtime pm接口，pm domain也提供了其它直接调用的形式，不过不建议使用。

具体的on/off流程，会在下一篇文章继续分析，本文就先到这里了。

 

原创文章，转发请注明出处。蜗窝科技，www.wowotech.net。