第十六章 GPIO 和 Pinctrl 子系統(tǒng)的使用

參考文檔：
a. 內核 Documentation\devicetree\bindings\Pinctrl\ 目錄下：

Pinctrl-bindings.txt 

b. 內核 Documentation\gpio 目錄下：

Pinctrl-bindings.txt 

c. 內核 Documentation\devicetree\bindings\gpio 目錄下：

gpio.txt 

注意：本章的重點在于“使用”，深入講解放在“驅動大全”的視頻里。
前面的視頻，我們使用直接操作寄存器的方法編寫驅動。這只是為了讓大家掌握驅動程序的本質，在實際開發(fā)過程中我們可不這樣做，太低效了！如果驅動開發(fā)都是這樣去查找寄存器，那我們就變成“寄存器工程師”了，即使是做單片機的都不執(zhí)著于裸寫寄存器了。
Linux 下針對引腳有 2 個重要的子系統(tǒng)：GPIO、Pinctrl。

16.1 Pinctrl 子系統(tǒng)重要概念

16.1.1 引入

無論是哪種芯片，都有類似下圖的結構：

要想讓 pinA、B 用于 GPIO，需要設置 IOMUX 讓它們連接到 GPIO 模塊；
要想讓 pinA、B 用于 I2C，需要設置 IOMUX 讓它們連接到 I2C 模塊。
所以 GPIO、I2C 應該是并列的關系，它們能夠使用之前，需要設置 IOMUX。有時候并不僅僅是設置 IOMUX，還要配置引腳，比如上拉、下拉、開漏等等。

現(xiàn)在的芯片動輒幾百個引腳，在使用到 GPIO 功能時，讓你一個引腳一個引腳去找對應的寄存器，這要瘋掉。術業(yè)有專攻，這些累活就讓芯片廠家做吧──他們是 BSP 工程師。我們在他們的基礎上開發(fā)，我們是驅動工程師。開玩笑的，BSP 工程師是更懂他自家的芯片，但是如果驅動工程師看不懂他們的代碼，那你的進步也有限啊。

所以，要把引腳的復用、配置抽出來，做成 Pinctrl子系統(tǒng)，給 GPIO、I2C等模塊使用。 BSP工程師要做什么？看下圖：

等 BSP工程師在 GPIO子系統(tǒng)、Pinctrl子系統(tǒng)中把自家芯片的支持加進去后，我們就可以非常方便地使用這些引腳了：點燈簡直太簡單了。
等等，GPIO模塊在圖中跟 I2C不是并列的嗎？干嘛在講 Pinctrl時還把 GPIO子系統(tǒng)拉進來？
大多數(shù)的芯片，沒有單獨的 IOMUX模塊，引腳的復用、配置等等，就是在 GPIO模塊內部實現(xiàn)的。 在硬件上 GPIO和 Pinctrl是如此密切相關，在軟件上它們的關系也非常密切。
所以這 2個子系統(tǒng)我們一起講解。

16.1.2 重要概念

從設備樹開始學習 Pintrl會比較容易。
主要參考文檔是：內核 Documentation\devicetree\bindings\pinctrl\pinctrl-bindings.txt
這會涉及 2個對象：pin controller、client device。
前者提供服務：可以用它來復用引腳、配置引腳。
后者使用服務：聲明自己要使用哪些引腳的哪些功能，怎么配置它們。

a. pin controller：
在芯片手冊里你找不到 pin controller，它是一個軟件上的概念，你可以認為它對應 IOMUX──用來復用引腳，還可以配置引腳(比如上下拉電阻等)。
注意，pin controller和 GPIO Controller不是一回事，前者控制的引腳可用于 GPIO功能、I2C功能；后者只是把引腳配置為輸出、輸出等簡單的功能。

b. client device
“客戶設備”，誰的客戶？Pinctrl系統(tǒng)的客戶，那就是使用 Pinctrl系統(tǒng)的設備，使用引腳的設備。它在設備樹里會被定義為一個節(jié)點，在節(jié)點里聲明要用哪些引腳。
下面這個圖就可以把幾個重要概念理清楚：

上圖中，左邊是 pincontroller節(jié)點，右邊是 client device節(jié)點：

a. pin state：
對于一個“client device”來說，比如對于一個 UART設備，它有多個“狀態(tài)”：default、sleep等，那對應的引腳也有這些狀態(tài)。
怎么理解？
比如默認狀態(tài)下，UART設備是工作的，那么所用的引腳就要復用為 UART功能。
在休眠狀態(tài)下，為了省電，可以把這些引腳復用為 GPIO功能；或者直接把它們配置輸出高電平。
上圖中，pinctrl-names里定義了 2種狀態(tài)：default、sleep。
第 0種狀態(tài)用到的引腳在 pinctrl-0中定義，它是 state_0_node_a，位于 pincontroller節(jié)點中。
第 1種狀態(tài)用到的引腳在 pinctrl-1中定義，它是 state_1_node_a，位于 pincontroller節(jié)點中。
當這個設備處于 default狀態(tài)時，pinctrl子系統(tǒng)會自動根據(jù)上述信息把所用引腳復用為 uart0功能。
當這這個設備處于 sleep狀態(tài)時，pinctrl子系統(tǒng)會自動根據(jù)上述信息把所用引腳配置為高電平。

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

c. Generic pin multiplexing node和 Generic pin configuration node
在上圖左邊的 pin controller節(jié)點中，有子節(jié)點或孫節(jié)點，它們是給 client device使用的。 可以用來描述復用信息：哪組(group)引腳復用為哪個功能(function)；
可以用來描述配置信息：哪組(group)引腳配置為哪個設置功能(setting)，比如上拉、下拉等。

注意：pin controller節(jié)點的格式，沒有統(tǒng)一的標準！！！！每家芯片都不一樣。 甚至上面的 group、function關鍵字也不一定有，但是概念是有的。

16.1.3 示例

16.1.4 代碼中怎么引用pinctrl

這是透明的，我們的驅動基本不用管。當設備切換狀態(tài)時，對應的 pinctrl就會被調用。 比如在 platform_device和 platform_driver的枚舉過程中，流程如下：

當系統(tǒng)休眠時，也會去設置該設備 sleep狀態(tài)對應的引腳，不需要我們自己去調用代碼。

非要自己調用，也有函數(shù)：

devm_pinctrl_get_select_default(struct device *dev);      // 使用"default"狀態(tài)的引腳 
pinctrl_get_select(struct device *dev, const char *name); // 根據(jù) name選擇某種狀態(tài)的引腳 
pinctrl_put(struct pinctrl *p);   // 不再使用, 退出時調用 

16.2 GPIO子系統(tǒng)重要概念

16.2.1 引入

要操作 GPIO引腳，先把所用引腳配置為 GPIO功能，這通過 Pinctrl子系統(tǒng)來實現(xiàn)。
然后就可以根據(jù)設置引腳方向(輸入還是輸出)、讀值──獲得電平狀態(tài)，寫值──輸出高低電平。 以前我們通過寄存器來操作 GPIO引腳，即使 LED驅動程序，對于不同的板子它的代碼也完全不同。 當 BSP工程師實現(xiàn)了 GPIO子系統(tǒng)后，我們就可以：
a. 在設備樹里指定 GPIO引腳
b. 在驅動代碼中：
使用 GPIO子系統(tǒng)的標準函數(shù)獲得 GPIO、設置 GPIO方向、讀取/設置 GPIO值。
這樣的驅動代碼，將是單板無關的。

16.2.2 在設備樹中指定引腳

在幾乎所有 ARM芯片中，GPIO都分為幾組，每組中有若干個引腳。所以在使用 GPIO子系統(tǒng)之前，就要先確定：它是哪組的？組里的哪一個？
在設備樹中，“GPIO組”就是一個 GPIO Controller，這通常都由芯片廠家設置好。我們要做的是找到它名字，比如“gpio1”，然后指定要用它里面的哪個引腳，比如<&gpio1 0>。
有代碼更直觀，下圖是一些芯片的 GPIO控制器節(jié)點，它們一般都是廠家定義好，在 xxx.dtsi文件中：

我們暫時只需要關心里面的這 2個屬性：

gpio-controller; 
#gpio-cells = <2>; 
“gpio-controller”表示這個節(jié)點是一個 GPIO Controller，它下面有很多引腳。 
“#gpio-cells = <2>”表示這個控制器下每一個引腳要用 2個 32位的數(shù)(cell)來描述。 

為什么要用 2個數(shù)？其實使用多個 cell來描述一個引腳，這是 GPIO Controller自己決定的。比如可以用其中一個 cell來表示那是哪一個引腳，用另一個 cell來表示它是高電平有效還是低電平有效，甚至還可以用更多的 cell來示其他特性。
普遍的用法是，用第 1個 cell來表示哪一個引腳，用第 2個 cell來表示有效電平：

GPIO_ACTIVE_HIGH ： 高電平有效 
GPIO_ACTIVE_LOW  :  低電平有效 

定義 GPIO Controller是芯片廠家的事，我們怎么引用某個引腳呢？在自己的設備節(jié)點中使用屬性"[-]gpios"，示例如下：

上圖中，可以使用 gpios屬性，也可以使用 name-gpios屬性。

16.2.3 在驅動代碼中調用GPIO子系統(tǒng)

在設備樹中指定了 GPIO引腳，在驅動代碼中如何使用？
也就是 GPIO子系統(tǒng)的接口函數(shù)是什么？
GPIO子系統(tǒng)有兩套接口：基于描述符的(descriptor-based)、老的(legacy)。前者的函數(shù)都有前綴
“gpiod_”，它使用 gpio_desc結構體來表示一個引腳；后者的函數(shù)都有前綴“gpio_”，它使用一個整數(shù)來表示一個引腳。
要操作一個引腳，首先要 get引腳，然后設置方向，讀值、寫值。
驅動程序中要包含頭文件，

#include <linux/gpio/consumer.h>   // descriptor-based 或 
#include <linux/gpio.h>            // legacy 

下表列出常用的函數(shù)：

有前綴“devm_”的含義是“設備資源管理”(Managed Device Resource)，這是一種自動釋放資源的機制。它的思想是“資源是屬于設備的，設備不存在時資源就可以自動釋放”。
比如在 Linux開發(fā)過程中，先申請了 GPIO，再申請內存；如果內存申請失敗，那么在返回之前就需要先釋放 GPIO資源。如果使用 devm的相關函數(shù)，在內存申請失敗時可以直接返回：設備的銷毀函數(shù)會自動地釋放已經(jīng)申請了的 GPIO資源。
建議使用“devm_”版本的相關函數(shù)。
舉例，假設備在設備樹中有如下節(jié)點：

 foo_device { compatible = "acme,foo"; ... led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */ <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; }; 

那么可以使用下面的函數(shù)獲得引腳：

struct gpio_desc *red, *green, *blue, *power; 
red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH); 
green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH); blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH); power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); 

要注意的是，gpiod_set_value設置的值是“邏輯值”，不一定等于物理值。 什么意思？
舊的“gpio_”函數(shù)沒辦法根據(jù)設備樹信息獲得引腳，它需要先知道引腳號。
引腳號怎么確定？
在 GPIO子系統(tǒng)中，每注冊一個 GPIO Controller時會確定它的“base number”，那么這個控制器里的第 n號引腳的號碼就是：base number + n。
但是如果硬件有變化、設備樹有變化，這個 base number并不能保證是固定的，應該查看 sysfs來確定 base number。

16.2.4 sysfs中的訪問方法

在 sysfs中訪問 GPIO，實際上用的就是引腳號，老的方法。

a. 先確定某個 GPIO Controller的基準引腳號(base number)，再計算出某個引腳的號碼。 方法如下：
① 先在開發(fā)板的/sys/class/gpio目錄下，找到各個 gpiochipXXX目錄：

② 然后進入某個 gpiochip目錄，查看文件 label的內容
③ 根據(jù) label的內容對比設備樹
label內容來自設備樹，比如它的寄存器基地址。用來跟設備樹(dtsi文件)比較，就可以知道這對應哪一個 GPIO Controller。
下圖是在 xxxxxx_imx6ull上運行的結果，通過對比設備樹可知 gpiochip96對應 gpio4：

所以 gpio4這組引腳的基準引腳號就是 96，這也可以“cat base”來再次確認。

b. 基于 sysfs操作引腳：
以 xxxxxx_imx6ull為例，它有一個按鍵，原理圖如下：

那么 GPIO4_14的號碼是 96+14=110，可以如下操作讀取按鍵值： echo 110 >

/sys/class/gpio/export 
echo in > /sys/class/gpio/gpio110/direction 
cat /sys/class/gpio/gpio110/value 
echo  110 > /sys/class/gpio/unexport 

注意：如果驅動程序已經(jīng)使用了該引腳，那么將會 export失敗，會提示下面的錯誤：
對于輸出引腳，假設引腳號為 N，可以用下面的方法設置它的值為 1： echo N >

/sys/class/gpio/export 
echo out > /sys/class/gpio/gpioN/direction 
echo 1 > /sys/class/gpio/gpioN/value 
echo  N > /sys/class/gpio/unexport 

16.3 基于GPIO子系統(tǒng)的LED驅動程序

16.3.1 編寫思路

GPIO的地位跟其他模塊，比如 I2C、UART的地方是一樣的，要使用某個引腳，需要先把引腳配置為 GPIO功能，這要使用 Pinctrl子系統(tǒng)，只需要在設備樹里指定就可以。在驅動代碼上不需要我們做任何事情。
GPIO本身需要確定引腳，這也需要在設備樹里指定。
設備樹節(jié)點會被內核轉換為 platform_device。
對應的，驅動代碼中要注冊一個 platform_driver，在 probe函數(shù)中：獲得引腳、注冊 file_operations。
在 file_operations中：設置方向、讀值/寫值。

下圖就是一個設備樹的例子：

16.3.2 在設備樹中添加Pinctrl信息

有些芯片提供了設備樹生成工具，在 GUI界面中選擇引腳功能和配置信息，就可以自動生成 Pinctrl子結點。把它復制到你的設備樹文件中，再在 client device結點中引用就可以。
有些芯片只提供文檔，那就去閱讀文檔，一般在內核源碼目錄Documentation\devicetree\bindings\pinctrl下面，保存有該廠家的文檔。
如果連文檔都沒有，那只能參考內核源碼中的設備樹文件，在內核源碼目錄 arch/arm/boot/dts目錄下。
最后一步，網(wǎng)絡搜索。
Pinctrl子節(jié)點的樣式如下：

16.3.3 在設備樹中添加GPIO信息

先查看電路原理圖確定所用引腳，再在設備樹中指定：添加”[name]-gpios”屬性，指定使用的是哪一個 GPIO Controller里的哪一個引腳，還有其他 Flag信息，比如 GPIO_ACTIVE_LOW等。具體需要多少個cell來描述一個引腳，需要查看設備樹中這個 GPIO Controller節(jié)點里的“#gpio-cells”屬性值，也可以查看內核文檔。
示例如下：

16.3.4 編程示例

在實際操作過程中也許會碰到意外的問題，現(xiàn)場演示如何解決。
a. 定義、注冊一個 platform_driver
b. 在它的 probe函數(shù)里：
b.1 根據(jù) platform_device的設備樹信息確定 GPIO：gpiod_get
b.2 定義、注冊一個 file_operations結構體
b.3 在 file_operarions中使用 GPIO子系統(tǒng)的函數(shù)操作 GPIO： gpiod_direction_output、gpiod_set_value
好處：這些代碼對所有的代碼都是完全一樣的！
使用 GIT命令載后，源碼 leddrv.c位于這個目錄下：

01_all_series_quickstart\ 
05_嵌入式 Linux驅動開發(fā)基礎知識\source\ 
05_gpio_and_pinctrl\     01_led 

摘錄重點內容：
a. 注冊 platform_driver
注意下面第 122行的"xxxxxx,leddrv"，它會跟設備樹中節(jié)點的 compatible對應：

121 static const struct of_device_id xxxxxx_leds[] = { 
122     { .compatible = "xxxxxx,leddrv" }, 
123     { }, 
124 }; 
125 
126 /* 1. 定義 platform_driver */ 
127 static struct platform_driver chip_demo_gpio_driver = { 
128     .probe      = chip_demo_gpio_probe, 
129     .remove     = chip_demo_gpio_remove, 
130     .driver     = { 
131         .name   = "xxxxxx_led", 
132         .of_match_table = xxxxxx_leds, 
133     }, 
134 }; 
135 
136 /* 2. 在入口函數(shù)注冊 platform_driver */ 
137 static int __init led_init(void) 
138 { 
139     int err; 
140 
141     printk("%s %s line %d\n", __FILE__, __FUNCTION__, __LINE__); 
142 
143     err = platform_driver_register(&chip_demo_gpio_driver); 
144 
145     return err; 
146 } 

b. 在 probe函數(shù)中獲得 GPIO
核心代碼是第 87行，它從該設備(對應設備樹中的設備節(jié)點)獲取名為“l(fā)ed”的引腳。在設備樹中，必定有一屬性名為“l(fā)ed-gpios”或“l(fā)ed-gpio”。

77 /* 4. 從 platform_device獲得 GPIO 
78  *    把 file_operations結構體告訴內核：注冊驅動程序 
79  */ 
80 static int chip_demo_gpio_probe(struct platform_device *pdev) 
81 { 
82      //int err; 
83 
84      printk("%s %s line %d\n", __FILE__, __FUNCTION__, __LINE__); 
85 
86      /* 4.1 設備樹中定義有: led-gpios=<...>; */ 
87     led_gpio = gpiod_get(&pdev->dev, "led", 0); 
88      if (IS_ERR(led_gpio)) { 
89              dev_err(&pdev->dev, "Failed to get GPIO for led\n"); 
90              return PTR_ERR(led_gpio); 
91      } 
92 

c. 注冊 file_operations結構體：
這是老套路了：

93      /* 4.2 注冊 file_operations      */ 
94      major = register_chrdev(0, "xxxxxx_led", &led_drv);  /* /dev/led */ 
95 
96      led_class = class_create(THIS_MODULE, "xxxxxx_led_class"); 
97      if (IS_ERR(led_class)) { 
98              printk("%s %s line %d\n", __FILE__, __FUNCTION__, __LINE__); 
99              unregister_chrdev(major, "led"); 
100             gpiod_put(led_gpio); 
101             return PTR_ERR(led_class); 
102     } 
103 
104     device_create(led_class, NULL, MKDEV(major, 0), NULL, "xxxxxx_led%d", 0); /* /dev/xxxxxx_led0 */ 
105 

d. 在 open函數(shù)中調用 GPIO函數(shù)設置引腳方向：

51 static int led_drv_open (struct inode *node, struct file *file) 
52 { 
53      //int minor = iminor(node); 
54 
55      printk("%s %s line %d\n", __FILE__, __FUNCTION__, __LINE__); 56      /* 根據(jù)次設備號初始化 LED */ 
57      gpiod_direction_output(led_gpio, 0); 
58 
59      return 0; 
60 } 

e. 在 write函數(shù)中調用 GPIO函數(shù)設置引腳值：

34 /* write(fd, &val, 1); */ 
35 static ssize_t led_drv_write (struct file *file, const char __user *buf, size_t size, loff_t *offset) 
36 { 
37      int err; 
38      char status; 
39      //struct inode *inode = file_inode(file); 
40      //int minor = iminor(inode); 
41 
42      printk("%s %s line %d\n", __FILE__, __FUNCTION__, __LINE__); 
43      err = copy_from_user(&status, buf, 1); 
44 
45      /* 根據(jù)次設備號和 status控制 LED */ 
46      gpiod_set_value(led_gpio, status); 
47 
48      return 1; 
49 } 

f. 釋放 GPIO：

gpiod_put(led_gpio); 

16.4 在xxxxxx_IMX6ULL上機實驗

16.4.1 確定引腳并生成設備樹節(jié)點

NXP公司對于 IMX6ULL芯片，有設備樹生成工具。我們也把它上傳到 GIT去了，使用 GIT命令載后，在這個目錄下：

01_all_series_quickstart\ 
05_嵌入式 Linux驅動開發(fā)基礎知識\source\ 
05_gpio_and_pinctrl\ 
tools\ 
imx\ 

安裝“ Pins_Tool_for_i.MX_Processors_v6_x64.exe”后運行，打開 IMX6ULL的配置文件
“MCIMX6Y2xxx08.mex”，就可以在 GUI界面中選擇引腳，配置它的功能，這就可以自動生成 Pinctrl的子節(jié)點信息。
xxxxxx_IMX6ULL使用的 LED原理圖如下，可知引腳是 GPIO5_3：

在設備樹工具中，如下圖操作：

把自動生成的設備樹信息，放到內核源碼 arch/arm/boot/dts/xxxxxx_imx6ull-14x14.dts中，代碼如下：
a. Pinctrl信息：

&iomuxc_snvs { 
…… myled_for_gpio_subsys: myled_for_gpio_subsys{  fsl,pins = < MX6ULL_PAD_SNVS_TAMPER3__GPIO5_IO03        0x000110A0 >; }; 

b. 設備節(jié)點信息(放在根節(jié)點下)：

myled { compatible = "xxxxxx,leddrv"; pinctrl-names = "default"; pinctrl-0 = <&myled_for_gpio_subsys>; led-gpios = <&gpio5 3 GPIO_ACTIVE_LOW>;         

};

16.4.2 編譯程序

編譯設備樹后，要更新設備樹。

編譯驅動程序時，“l(fā)eddrv_未測試的原始版本.c”是有錯誤信息的，“l(fā)eddrv.c”是修改過的。 測試方法，在板子上執(zhí)行命令：

# insmod  leddrv.ko 
# ls /dev/xxxxxx_led0 
# ./ledtest /dev/xxxxxx_led0 on 
# ./ledtest /dev/xxxxxx_led0 off