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

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

pinctrl

數(shù)據(jù)結(jié)構(gòu)

使用 struct pinctrl_desc 抽象一個 pin controller，該結(jié)構(gòu)的定義如下:

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 描述出來，并建立索引。驅(qū)動為了和具體的 pin 對應(yīng)上，再將這些描述的這些 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相關(guān)信息，如下：

struct?pinctrl_ops?{
??//獲取系統(tǒng)中pin?groups的個數(shù)，后續(xù)的操作，將以相應(yīng)的索引為單位（類似數(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指定），結(jié)果保存在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信息轉(zhuǎn)換為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 的組織方式是由驅(qū)動決定的。

pin configuration

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

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);
??//設(shè)置指定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);
??//設(shè)置指定pin?group的配置項
?int?(*pin_config_group_set)?(struct?pinctrl_dev?*pctldev,?unsigned?selector,?unsigned?long?*configs,?unsigned?num_configs);
??......

pin mux

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

struct?pinmux_ops?{
??//檢查某個pin是否已作它用，用于管腳復(fù)用時的互斥
?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）設(shè)置為指定的function（func_selector）
?int?(*set_mux)?(struct?pinctrl_dev?*pctldev,?unsigned?func_selector,?unsigned?group_selector);
??//以下是gpio相關(guān)的操作
?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）。一個設(shè)備在某一狀態(tài)下（如工作狀態(tài)、休眠狀態(tài)、等等），所使用的pin（pin group）、pin（pin group）的 function 和 configuration，是唯一確定的。所以固定的組合可以確定固定的狀態(tài)，在設(shè)備樹里用 pinctrl-names 指明狀態(tài)名字，pinctrl-x 指明狀態(tài)引腳。

pin map

pin state 有關(guān)的信息是通過 pin map 收集，相關(guān)的數(shù)據(jù)結(jié)構(gòu)如下：

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,
?//配置管腳復(fù)用
?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 以及相應(yīng)的 mapping table。pinctrl core 在初始化的時候，會讀取并解析 dts，并生成 pin map。

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

pin controller 驅(qū)動初始化

我們再來回憶下 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 是復(fù)用引腳相關(guān)的操作函數(shù)；confops操作函數(shù)是用來配置引腳的特性。pin 控制器驅(qū)動的初始化主要是注冊這三類函數(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
????????????>;
????};
?......
}

相應(yīng)的 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，找到相應(yīng)的 pin state，進行調(diào)用 pinctrl driver 提供的 dt_node_to_map 接口，解析 pin state 并轉(zhuǎn)換為 pin map。

例子

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

pin state

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

groups 和 function

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

sysfs 訪問方法

gpio

數(shù)據(jù)結(jié)構(gòu)

每個 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 來定義控制引腳和中斷相關(guān)的函數(shù)：

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

?//控制引腳的函數(shù),中斷相關(guān)的函數(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;
};

設(shè)備樹

GPIO一般都分為幾組，每組中有若干個引腳。所以在使用GPIO子系統(tǒng)之前，就要先確定它所在的組以及在組中的哪一個。在設(shè)備樹中，“GPIO組” 就是一個 GPIO Controller，這通常都由芯片廠家設(shè)置好。我們要做的是找到它的名字，比如“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(低電平有效)。

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

gpio controller 驅(qū)動

gpio client 驅(qū)動

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

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

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

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

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

sysfs 訪問方法

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

然后進入某個gpiochip目錄，查看文件label的內(nèi)容，根據(jù) label 的內(nèi)容對比設(shè)備樹，就可以知道這對應(yīng)哪一個 GPIO Controller。比如用上面的例子，通過對比設(shè)備樹可知 gpiochip448 對應(yīng) 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 應(yīng)該是 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轉(zhuǎn)換為pin number之后，調(diào)用struct pinmux_ops中有關(guān)的回調(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 編號轉(zhuǎn)換成 pin 編號，然后調(diào)用 pinctrl 的相應(yīng)接口（參數(shù)是pin編號），申請該 pin 的使用。