一文搞懂 | Linux pinctrl/gpio子系統(tǒng)

pinctrl 子系統(tǒng)和 gpio 子系統(tǒng)雖然難度不大，但在內(nèi)核里的使用率非常高，本文爭取一次性把相關內(nèi)容介紹一遍。

pinctrl

數(shù)據(jù)結構

使用 struct pinctrl_desc 抽象一個 pin controller，該結構的定義如下:

struct?pinctrl_desc?{
?const?char?*name;
?const?struct?pinctrl_pin_desc?*pins;
?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
};

pins

變量 pins 和 npins 把系統(tǒng)中所有的 pin 描述出來，并建立索引。驅動為了和具體的 pin 對應上，再將這些描述的這些 pin 組織成一個 struct pinctrl_pin_desc 類型的數(shù)組，該類型的定義為：

struct?pinctrl_pin_desc?{
?unsigned?number;
?const?char?*name;
?void?*drv_data;
};

pin groups

SoC中，有時需要將很多 pin 組合在一起，以實現(xiàn)特定的功能，例如 uart 接口、i2c 接口等。因此 pin controller 需要以 group 為單位，訪問、控制多個 pin，這就是 pin groups。

struct?group_desc?{
?const?char?*name;
?int?*pins;
?int?num_pins;
?void?*data;
};

pinctrl core在struct pinctrl_ops中抽象出三個回調(diào)函數(shù)，用來獲取pin groups相關信息，如下：

struct?pinctrl_ops?{
??//獲取系統(tǒng)中pin?groups的個數(shù)，后續(xù)的操作，將以相應的索引為單位（類似數(shù)組的下標，個數(shù)為數(shù)組的大小）
?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（指針數(shù)組）和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);
};

group 的組織方式是由驅動決定的。

pin configuration

除了上面的 pin 和 pin group，有些管腳可以配置，比如上拉，下拉，高阻等。pin configuration 來封裝這些功能，具體體現(xiàn)在 struct pinconf_ops 數(shù)據(jù)結構中，如下：

struct?pinconf_ops?{
#ifdef?CONFIG_GENERIC_PINCONF
?bool?is_generic;
#endif
??//獲取指定?pin?的當前配置，保存在?config?指針中
?int?(*pin_config_get)?(struct?pinctrl_dev?*pctldev,?unsigned?pin,?unsigned?long?*config);
??//設置指定pin的配置
?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);
??......

pin mux

為了兼容不同的應用場景，有很多管腳可以配置為不同的功能，例如A和B兩個管腳，既可以當作普通的GPIO使用，又可以配置為I2C的的SCL和SDA，也可以配置為UART的TX和RX，這稱作管腳的復用（簡稱 pin mux）。使用 struct pinmux_ops 來抽象 pin mux 有關的操作，如下：

struct?pinmux_ops?{
??//檢查某個pin是否已作它用，用于管腳復用時的互斥
?int?(*request)?(struct?pinctrl_dev?*pctldev,?unsigned?offset);
??//request的反操作
?int?(*free)?(struct?pinctrl_dev?*pctldev,?unsigned?offset);
??//獲取系統(tǒng)中function的個數(shù)
?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);
??//為true時，說明該pin?controller不允許某個pin作為gpio和其它功能同時使用
?bool?strict;
};

pin state

根據(jù)前面的描述，pinctrl driver 抽象出來了一些離散的對象：pin（pin group）、function、configuration，并實現(xiàn)了這些對象的控制和配置方式。然后我們回到某一個具體的 device 上（如 lpuart，usdhc）。一個設備在某一狀態(tài)下（如工作狀態(tài)、休眠狀態(tài)、等等），所使用的pin（pin group）、pin（pin group）的 function 和 configuration，是唯一確定的。所以固定的組合可以確定固定的狀態(tài)，在設備樹里用 pinctrl-names 指明狀態(tài)名字，pinctrl-x 指明狀態(tài)引腳。

pin map

pin state 有關的信息是通過 pin map 收集，相關的數(shù)據(jù)結構如下：

struct?pinctrl_map?{
??//device的名稱
?const?char?*dev_name;
??//pin?state的名稱
?const?char?*name;
??//該map的類型
?enum?pinctrl_map_type?type;
??//pin?controller?device的名字
?const?char?*ctrl_dev_name;
?union?{
??struct?pinctrl_map_mux?mux;
??struct?pinctrl_map_configs?configs;
?}?data;
};

enum?pinctrl_map_type?{
?PIN_MAP_TYPE_INVALID,
?//不需要任何配置，僅僅為了表示state的存在
?PIN_MAP_TYPE_DUMMY_STATE,
?//配置管腳復用
?PIN_MAP_TYPE_MUX_GROUP,
?//配置pin
?PIN_MAP_TYPE_CONFIGS_PIN,
?//配置pin?group
?PIN_MAP_TYPE_CONFIGS_GROUP,
};

struct?pinctrl_map_mux?{
?//group的名字
?const?char?*group;
?//function的名字
?const?char?*function;
};

struct?pinctrl_map_configs?{
?//該pin或者pin?group的名字
?const?char?*group_or_pin;
?//configuration數(shù)組
?unsigned?long?*configs;
?//配置項的個數(shù)
?unsigned?num_configs;
};

pinctrl driver 確定了 pin map 各個字段的格式之后，就可以在 dts 文件中維護 pin state 以及相應的 mapping table。pinctrl core 在初始化的時候，會讀取并解析 dts，并生成 pin map。

而各個 consumer，可以在自己的 dts node 中，直接引用 pinctrl driver 定義的 pin state，并在設備驅動的相應的位置，調(diào)用 pinctrl subsystem 提供的 API（pinctrl_lookup_state，pinctrl_select_state），active 或者 deactive 這些 state。

pin controller 驅動初始化

我們再來回憶下 pin 控制器的描述符：

struct?pinctrl_desc?{
?const?char?*name;
?const?struct?pinctrl_pin_desc?*pins;
?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
};

pin 控制器描述符中包括了三類操作函數(shù)：pctlops 是一些全局的控制函數(shù)；pmxops 是復用引腳相關的操作函數(shù)；confops操作函數(shù)是用來配置引腳的特性。pin 控制器驅動的初始化主要是注冊這三類函數(shù)的回調(diào)。

struct pinctrl_ops *pctlops

struct pinmux_ops *pmxops

struct pinconf_ops *confops

pinctrl subsystem 的整體流程

pinctrl driver 根據(jù) pin controller 的實際情況，定義 struct pinctrl_desc（包括pin/pin group 的抽象，function 的抽象，pinconf、pinmux 的 operation API 實現(xiàn)，dt_node_to_map 的實現(xiàn)，等等），并注冊到 kernel 中。

pinctrl driver 在 pin controller的 dts node 中，根據(jù)自己定義的格式，描述每個 device 的所有 pin state。如下所示：

&iomuxc1?{
?......
????pinctrl_lpuart5:?lpuart5grp?{
????????????fsl,pins?=?<
????????????????????MX8ULP_PAD_PTF14__LPUART5_TX????0x3
????????????????????MX8ULP_PAD_PTF15__LPUART5_RX????0x3
????????????>;
????};
?......
?pinctrl_usdhc0:?usdhc0grp?{
????????????fsl,pins?=?<
????????????????????MX8ULP_PAD_PTD1__SDHC0_CMD??????0x3
????????????????????MX8ULP_PAD_PTD2__SDHC0_CLK??????0x10002
????????????????????MX8ULP_PAD_PTD10__SDHC0_D0??????0x3
????????????????????MX8ULP_PAD_PTD9__SDHC0_D1???????0x3
????????????????????MX8ULP_PAD_PTD8__SDHC0_D2???????0x3
????????????????????MX8ULP_PAD_PTD7__SDHC0_D3???????0x3
????????????????????MX8ULP_PAD_PTD6__SDHC0_D4???????0x3
????????????????????MX8ULP_PAD_PTD5__SDHC0_D5???????0x3
????????????????????MX8ULP_PAD_PTD4__SDHC0_D6???????0x3
????????????????????MX8ULP_PAD_PTD3__SDHC0_D7???????0x3
????????????????????MX8ULP_PAD_PTD11__SDHC0_DQS?????0x10002
????????????>;
????};
?......
}

相應的 consumer driver 可以在自己的 dts node 中，引用 pinctrl driver 所定義的 pin state，如下所示：

&lpuart5?{
????????/*?console?*/
????????pinctrl-names?=?"default",?"sleep";
????????pinctrl-0?=?<&pinctrl_lpuart5>;
????????pinctrl-1?=?<&pinctrl_lpuart5>;
????????status?=?"okay";
};

&usdhc0?{
????????pinctrl-names?=?"default",?"state_100mhz",?"state_200mhz",?"sleep";
????????pinctrl-0?=?<&pinctrl_usdhc0>;
????????pinctrl-1?=?<&pinctrl_usdhc0>;
????????pinctrl-2?=?<&pinctrl_usdhc0>;
????????pinctrl-3?=?<&pinctrl_usdhc0>;
????????non-removable;
????????bus-width?=?<8>;
????????status?=?"okay";
};

consumer driver 在需要的時候，可以調(diào)用 pinctrl_get/devm_pinctrl_get 接口，獲得一個 pinctrl handle（struct pinctrl類型的指針）。在 pinctrl get 的過程中，解析 consumer device 的 dts node，找到相應的 pin state，進行調(diào)用 pinctrl driver 提供的 dt_node_to_map 接口，解析 pin state 并轉換為 pin map。

例子

上圖中，左邊是 pin controller 節(jié)點，右邊是 client device 節(jié)點 。

pin state

對于一個“client device”來說，比如對于一個 UART 設備，它有多個“狀態(tài)”：default、sleep 等，那對應的引腳也有這些狀態(tài)。比如當這個設備處于 default 狀態(tài)時，pinctrl 子系統(tǒng)會自動根據(jù)上述信息把所用引腳復用為 uart0 功能。當這這個設備處于 sleep 狀態(tài)時，pinctrl 子系統(tǒng)會自動根據(jù)上述信息把所用引腳配置為高電平。

groups 和 function

一個設備會用到一個或多個引腳，這些引腳就可以歸為一組 group。這些引腳可以復用為某個功能 function。當然，一個設備可以用到多組多功能引腳，比如A1、A2兩組引腳，A1組復用為F1功能，A2組復用為F2功能。

sysfs 訪問方法

gpio

數(shù)據(jù)結構

每個 GPIO 控制器用一個 gpio_device 來表示:

struct?gpio_device?{
?//它是系統(tǒng)中第幾個GPIO控制器
?int???id;
?struct?device??dev;
?struct?cdev??chrdev;
?struct?device??*mockdev;
?struct?module??*owner;
?//含有各類操作函數(shù)
?struct?gpio_chip?*chip;
?//每一個gpio引腳用一個gpio_desc來表示
?struct?gpio_desc?*descs;
?//這些GPIO的號碼基值
?int???base;
?//這個GPIO控制器支持多少個GPIO
?u16???ngpio;
?//標簽，名字
?char???*label;
?void???*data;
?struct?list_head????????list;
?......
};

用 gpio_chip 來定義控制引腳和中斷相關的函數(shù)：

struct?gpio_chip?{
?const?char??*label;
?struct?gpio_device?*gpiodev;
?struct?device??*parent;
?struct?module??*owner;

?//控制引腳的函數(shù),中斷相關的函數(shù)
?int???(*request)(struct?gpio_chip?*chip,
??????unsigned?offset);
?void???(*free)(struct?gpio_chip?*chip,
??????unsigned?offset);
?int???(*get_direction)(struct?gpio_chip?*chip,
??????unsigned?offset);
?int???(*direction_input)(struct?gpio_chip?*chip,
??????unsigned?offset);
?int???(*direction_output)(struct?gpio_chip?*chip,
??????unsigned?offset,?int?value);
?int???(*get)(struct?gpio_chip?*chip,
??????unsigned?offset);
?void???(*set)(struct?gpio_chip?*chip,
??????unsigned?offset,?int?value);
?void???(*set_multiple)(struct?gpio_chip?*chip,
??????unsigned?long?*mask,
??????unsigned?long?*bits);
?int???(*set_config)(struct?gpio_chip?*chip,
???????????unsigned?offset,
???????????unsigned?long?config);
?int???(*to_irq)(struct?gpio_chip?*chip,
??????unsigned?offset);

?void???(*dbg_show)(struct?seq_file?*s,
??????struct?gpio_chip?*chip);
?//GPIO控制器中引腳的號碼基值
?int???base;
?//GPIO控制器中引腳的個數(shù)
?u16???ngpio;
?//每個引腳的名字
?const?char??*const?*names;
?bool???can_sleep;
?......
};

每一個 gpio 引腳用一個 gpio_desc 來表示:

struct?gpio_desc?{
?//屬于哪個?GPIO?控制器
?struct?gpio_device?*gdev;
?unsigned?long??flags;
/*?flag?symbols?are?bit?numbers?*/
#define?FLAG_REQUESTED?0
#define?FLAG_IS_OUT?1
#define?FLAG_EXPORT?2?/*?protected?by?sysfs_lock?*/
#define?FLAG_SYSFS?3?/*?exported?via?/sys/class/gpio/control?*/
#define?FLAG_ACTIVE_LOW?6?/*?value?has?active?low?*/
#define?FLAG_OPEN_DRAIN?7?/*?Gpio?is?open?drain?type?*/
#define?FLAG_OPEN_SOURCE?8?/*?Gpio?is?open?source?type?*/
#define?FLAG_USED_AS_IRQ?9?/*?GPIO?is?connected?to?an?IRQ?*/
#define?FLAG_IS_HOGGED?11?/*?GPIO?is?hogged?*/
#define?FLAG_SLEEP_MAY_LOOSE_VALUE?12?/*?GPIO?may?loose?value?in?sleep?*/

?/*?Connection?label?*/
?//一般等于?gpio_chip?的?label
?const?char??*label;
?/*?Name?of?the?GPIO?*/
?//引腳名
?const?char??*name;
};

設備樹

GPIO一般都分為幾組，每組中有若干個引腳。所以在使用GPIO子系統(tǒng)之前，就要先確定它所在的組以及在組中的哪一個。在設備樹中，“GPIO組” 就是一個 GPIO Controller，這通常都由芯片廠家設置好。我們要做的是找到它的名字，比如“gpio1”，然后指定要用它里面的哪個引腳，比如 <&gpio1 0>。

“gpio-controller”表示這個節(jié)點是一個GPIO Controller，它下面有很多引腳。

“#gpio-cells = <2>”表示這個控制器下每一個引腳要用2個32位的數(shù)(cell)來描述。用第1個cell來表示哪一個引腳，用第2個cell來表示有效電平：GPIO_ACTIVE_HIGH(高電平有效)，GPIO_ACTIVE_LOW(低電平有效)。

怎么引用某個引腳呢？在自己的設備節(jié)點中使用屬性"[name]-gpios"，示例如下：

gpio controller 驅動

gpio client 驅動

GPIO 子系統(tǒng)有兩套接口：基于描述符的(descriptor-based)、老的(legacy)。前者的函數(shù)都有前綴 “gpiod_”，它使用 gpio_desc 結構體來表示一個引腳；后者的函數(shù)都有前綴 “gpio_”，它使用一個整數(shù)來表示一個引腳。

要操作一個引腳，首先要 get 引腳，然后設置方向，讀值、寫值。

建議使用“devm_”版本的相關函數(shù)。有前綴“devm_”的含義是“設備資源管理”(Managed Device Resource)，這是一種自動釋放資源的機制。它的思想是“資源是屬于設備的，設備不存在時資源就可以自動釋放”。

比如在 Linux 開發(fā)過程中，先申請了GPIO，再申請內(nèi)存；如果內(nèi)存申請失敗，那么在返回之前就需要先釋放GPIO資源。如果使用devm的相關函數(shù)，在內(nèi)存申請失敗時可以直接返回：設備的銷毀函數(shù)會自動地釋放已經(jīng)申請了的GPIO資源。

以上面的設備 max9286_mipi 為例，它的驅動實現(xiàn)如下：

sysfs 訪問方法

先確定某個GPIO Controller的基準引腳號(base number)，再計算出某個引腳的號碼。

然后進入某個gpiochip目錄，查看文件label的內(nèi)容，根據(jù) label 的內(nèi)容對比設備樹，就可以知道這對應哪一個 GPIO Controller。比如用上面的例子，通過對比設備樹可知 gpiochip448 對應 gpio1。

因為 pin number = base + offset，所以 GPIO1_27 的號碼是 448 + 27 = 475，那么通過 sys 可以做如下操作。

“

echo 475 > /sys/class/gpio/export

echo in > /sys/class/gpio/gpio475/direction

cat /sys/class/gpio/gpio475/value

echo 475 > /sys/class/gpio/unexport

”

pinctrl subsystem 和 gpio subsysem 之間的耦合

pinctrl subsystem 管理系統(tǒng)的所有管腳，GPIO 是這些管腳的用途之一，因此 gpio subsystem 應該是 pinctrl subsystem 的 backend。在使用 GPIO 的時候，都需要向系統(tǒng)的 pinctrl subsystem 申請管腳，并將管腳配置為 GPIO 功能。

內(nèi)核也提供了通過 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);

”

pinctrl subsystem會維護一個gpio number到pin number的map(gpio range)，將gpio subsystem傳來的gpio number轉換為pin number之后，調(diào)用struct pinmux_ops中有關的回調(diào)函數(shù)即可：

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 ranges

當 gpio driver 需要使用某一個 gpio 的時候，可以在 struct gpio_chip 的 request 函數(shù)中，調(diào)用 pinctrl core 提供的 pinctrl_request_gpio 接口（參數(shù)是gpio編號），然后 pinctrl core 會查尋 gpio ranges 鏈表，將 gpio 編號轉換成 pin 編號，然后調(diào)用 pinctrl 的相應接口（參數(shù)是pin編號），申請該 pin 的使用。