Hi3519-pinctrl驱动开发③consumer driver与pinctrl子系统交互

前一篇文章介绍了如果创建consumer driver到pinctrl driver的mapping table，这个mapping table就是系统的配置表，在系统启动之初注册到pinctrl sub system中去，貌似是在pinctrl driver注册之前就注册了mapping table了。既然已经有了mapping table，那我们假设pinctrl driver也已经“编写完成”（假设可以用了），这时候编写一个设备驱动的时候需要使用pinctrl sub system提供的服务，这时候设备驱动如何和pinctrl sub system交互呢？
有一个概念需要理解，就是“state”，也就是“状态”，每个设备对应第一个引脚组，继续以spi0设备为例，假设spi0设备对应的引脚组有两个，分别是PA0、1、2、3和PB5、6、7、8。state表示的就是设备使用的引脚组中引脚的状态，往常单片机开发中没有这个概念，但是在linux中为了提供足够的便利性和功能支持使用了state这个概念，具体来说当设备spi0正常运行的时候引脚状态处于正常状态，一般叫做default状态，当spi0设备处于关闭或者说低功耗模式下的时候引脚状态处于低功耗状态，一般叫做idle状态或者sleep状态（引脚的低功耗状态可能就是高阻态）。这样看来一个设备的pins可以处于不同的状态，pinctrl sub system提供了一种机制：pinctrl state holder，这个holder是一个容器，每一个设备都对应一个pinctrl state holder，用来存放设备拥有的所有states，pinctrl state holder结构体的定义如下：

struct pinctrl {     struct list_head node;－－系统中的所有device的pin control state holder被挂入到了一个全局链表中     struct device *dev;－－－该pin control state holder对应的device     struct list_head states;－－－－该设备的所有的状态被挂入到这个链表中     struct pinctrl_state *state;－－－当前的pin control state     struct list_head dt_maps;－－－－mapping table     struct kref users;－－－－－－reference count };

pinctrl state holder结构体的名称为“pinctrl”，而pinctrl驱动的描述结构体的名称为“pinctrl_desc”，真的很郁闷为什么这么命名，我觉得可以是“pinctrl_state_holder”和“pinctrl”，这样对于理解会方便很多。
pinctrl state holder结构体中的states元素存放的就是device的state链表，state元素存放的是当前device处于的状态。说到这里state显得很神秘，state是由结构体pinctrl_state 描述的：

struct pinctrl_state {        struct list_head node;---链表元素        const char *name;---state的名称        struct list_head settings;---设置};

pinctrl_state 前两个元素很好理解，最后一个settings元素表示的是要设置成这个state的话要进行的配置，settings也是一个链表，也就是有多个setting。setting是结构体struct pinctrl_setting：

struct pinctrl_setting {        struct list_head node;---链表元素        enum pinctrl_map_type type;---map type        struct pinctrl_dev *pctldev;---pinctrl驱动        const char *dev_name;---使用这个state的设备名        union {                struct pinctrl_setting_mux mux;                struct pinctrl_setting_configs configs;        } data;};

这个结构体和struct pinctrl_map结构体很像，type为PIN_MAP_TYPE_MUX_GROUP时data为mux，struct pinctrl_setting_mux的定义如下：

struct pinctrl_setting_mux {        unsigned group;---the group selector to program        unsigned func;---the function selector to program};

其中group就是引脚组的索引，func就是功能的索引。state的组织原理图如下图：

state概念介绍完了，那么说每个device对应的pinctrl state holder中的states中的settings是怎么来的，难道说是device自己定义的？显然不能，这样的话驱动会有太多没用的程序，而且可移植性很差。具体是怎么创建device的states和state中的settings呢？我也没研究过，我猜测是这样的：mapping table在系统启动之初就建立好了，注册到pinctrl sub system中，在建立pinctrl state holder的时候pinctrl子系统会根据对应的mapping table中的mapping entry创建states和settings，先假设是这么回事。现在已经“知道了”states和settings是在建立pinctrl state holder的时候创建的，那么pinctrl state holder是如何创建的呢？
pinctrl state holder是动态定义的，且并不是每个device都对应一个pinctrl state holder，因为有的device是不用引脚的。需要引脚的device需要获取属于自己的pinctrl state holder，使用的pinctrl sub system接口函数是devm_pinctrl_get和pinctrl_get，前者是后者的resource managed版本。单看后者pinctrl_get函数：

868 struct pinctrl *pinctrl_get(struct device *dev)869 {870         struct pinctrl *p;871 872         if (WARN_ON(!dev))873                 return ERR_PTR(-EINVAL);874 875         /*876          * See if somebody else (such as the device core) has already877          * obtained a handle to the pinctrl for this device. In that case,878          * return another pointer to it.879          */880         p = find_pinctrl(dev);881         if (p != NULL) {882                 dev_dbg(dev, "obtain a copy of previously claimed pinctrl\n");883                 kref_get(&p->users);884                 return p;885         }886 887         return create_pinctrl(dev);888 }

第880行中的find_pinctrl函数用来查找当前系统是否已经定义了该device的pinctrl state holder，如果没有定义的话就调用887行中的 create_pinctrl函数创建该device的pinctrl state holder。create_pinctrl如下：

 788 static struct pinctrl *create_pinctrl(struct device *dev) 789 { 790         struct pinctrl *p; 791         const char *devname; 792         struct pinctrl_maps *maps_node; 793         int i; 794         struct pinctrl_map const *map; 795         int ret; 796  797         /* 798          * create the state cookie holder struct pinctrl for each 799          * mapping, this is what consumers will get when requesting 800          * a pin control handle with pinctrl_get() 801          */ 802         p = kzalloc(sizeof(*p), GFP_KERNEL); 803         if (p == NULL) { 804                 dev_err(dev, "failed to alloc struct pinctrl\n"); 805                 return ERR_PTR(-ENOMEM); 806         } 807         p->dev = dev; 808         INIT_LIST_HEAD(&p->states); 809         INIT_LIST_HEAD(&p->dt_maps); 810  811         ret = pinctrl_dt_to_map(p); 812         if (ret < 0) { 813                 kfree(p); 814                 return ERR_PTR(ret); 815         } 816  817         devname = dev_name(dev); 818  819         mutex_lock(&pinctrl_maps_mutex); 820         /* Iterate over the pin control maps to locate the right ones */ 821         for_each_maps(maps_node, i, map) { 822                 /* Map must be for this device */ 823                 if (strcmp(map->dev_name, devname)) 824                         continue; 825  826                 ret = add_setting(p, map); 827                 /* 828                  * At this point the adding of a setting may: 829                  * 830                  * - Defer, if the pinctrl device is not yet available 831                  * - Fail, if the pinctrl device is not yet available, 832                  *   AND the setting is a hog. We cannot defer that, since 833                  *   the hog will kick in immediately after the device 834                  *   is registered. 835                  * 836                  * If the error returned was not -EPROBE_DEFER then we 837                  * accumulate the errors to see if we end up with 838                  * an -EPROBE_DEFER later, as that is the worst case. 839                  */ 840                 if (ret == -EPROBE_DEFER) { 841                         pinctrl_free(p, false); 842                         mutex_unlock(&pinctrl_maps_mutex); 843                         return ERR_PTR(ret); 844                 } 845         } 846         mutex_unlock(&pinctrl_maps_mutex); 847  848         if (ret < 0) { 849                 /* If some other error than deferral occured, return here */ 850                 pinctrl_free(p, false); 851                 return ERR_PTR(ret); 852         } 853  854         kref_init(&p->users); 855  856         /* Add the pinctrl handle to the global list */ 857         mutex_lock(&pinctrl_list_mutex); 858         list_add_tail(&p->node, &pinctrl_list); 859         mutex_unlock(&pinctrl_list_mutex); 860  861         return p; 862 }

简单看一下程序，802行分配pinctrl state holder内存空间，811行使用函数pinctrl_dt_to_map创建mapping table，这是使用DTS的方式创建的，我们使用的是Machine Driver的方式创建的，结果都是一样的，都是创建一个mapping table，只是DTS方式更加灵活方便，不需要修改内核代码就能系统支持不同的Board。这里有个疑问，没有使用DTS方式的话pinctrl_dt_to_map函数是不是会返回错误呢？这样就会在814行返回了，返回的话后面的初始化就没有得到执行，我看了一下pinctrl_dt_to_map函数的部分源码：

175 int pinctrl_dt_to_map(struct pinctrl *p)176 {177         struct device_node *np = p->dev->of_node;178         int state, ret;179         char *propname;180         struct property *prop;181         const char *statename;182         const __be32 *list;183         int size, config;184         phandle phandle;185         struct device_node *np_config;186 187         /* CONFIG_OF enabled, p->dev not instantiated from DT */188         if (!np) {189                 if (of_have_populated_dt())190                         dev_dbg(p->dev,191                                 "no of_node; not parsing pinctrl DT\n");192                 return 0;193         }194 195         /* We may store pointers to property names within the node */196         of_node_get(np);......

117行中获取p->dev->of_node，188行判断np是否为null，如果为null表示没有使用Device Tree机制，同时返回0表示没有错误。回到create_pinctrl函数，这样一来pinctrl_dt_to_map并没有完成解析DT来创建mapping table的任务，因为根本没有DT。接下里821行的“for_each_maps(maps_node, i, map)”其实就是遍历了系统全局变量pinctrl_maps链表中的每个pinctrl_maps，宏展开后是这样的：

list_for_each_entry(maps_node, &pinctrl_maps, node)        for (i=0,map=&maps_node->maps[i];i<maps_node->num_maps;i++,map=&maps_node>maps[i])

list_for_each_entry的含义参见文章：http://blog.csdn.net/tq384998430/article/details/73188601，简单来说就是list_for_each_entry宏中maps_node是一个迭代变量，&pinctrl_maps是链表头指针，node是结构体中的元素名称。整体意思就是从链表pinctrl_maps中挨个获取pinctrl_maps元素赋值给maps_node，然后循环将maps_node中的元素赋值给map进入循环中执行。注意这里两个pinctrl_maps的区别，一个pinctrl_maps是core.c文件中定义的链表全局变量：

59:LIST_HEAD(pinctrl_maps);

另一个是结构体struct pinctrl_maps。前者pinctrl_maps链表中的元素都是struct pinctrl_maps类型。
下面再看create_pinctrl函数的826行，add_setting，很显然这是通过map元素来创建pinctrl state holder中的state和settings，add_setting函数源码就不看了，意图很明显。经过list_for_each_entry循环和第二层的for循环后将所有与创建pinctrl state holder的device相关的maps都生成了相应的states和settings，这样consumer driver就能使用这些个states了。下面来说具体怎么使用定义好了的state holder中的states。
前面使用pinctrl_get已经创建了device的pinctrl state holder，并且根据mapping table初始化了pinctrl state holder中的states和settings（对应的devm_pinctrl_put和pinctrl_put两个函数用于释放pinctrl state holder资源）。现在假设一个场景是spi0设备驱动从pinctrl sub system中获取到了自己的pinctrl state holder，然后它要设置自己需要的引脚的状态到default状态，那么它可以使用函数pinctrl_lookup_state，函数原型为：

struct pinctrl_state *pinctrl_lookup_state(struct pinctrl *p, const char *name)；

这个函数根据state name在pin control state holder找到对应的pin control state。具体的state是各个device自己定义的，不过pin control subsystem自己定义了一些标准的pin control state，定义在pinctrl-state.h文件中：

#define PINCTRL_STATE_DEFAULT "default" #define PINCTRL_STATE_IDLE "idle" #define PINCTRL_STATE_SLEEP "sleep"

调用pinctrl_lookup_state示例：

dev->pins->default_state = pinctrl_lookup_state(dev->pins->p,PINCTRL_STATE_DEFAULT);

获取到了default_state之后可以调用pinctrl_select_state函数：

int pinctrl_select_state(struct pinctrl *p, struct pinctrl_state *state)；

这个函数用来选中一个特定的state，意思就是设置引脚成该state所描述的状态，这个设置过程就是由pinctrl驱动完成的了。