pinctrl(2)——驱动实现与设备树配置

一、pinctrl子系统简介

1. pin control subsystem驱动的硬件叫做pin controller，主要功能包括：
(1) pin multiplexing，pin引脚复用。
(2) pin configuration，这些配置参数包括 pull-up/down电阻的设定， tri-state设定，drive-strength的设定。

2. pin controller这个HW block需要是device tree中的一个节点。此外，device也需要在它自己的device tree node中描述pin control的相关内容。也就是说引脚配置在pin controller的设备树节点中，设备的节点中通过其phandle去引用这些节点去使用。

3. 每个pin configuration都是pin controller的child node，描述了client device要使用到的一组pin的配置信息。具体如何定义pin configuration是和具体的pin controller相关的。在pin controller node中定义pin configuration其目的是为了让client device引用。

4. pinctrl driver需要根据实际情况，将系统中所有的pin组织成一个struct pinctrl_pin_desc类型的数组。

5. Pin groups

在SoC系统中，有时需要将很多pin组合在一起，以实现特定的功能，例如SPI接口、I2C接口等。因此pin controller需要以group为单位，访问、控制多个pin，这就是pin groups。相应地，pin controller subsystem需要提供一些机制，来获取系统中到底有多少groups、每个groups包含哪些pins、等等。因此，pinctrl core在struct pinctrl_ops中抽象出三个回调函数，用来获取pin groups相关信息。

struct pinctrl_ops {
    /*获取系统中pin groups的个数，后续的操作，将以相应的索引为单位(类似数组的下标，个数为数组的大小)*/
    int (*get_groups_count) (struct pinctrl_dev *pctldev); 
    /*获取指定group（由索引selector指定）的名称。*/
    const char *(*get_group_name) (struct pinctrl_dev *pctldev, unsigned selector); 
    /*获取指定group的所有pins（由索引selector指定），结果保存在pins（指针数组）和num_pins中。*/
    int (*get_group_pins) (struct pinctrl_dev *pctldev, unsigned selector, const unsigned **pins, unsigned *num_pins); 
    void (*pin_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s, unsigned offset); 
    /*将device tree中的pin state信息转换为pin map*/
    int (*dt_node_to_map) (struct pinctrl_dev *pctldev, struct device_node *np_config, struct pinctrl_map **map, unsigned *num_maps); 
    void (*dt_free_map) (struct pinctrl_dev *pctldev, struct pinctrl_map *map, unsigned num_maps); 
};

6. Pin configuration

Pin configuration 的对象是pin或者pin group，SoC中的管脚有些属性可以配置，例如上拉、下拉、高阻、驱动能力等。pinctrl subsystem使用pin configuration来封装这些功能，具体体现在struct pinconf_ops数据结构中，如下：

struct pinconf_ops { 
    #ifdef CONFIG_GENERIC_PINCONF 
    bool is_generic; 
    #endif
    /*获取指定pin (管脚的编号，由pin的注册信息获得)当前配置，保存在config指针中(配置的具体含义，只有pinctrl driver自己知道)*/
    int (*pin_config_get) (struct pinctrl_dev *pctldev, unsigned pin, unsigned long *config); 
    /*设置指定pin的配置(可以同时配置多个config，具体意义要由相应pinctrl driver)*/
    int (*pin_config_set) (struct pinctrl_dev *pctldev, unsigned pin, unsigned long *configs, unsigned num_configs); 
    /*获取指定pin group的配置项*/
    int (*pin_config_group_get) (struct pinctrl_dev *pctldev, unsigned selector, unsigned long *config); 
    /*设置指定pin group的配置项*/
    int (*pin_config_group_set) (struct pinctrl_dev *pctldev, unsigned selector, unsigned long *configs, unsigned num_configs); 
    int (*pin_config_dbg_parse_modify) (struct pinctrl_dev *pctldev, const char *arg, unsigned long *config); 
    void (*pin_config_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s, unsigned offset); 
    void (*pin_config_group_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s, unsigned selector); 
    void (*pin_config_config_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s, unsigned long config); 
}; 

kernel pinctrl subsystem 并不关心configuration的具体内容是什么，它只提供pin configuration get/set的通用机制，至于get到的东西，以及set的东西，到底是什么，是 pinctrl driver 自己的事情。后面结合pin map和pin state，就能更好地理解这种设计了。

7. Pin multiplexing(对象是pin或者pin group)

Pin multiplexing 的对象也是pin或者pin group，SoC中的很多管脚可以配置为不同的功能，这称作管脚的复用（pin multiplexing，简称为pinmux）。kernel pinctrl subsystem使用struct pinmux_ops来抽象pinmux有关的操作，如下：

struct pinmux_ops {
    /*检查某个pin是否已作它用，用于管脚复用时的互斥（避免多个功能同时使用某个pin而不知道，导致奇怪的错误）*/
    int (*request) (struct pinctrl_dev *pctldev, unsigned offset); 
    /*request的反操作。*/
    int (*free) (struct pinctrl_dev *pctldev, unsigned offset); 
    /*获取系统中function的个数。*/
    int (*get_functions_count) (struct pinctrl_dev *pctldev); 
    /*获取指定function的名称。*/
    const char *(*get_function_name) (struct pinctrl_dev *pctldev, unsigned selector); 
    /*获取指定function所占用的pin group（可以有多个）。*/
    int (*get_function_groups) (struct pinctrl_dev *pctldev, unsigned selector, const char * const **groups, unsigned *num_groups); 
    /*将指定的pin group（group_selector）设置为指定的function（func_selector）。*/
    int (*set_mux) (struct pinctrl_dev *pctldev, unsigned func_selector, unsigned group_selector); 
    /*下面是gpio有关的操作*/
    int (*gpio_request_enable) (struct pinctrl_dev *pctldev, struct pinctrl_gpio_range *range, unsigned offset); 
    void (*gpio_disable_free) (struct pinctrl_dev *pctldev, struct pinctrl_gpio_range *range, unsigned offset); 
    int (*gpio_set_direction) (struct pinctrl_dev *pctldev, struct pinctrl_gpio_range *range, unsigned offset, bool input); 
    bool strict; 
};

注释：

(1)为了管理SoC的管脚复用，pinctrl subsystem抽象出function的概念，用来表示I2C0、UART5等功能。pin（或者pin group）所对应的function一经确定，它们的管脚复用状态也就确定了。

(2)和pin group类似，pinctrl core不关心function的具体形态，只要求pinctrl driver将SoC的所有可能的function枚举出来（格式自行定义，不过需要有编号、名称等内容），并注册给pinctrl core。后续pinctrl core将会通过function的索引，访问、控制相应的function。

(3)同一个function（如I2C0），可能可以map到不同的pin（或者pin group）上。

8. pinctrl subsystem的控制逻辑

8.1 pin state

pin(pin group)以及相应的function和configuration的组合，可以确定一个设备的一个“状态”。这个状态在pinctrl subsystem中就称作pin state。

8.2 pin map

(1) 在pinctrl subsystem中，pin state有关的信息是通过pin map收集，相关的数据结构如下：

/* include/linux/pinctrl/machine.h */
struct pinctrl_map { 
    const char *dev_name; //device的名称。
    const char *name; //pin state的名称。
    enum pinctrl_map_type type;
    const char *ctrl_dev_name; //pin controller device的名字。
    /*
    data，该map需要用到的数据项， 如果map的类型是 PIN_MAP_TYPE_CONFIGS_GROUP,
    则为struct pinctrl_map_mux 类型的变量；
    如果map的类型是 PIN_MAP_TYPE_CONFIGS_PIN 或者 PIN_MAP_TYPE_CONFIGS_GROUP，
    则为struct pinctrl_map_configs 类型的变量。
    */
    union { 
        struct pinctrl_map_mux mux;
        struct pinctrl_map_configs configs;
    } data; 
};

/*
type取值包括：
PIN_MAP_TYPE_MUX_GROUP 配置管脚复用
PIN_MAP_TYPE_CONFIGS_PIN 配置pin
PIN_MAP_TYPE_CONFIGS_GROUP 配置pin group 
PIN_MAP_TYPE_DUMMY_STATE 不需要任何配置，仅仅为了表示state的存在。
*/

struct pinctrl_map_mux的定义如下：

struct pinctrl_map_mux { 
    const char *group; //group的名字，指明该map所涉及的pin group。
    const char *function; //function的名字，表示该map需要将group配置为哪种function。
};

struct pinctrl_map_configs的定义如下：

struct pinctrl_map_configs { 
    const char *group_or_pin; //pin或者pin group的名字。
    unsigned long *configs; //configuration数组，指明要将该group或pin配置成“什么样子”。
    unsigned num_configs; //配置项的个数。
};  

注：讲到这里，应该理解为什么struct pinconf_ops中的api，都不知道configuration到底是什么东西了吧，因为都是pinctrl driver自己安排好的，自产自销，外人（pinctrl subsystem以及consumers）没必要理解！

(2) 通过dts生成pin map

在旧时代，kernel的bsp工程师需要在machine有关的代码中，静态的定义pin map数组，这一个非常繁琐且不易维护的过程。不过当kernel引入device tree之后，事情就简单了很多：pinctrl driver确定了pin map各个字段的格式之后，就可以在dts文件中维护pin state以及相应的mapping table。pinctrl core在初始化的时候，会读取并解析dts，并生成pin map。而各个consumer，可以在自己的dts node中，直接引用pinctrl driver定义的pin state，并在设备驱动的相应的位置，调用pinctrl subsystem提供的API，active或者deactive这些state。至于dts中pin map描述的格式是什么，则完全由pinctrl driver自己决定，因为，最终的解析工作（dts to map）也是它自己做的。

9.Consumer驱动对pinctrl子系统的使用

(1) 设备树中配置好。

(2) 驱动中调用 pinctrl_get / devm_pinctrl_get 接口，获得一个struct pinctrl类型的handle指针，此函数调用如下：

pinctrl_get 
    create_pinctrl //drivers/pinctrl/core.c
        pinctrl_dt_to_map //drivers/pinctrl/devicetree.c
            dt_to_map_one_config 
                pctlops->dt_node_to_map

(3) 调用 pinctrl_select_state()选择一个state，使自己的某个pin state生效。

(4) 调用pinctrl subsystem提供的其它API，pinctrl subsystem进而调用pinctrl driver提供的各种回调函数，配置pin controller的硬件。

注：在设备和驱动在探测(probe)之前，就已经调用了pinctrl_bind_pins()来获取4钟state的引脚配置了，保存在struct device结构的struct dev_pin_info pins成员中，也可以从中直接获取。

struct dev_pin_info {
    struct pinctrl *p;
    struct pinctrl_state *default_state;
    struct pinctrl_state *init_state;
#ifdef CONFIG_PM
    struct pinctrl_state *sleep_state;
    struct pinctrl_state *idle_state;
#endif
};

really_probe
    pinctrl_bind_pins
        dev->pins->default_state = pinctrl_lookup_state(dev->pins->p, PINCTRL_STATE_DEFAULT);
        dev->pins->init_state = pinctrl_lookup_state(dev->pins->p, PINCTRL_STATE_INIT); /*这里会根据init state在设备树中是否配置来选择是能"init tate"还是"default state"*/
        dev->pins->sleep_state = pinctrl_lookup_state(dev->pins->p, PINCTRL_STATE_SLEEP);
        dev->pins->idle_state = pinctrl_lookup_state(dev->pins->p, PINCTRL_STATE_IDLE);

二、pinctrl设备树配置

(1) client device的DTS

一个典型的device tree中的外设node定义如下：

device-node-name {  
    ......
    pinctrl-names = "sleep", "active";
    pinctrl-0 = <pin-config-0-a>; //pinctrl-x是一个句柄（phandle）列表，每个句柄指向一个pin configuration。
    pinctrl-1 = <pin-config-1-a>;
    ......
};

如果设备树中没有通过 pinctrl-names 字段指定state的话，由解析函数 pinctrl_dt_to_map() 可知，statename 降为pinctrl-X的X字符。

(2) pinctrl host的设备树配置

pinctrl@f120000 {
    ......
    uart2_pins {
        uart2_active {
            phandle = <0x261>;
            mux {
                pins = "gpio117", "gpio118";
                function = "qup2";
            };
            config {
                pins = "gpio117", "gpio118";
                drive-strength = <0x2>;
                bias-disable;
            };
        };

        uart2_sleep {
            phandle = <0x262>;
            mux {
                pins = "gpio117", "gpio118";
                function = "gpio";
            };
            config {
                pins = "gpio117", "gpio118";
                drive-strength = <0x2>;
                bias-pull-down;
            };
        };
    };
};

举例：

/* 1.1 设备端的设备树配置 */
i2c@990000 {
    compatible = "qcom,i2c-geni";
    ......
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <0x27d>;   //default状态对应下面的phandle = <0x27d>;
    pinctrl-1 = <0x27e>;   //sleep状态对应下面的phandle = <0x27e>;
    ......
};

/* 1.2 pinctrl host端的设备树配置 */    
qup7_i2c_pins {
    phandle = <0x480>;

    qup7_i2c_active {
        phandle = <0x27d>;
        mux {
            pins = "gpio20", "gpio21";
            function = "qup7";
        };
        config {
            pins = "gpio20", "gpio21";
            drive-strength = <0x2>;
            bias-disable;
        };
    };

    qup7_i2c_sleep {
        phandle = <0x27e>;
        mux {
            pins = "gpio20", "gpio21";
            function = "gpio";
        };
        config {
            pins = "gpio20", "gpio21";
            drive-strength = <0x2>;
            bias-no-pull;
        };
    };
};

注：phandle是dtb反编译成dts文件后额外生成的，源设备树文件中没有这个域，对应关系如下：

1. 设备树种的配置

tsif1_signals_active: tsif1_signals_active {
    tsif2_clk {
        pins = "gpio73";
        function = "tsif1_clk";
    };
};

tsif1_sync_active: tsif1_sync_active {
    tsif2_sync {
        pins = "gpio76";
        function = "tsif1_sync";
        drive_strength = <2>;    /* 2 mA */
        bias-pull-down;        /* pull down */
    };
};
        
tspp: msm_tspp@8880000 {
    compatible = "qcom,msm_tspp";
    ...
    pinctrl-4 = <&tsif1_signals_active &tsif1_sync_active>;        /* tsif1-mode2 */
    ...
}

2.dtb反解析后的配置：

tsif1_signals_active {
    phandle = <0x9f>; //反编译后生成的，原始设备树种没有。

    tsif2_clk {
        pins = "gpio73";
        function = "tsif1_clk";
    };
};

tsif1_sync_active {
    phandle = <0xa0>; //dtb反编译成dts才生成的，只是这个是增加的，其它的没有变。

    tsif2_sync {
        pins = "gpio76";
        function = "tsif1_sync";
        drive_strength = <0x2>;
        bias-pull-down;
    };
};

msm_tspp@8880000 {
    compatible = "qcom,msm_tspp";
    ...
    pinctrl-4 = <0x9f 0xa0>; //反编译后的使用的是phandle值来代替"&节点名称"
    ...
}

三、gpio子系统与pinctrl子系统之间的耦合关系

1. gpio subsystem是pinctrl subsystem的client，基于pinctrl subsystem提供的功能，处理GPIO有关的逻辑。 

2. pinctrl中和gpio有关的后门

static inline int pinctrl_request_gpio(unsigned gpio) ; 
static inline void pinctrl_free_gpio(unsigned gpio) ; 
static inline int pinctrl_gpio_direction_input(unsigned gpio); 
static inline int pinctrl_gpio_direction_output(unsigned gpio);

当 gpio driver 需要使用某个管脚的时候，直接调用 pinctrl_request_gpio，向pinctrl subsystem申请。pinctrl subsystem会维护一个gpio number到pin number的map，将gpio subsystem传来的gpio number转换为pin number之后，调用 struct pinmux_ops 中有关的回调函数即可：

struct pinmux_ops { 
    ... 
    int (*gpio_request_enable) (struct pinctrl_dev *pctldev, struct pinctrl_gpio_range *range, unsigned offset); 
    void (*gpio_disable_free) (struct pinctrl_dev *pctldev, struct pinctrl_gpio_range *range, unsigned offset); 
    int (*gpio_set_direction) (struct pinctrl_dev *pctldev, struct pinctrl_gpio_range *range, unsigned offset, bool input); 
};

对gpio driver来说，要做的事情就是提供gpio number到pin number的map。而pinctrl subsystem呢，做自己分内的事情即可：管理系统的pin资源，并根据gpio subsystem的请求，将某些pin设置为GPIO功能。   

4. gpio number通过struct pinctrl_gpio_range结构映射到pin number

(1) gpio number和pin number的map是通过一个名称为gpio range的数据结构(pinctrl subsystem提供的），如下：

struct pinctrl_gpio_range { 
    struct list_head node; 
    const char *name; 
    unsigned int id; 
    unsigned int base; 
    unsigned int pin_base; 
    unsigned const *pins; 
    unsigned int npins; 
    struct gpio_chip *gc; 
};

就是：gpio controller(gc)中的gpio(base)到gpio(base + npins - 1) 和 pin controller中的 pin(pin_base) 到 pin(pin_base + npins - 1) 是一一对应的。

(2) gpio range dts node的解析过程大致如下

devm_gpiochip_add_data(drivers/gpio/gpiolib.c) 
    gpiochip_add_data 
        of_gpiochip_add(drivers/gpio/gpiolib-of.c) 
            of_gpiochip_add_pin_range 
                gpiochip_add_pin_range(drivers/gpio/gpiolib.c) 
                    pinctrl_find_and_add_gpio_range(drivers/pinctrl/core.c) 
                        pinctrl_add_gpio_range

以上过程的结果，就是在相应的pin controller device的数据结构中生成了一个gpio range的链表，如下：

struct pinctrl_dev { 
    struct list_head node; 
    struct pinctrl_desc *desc; 
    struct radix_tree_root pin_desc_tree; 
    struct list_head gpio_ranges; 
    ... 
};

(3) gpio range的使用

当gpio driver需要使用某一个gpio的时候，可以在gpiochip的request函数中，调用pinctrl core提供的pinctrl_request_gpio()接口（参数是gpio编号），然后pinctrl core会查寻gpio ranges链表，将gpio编号转换成pin编号，然后调用pinctrl的相应接口（参数是pin编号），申请该pin的使用。这就是gpio subsystem和pinctrl subsystem的耦合。