linux内核驱动-pinctrl子系统

1 pinctrl和gpio subsystem引入

Linux 驱动讲究驱动分离与分层，pinctrl 和 gpio 子系统就是驱动分离与分层思想下的产物。
pinctrl顾名思义就是引脚控制，用来配置比如引脚mux复用信息，引脚电器属性（比如上/下拉、速度、驱动能力等）信息。
gpio顾名思义就是控制gpio的输入输出，以及高低电平。不过，大多数的芯片并没有单独的IOMUX模块，引脚的复用、配置等，而是在GPIO模块内部实现的。

2 pinctrl子系统原理介绍

2.1 pinctrl子系统

2.1.1 pinctrl子系统软件架构

pinctrl子系统源码路径是linux/drivers/pinctrl：

其他驱动层（client）：具体到使用系统pin资源的设备驱动程序
pinctrl核心层(core)：内核抽象出来，向下为SoC pin controler drvier提供底层通信接口的能力， 向上为其他驱动提供了控制pin的能力，比如pin复用、配置引脚的电气特性，同时也为GPIO子系统提供pin操作。
pin控制器驱动层(pinctrl-driver)： 提供了操作pin的具体方法。

pinctrl-driver主要为pinctrl-core提供pin的操作能力。把系统所有的pin以及对于pin的控制接口实例化成pinctrl_desc，并将pinctrl_desc注册到pinctrl-core中去。

2.1.2 Pinctrl重要概念

Documentation\devicetree\bindings\pinctrl\pinctrl-bindings.txt有介绍重要相关概念：

1. pin controller：
芯片手册里你找不到 pin controller，它是一个软件上的概念。对应 IOMUX──用来复用引脚，还可以配置引脚(比如上下拉电阻等)。
2. client device：
“客户设备”，客户是指Pinctrl系统的客户，即使用Pinctrl系统的设备，使用引脚的设备

• 1. pin state
     对于一个"client device"，如UART设备，它有多个“状态”：default、sleep等，那么对应的引脚也有这些状态。

  比如，默认状态下，UART设备正常工作，那么所用的引脚就要复用为UART功能；
  休眠状态下，为了省电，可以把这些引脚复用为GPIO功能；或者直接把它们配置输出高电平。

  上图pinctrl-names定义2种状态：default，sleep。
  第0种状态用到的引脚在pinctrl-0中定义，它是state_0_node_a，位于pincontroller节点中。
  第1种状态用到的引脚在Pinctrl-1中定义，它是state_1_node_a，位于pincontroller节点中。

  当UART设备处于default状态时，pinctrl子系统会自动根据上述信息将所用引脚复用为uart0功能。
  当UART设备处于sleep状态时，pinctrl子系统会自动根据上述信息将所用引脚配置为高电平。

• 2. groups和function
     一个设备会用到一个或多个引脚，这些引脚可以归纳为一组（group）；
     这些引脚可以复用为某个功能：function，如I2C功能，SPI功能，GPIO功能等。当然：一个设备可以用到多组引脚，比如A1、A2两组引脚，A1组复用为F1功能，A2组复用为F2功能：
     
• 3. Generic pin multiplexing node和Generic pin configuration node
     上图左边pin controller节点中，有子节点或孙节点，它们是给client device使用的。
     可用来描述复用信息：哪组（group）引脚复用为哪个功能（function）；
     配置信息：哪组（group）引脚配置为哪个设置功能（setting），如上拉、下拉等；

2.1.3 pinctrl 子系统注册流程

以imx6ull为例，drivers/pinctrl/freescale/pinctrl-imx6ul.c

驱动的入口是 arch_initcall 中声明的函数，类似于我们经常写的 module_init是动态ko加载，arch_initcall是编译进入内核镜像。可以看到是利用platform_device框架来写的。

根据 compatible 和设备树的compatible 字段进行匹配，匹配成功执行 probe 函数，调用imx_pinctrl_probe_dt解析dts中的pinctrl描述信息。调用pinctrl_register或者devm_pinctrl_register注册pinctl子系统。

3 soc pin主要结构体（controller）

总框图记录数据结构之间的关联。

//pincontroller数据结构
drivers\pinctrl\core.h
include\linux\pinctrl\pinctrl.h
include\linux\pinctrl\pinmux.h
include\linux\pinctrl\pinconf.h
//client数据结构
drivers\pinctrl\core.h
include\linux\pinctrl\devinfo.h
include\linux\device.h
include\linux\pinctrl\machine.h

3.1 pinctrl_dev

pinctrl_dev 是 pinctrl 子系统的根源结构体。

struct pinctrl_dev {
	struct list_head node;
	struct pinctrl_desc *desc; //提供具体操作方法和抽象包括pincrtl_ops函数，pinmux操作函数和pin的描述等
	struct radix_tree_root pin_desc_tree;
#ifdef CONFIG_GENERIC_PINCTRL_GROUPS
	struct radix_tree_root pin_group_tree;//存储group的描述信息
	unsigned int num_groups;
#endif
#ifdef CONFIG_GENERIC_PINMUX_FUNCTIONS
	struct radix_tree_root pin_function_tree;//存储function的描述信息
	unsigned int num_functions;
#endif
	struct list_head gpio_ranges;//链接gpio range 2 pin range相关的信息
	struct device *dev;
	struct module *owner;
	void *driver_data;
	struct pinctrl *p;//每个pinctrl都描述着一组gpio的复用和状态配置，如果这个pinctrl_dev是一个通过iic连接的，那么使用这个pinctrl_dev就需要配置其占用的gpio为iic功能，那么就要用这个来描述
	struct pinctrl_state *hog_default;
	struct pinctrl_state *hog_sleep;
	struct mutex mutex;
#ifdef CONFIG_DEBUG_FS
	struct dentry *device_root;
#endif
}

/driver/pinctrl/core.c中注册pinctrl时将soc中所有的pinctrl_dev挂载到pinctrl_dev_list链表中方便查询使用。

struct pinctrl_dev *pinctrl_register(struct pinctrl_desc *pctldesc,
								 struct device *dev, void *driver_data);

3.2 pinctrl_desc

struct pinctrl_desc {
   const char *name;
   const struct pinctrl_pin_desc *pins;   //描述一个pin控制器的引脚,
   unsigned int npins;                    //描述该控制器有多少个引脚
   const struct pinctrl_ops *pctlops;     //引脚操作函数，有描述引脚，获取引脚等，全局控制函数
   const struct pinmux_ops *pmxops;       //引脚复用相关的操作函数
   const struct pinconf_ops *confops;     //引脚配置相关的操作函数
   struct module *owner;
#ifdef CONFIG_GENERIC_PINCONF
   unsigned int num_custom_params;
   const struct pinconf_generic_params *custom_params;
   const struct pin_config_item *custom_conf_items;
#endif
};

三个ops:

1. group操作接口对应数据结构struct pinctrl_ops，包含get_groups_count、get_group_name、get_group_pins等接口；

2. mux操作接口对应的数据结构为struct pinmux_ops，包含pin request、free、set_mux、get_functions_count、get_function_groups等；

3. function操作接口对应的数据结构为struct pinconf_ops，包含pin_config_set、pin_config_get、pin_config_group_get、pin_config_group_set等接口；

3.2.1 pinctrl_pin_desc

struct pinctrl_pin_desc {
	unsigned number;//引脚序号
	const char *name;//引脚名
	void *drv_data;
};

pinctrl_pin_desc来描述一个引脚.

3.2.2 pin_desc

struct pin_desc {
	struct pinctrl_dev *pctldev;
	const char *name;
	bool dynamic_name;
	void *drv_data;
	/* These fields only added when supporting pinmux drivers */
#ifdef CONFIG_PINMUX
	unsigned mux_usecount;
	const char *mux_owner;
	const struct pinctrl_setting_mux *mux_setting;
	const char *gpio_owner;
#endif
};

记录引脚的使用计数、引脚当前所属的function、group信息（该数据结构主要是pinctrl子系统用于判断一个引脚是否被多次配置不同的复用情况使用（pin_request、pin_free）

3.2.3 三个ops

3.2.3.1 pinctrl_ops

struct pinctrl_ops {
	//获取组数
	int (*get_groups_count) ();
	//获取组名
	const char *(*get_group_name) ();
	//获取某组的引脚
	int (*get_group_pins) ();
	//用以debugfs提供每个引脚的信息
	void (*pin_dbg_show) ();
	//解析设备树节点，转换成pinctrl_map，重点
	int (*dt_node_to_map) ();
	//释放map
	void (*dt_free_map) ();
};

• 来取出某组的引脚：get_groups_count、get_group_pins
• 处理设备树中pin controller中的某个节点创建映射：dt_node_to_map，把device_node转换为一系列的pinctrl_map

3.2.3.2 pinmux_ops

struct pinconf_ops {
#ifdef CONFIG_GENERIC_PINCONF
	bool is_generic;
#endif
	//获取单个引脚配置
	int (*pin_config_get) ();
	//配置单个引脚
	int (*pin_config_set) ();
	//获取某组引脚配置
	int (*pin_config_group_get) ();
	//配置某组引脚
	int (*pin_config_group_set) ();
	//用以debugfs修改pin配置信息
	int (*pin_config_dbg_parse_modify) ();
	//用以debugfs提供pin配置信息
	void (*pin_config_dbg_show) ();
	//用以debugfs提供group配置信息
	void (*pin_config_group_dbg_show) ();
	//用以debugfs解析并显示pin的配置
	void (*pin_config_config_dbg_show) (s);
};

3.2.3.3 pinconf_ops

struct pinconf_ops {
#ifdef CONFIG_GENERIC_PINCONF
	bool is_generic;
#endif
	//获取单个引脚配置
	int (*pin_config_get) ();
	//配置单个引脚
	int (*pin_config_set) ();
	//获取某组引脚配置
	int (*pin_config_group_get) ();
	//配置某组引脚
	int (*pin_config_group_set) ();
	//用以debugfs修改pin配置信息
	int (*pin_config_dbg_parse_modify) ();
	//用以debugfs提供pin配置信息
	void (*pin_config_dbg_show) ();
	//用以debugfs提供group配置信息
	void (*pin_config_group_dbg_show) ();
	//用以debugfs解析并显示pin的配置
	void (*pin_config_config_dbg_show) (s);
};

4 board pin相关结构体(使用者client)

前面Soc pin描述相关的数据结构，已经搭建了该soc所支持的pin、function、group以及相关操作接口等信息；而board pin描述相关的数据结构则描述一块board所使用到的function及相关的group：

4.1 pinctrl_map

struct pinctrl_map {
	const char *dev_name;//设备名称
	const char *name;//该pinctrl_map对应的状态（default、idle、sleep等
	enum pinctrl_map_type type;//pinctrl_map的类型，包括mux group、config group、config pins等
	const char *ctrl_dev_name;//pinctrl device的名称，根据该名称可获取到soc pin controller对应的pinctrl device
	union {
		struct pinctrl_map_mux mux;//引脚复用的内容，该数据结构中包含function名称、group名称，通过function、group就可以确定进行引脚复用的引脚id与引脚复用值等信息；
		struct pinctrl_map_configs configs;//引脚配置相关的内容，包括group或者pin的名称，以及该group、pin的配置信息，实现引脚配置操作。
	} data;
};

该数据结构可以理解为一个function类型：

4.2 dev_pin_info

device结构体中有一个dev_pin_info，用来保存设备的pinctrl信息：

struct dev_pin_info {    //该device对应引脚的配置与复用信息
	struct pinctrl *p;//该设备支持引脚配置类型（包括支持的pinctrl状态，每一种pinctrl状态下的引脚复用以及引脚配置信息）
	struct pinctrl_state *default_state;
	struct pinctrl_state *init_state;
#ifdef CONFIG_PM
	struct pinctrl_state *sleep_state;
	struct pinctrl_state *idle_state;
#endif
};

4.2.1 pinctrl

一个设备的所有引脚配置相关的信息:

struct pinctrl {
	struct list_head node;
	struct device *dev;
	struct list_head states;
	struct pinctrl_state *state;//states下链接了该设备支持的所有引脚配置状态
	struct list_head dt_maps;
	struct kref users;
};

4.2.1.1 pinctrl_state

struct pinctrl_state {
	struct list_head node;
	const char *name;
	struct list_head settings;
};

5 pinctrl实例化示例

5.1 pin controller示例

打开imx6ull的dtsi找到pin controller控制器节点，对比IMX6ULL参考手册可知：imx6ull一共3个IOMUX控制器：

5.2 client示例

以evk公板为例：

imx6ull pinmux dts配置描述：
我们看到：

MX6UL_PAD_UART1_RTS_B__GPIO1_IO19       0x17059 /* SD1 CD */

它是表示什么意思呢？配置了哪些信息呢？

UART1_RTS_B复用成GPIO1_IO19:

此宏定义在imx_6ull_pinfunc.h, 后面跟着 5 个数字，也就是这个宏定义的具体值，如下所示：

0x0090 0x031C 0x0000 0x5 0x0

这 5 个值的含义如下所示：

<mux_reg conf_reg input_reg mux_mode input_val>

0x0090表示UART1_RTS_B的iomux寄存器
0x031C表示UART1_RTS_B的电器属性寄存器
0x0000表示input寄存器
0x5表示复用成模式5
0x0表示input寄存器设置值为0x0

注意还少了一项电器属性的值啊？别急定义在dts中，0x17059就刚好是电器属性的值。

5.2.1 client如何使用pinctrl

前面讲过client包含device结构体，每个device结构体里都有一个dev_pin_info结构体，用来保存设备的pinctrl信息。platform_device匹配driver会执行probe，probe前会进行pinctrl处理，处理函数为pinctrl_bind_pins：

platform_device_register
	platform_device_add
		device_add
			bus_probe_device;
				device_initial_probe
					__device_attach
						bus_for_each_drv(dev->bus, NULL, &data, __device_attach_driver); // 对于plarform_bus_type下的每一个driver, 调用__device_attach_driver

__device_attach_driver
	driver_match_device(drv, dev);
		drv->bus->match(dev, drv)// 调用platform_bus_type.match
			driver_probe_device
				really_probe
				/* If using pinctrl, bind pins now before probing */
					pinctrl_bind_pins
					drv->probe //执行driver中的probe函数			

5.2.1.1 pinctrl_bind_pins过程

• 构造pinctrl
  • 通过pinctrl_ops.dt_node_to_map将设备树节点转换成一系列pinctrl_map
  • pinctrl_map转换成pinctrl_setting，放入settings链表，记录在pinctrl_state中
• 选择state，遍历settings链表，进行pinctrl的mux和config
  

函数调用过程：

pinctrl_bind_pins
	/* 分配dev_pin_info结构体 */
	devm_kzalloc(dev, sizeof(*(dev->pins)), GFP_KERNEL);
	/* 获取pinctrl */
	devm_pinctrl_get(dev);
		pinctrl_get
			/* 构建pinctrl */
			create_pinctrl(dev);
				/* 分配pinctrl */
				p = kzalloc(sizeof(*p), GFP_KERNEL);
				/* 设备树节点转换为pinctrl_map */
				pinctrl_dt_to_map(p);
				/* 每个pinctrl_map，又被转换为一个pinctrl_setting，添加到setting链表 */
				for_each_maps(maps_node, i, map) {
					ret = add_setting(p, map);
				}

节点转换为pinctrl_map过程：

点击查看代码

pinctrl_dt_to_map(p);
	for (state = 0; ; state++) {
		propname = kasprintf(GFP_KERNEL, "pinctrl-%d", state);
	    /* 取出pinctrl-%d节点属性 */
	   	prop = of_find_property(np, propname, &size);
	    list = prop->value;
		size /= sizeof(*list);
	   	/* 对pinctrl-%d中的每一个phandle进行pinctrl_map转换 */
	    /* 例如pinctrl-0 = <&state_0_node_a &state_0_node_b>有两个phandle */
	    for (config = 0; config < size; config++) {
	    	/* 根据phandle找到对应节点 */
	       	np_config = of_find_node_by_phandle(phandle);
	        /* Parse the node */
			dt_to_map_one_config(p, statename, np_config);
	           	/* 调用Pincontroller中dt_node_to_map函数,构造pinctrl_map */
	       		ops->dt_node_to_map()
	            /* 将pinctrl_map添加到maps链表 */
	            dt_remember_or_free_map
	            	pinctrl_register_map
	                	list_add_tail
		}
	}
 
/* fy00的dt_node_to_map函数 */
mc_pctrl_dt_node_to_map()
	/* 取出每一个子节点 */
    for_each_child_of_node(np_config, np) {
   		mc_pctrl_dt_subnode_to_map
   			/* 获取设备树pinmux属性 */
        	pins = of_find_property(node, "pinmux", NULL);
    		num_pins = pins->length / sizeof(u32);
    		for (i = 0; i < num_pins; i++) {
            	of_property_read_u32_index(node, "pinmux",i, &pinfunc); 
                /* 解析设备树，将pinmux属性中每一个成员记录在pin和func中 */
                pin = MC_GET_PIN_NO(pinfunc);
				func = MC_GET_PIN_FUNC(pinfunc);
                /* 设置复用的pinctrl_map */
                mc_pctrl_dt_node_to_map_func();
                	(*map)[*num_maps].type = PIN_MAP_TYPE_MUX_GROUP;
					(*map)[*num_maps].data.mux.group = grp->name;
                	(*map)[*num_maps].data.mux.function = mc_gpio_functions[fnum];
					(*num_maps)++;
              	if (has_config) {
                    /* 设置配置pinctrl_map，fy00没有配置pinctrl_map */
                    pinctrl_utils_add_map_configs
                        (*map)[*num_maps].type = type;
                        (*map)[*num_maps].data.configs.group_or_pin = group;
                        (*map)[*num_maps].data.configs.configs = dup_configs;
                        (*map)[*num_maps].data.configs.num_configs = num_configs;
                        (*num_maps)++;
                }
            }
		}

pinctrl_map转换为pinctrl_setting过程：

for_each_maps() {
	add_setting();
		find_state();
		if (!state)
			/* 第一次添加state到states链表 */
			create_state(p, map->name);
				list_add_tail(&state->node, &p->states);
		/* 将map的name和tpye赋值给setting */
		setting->type = map->type;
		setting->dev_name = map->dev_name;
		switch (map->type) {
			/* MUX类型 */
			case PIN_MAP_TYPE_MUX_GROUP:
				pinmux_map_to_setting(map, setting);
					/* 将pinctrl_map中的function字符串转换为序号，赋值给setting*/
					pinmux_func_name_to_selector(pctldev, map->data.mux.function);
					setting->data.mux.func = ret;
					/* 将pinctrl_map中的group字符串转换为序号，赋值给setting */
					ret = pinctrl_get_group_selector(pctldev, group);
					setting->data.mux.group = ret;
			/* CONFIGS类型 */
			case PIN_MAP_TYPE_CONFIGS_PIN:
			case PIN_MAP_TYPE_CONFIGS_GROUP:
				pinconf_map_to_setting(map, setting);
					/* 从pinctrl_map取出pin或group赋值给setting */
					setting->data.configs.group_or_pin = pin;
					/* 将pinctrl_map的configs赋值给setting */
					setting->data.configs.num_configs = map->data.configs.num_configs;
					setting->data.configs.configs = map->data.configs.configs;
			}
			/* 添加到settings链表 */
			list_add_tail(&setting->node, &state->settings);
}

pin脚的服用和配置过程：

pinctrl_bind_pins
	/* 寻找state */
	pinctrl_lookup_state
	/* 选择state */
	pinctrl_select_state
		pinctrl_commit_state
			/* 遍历settings链表 */
        	list_for_each_entry(setting, &state->settings, node) {
                switch (setting->type) {
                	case PIN_MAP_TYPE_MUX_GROUP:
                		/* 设置复用 */
                   		pinmux_enable_setting(setting);
                        	ops->set_mux(...);
                    case PIN_MAP_TYPE_CONFIGS_PIN:
					case PIN_MAP_TYPE_CONFIGS_GROUP:
						/* 设置配置 */
						pinconf_apply_setting(setting);
							ops->pin_config_group_set(...);
           }