Documentation / zh_CN / gpio.txt

Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:17 EST.

	Chinese translated version of Documentation/gpio.txt
	
	If you have any comment or update to the content, please contact the
	original document maintainer directly.  However, if you have a problem
	communicating in English you can also ask the Chinese maintainer for
	help.  Contact the Chinese maintainer if this translation is outdated
	or if there is a problem with the translation.
	
	Maintainer: Grant Likely <grant.likely@secretlab.ca>
			Linus Walleij <linus.walleij@linaro.org>
	Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
	---------------------------------------------------------------------
	Documentation/gpio.txt 的中文翻译
	
	如果想评论或更新本文的内容，请直接�系原文档的维护者。如果你使用英文
	交�有困难的�，也�以�中文版维护者求助。如果本翻译更新��时或者翻
	译存在问题，请�系中文版维护者。
	英文版维护者： Grant Likely <grant.likely@secretlab.ca>
			Linus Walleij <linus.walleij@linaro.org>
	中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	
	
	以下为正文
	---------------------------------------------------------------------
	GPIO 接�
	
	本文档�供了一个在Linux下访问GPIO的公约概述。
	
	这些函数以 gpio_* 作为�缀。其他的函数��许使用这样的�缀或相关的
	__gpio_* �缀。
	
	
	什么是GPIO?
	==========
	"通用输入/输出�"(GPIO)是一个�活的由软件控制的数字信�。他们�
	由多�芯片�供,且对于从事嵌入�和定制硬件的 Linux 开�者�说是
	比较熟悉。�个GPIO 都代表一个连接到特定引脚或�栅阵列(BGA)�装中
	“���的一个�。电路�原�图显示了 GPIO 与外部硬件的连接关系。
	驱动�以编写�通用代�，以使�级�动代��传递引脚�置数�给驱动。
	
	片上系统 (SOC) 处�器对 GPIO 有很大的�赖。在�些情况下,�个
	�专用引脚都��置为 GPIO,且大多数芯片都最少有一些 GPIO。
	�编程逻辑器件(类似 FPGA) �以方便地�供 GPIO。�电�管�和
	音频编解�器这样的多功能芯片�常留有一些这样的引脚�帮助那些引脚
	匮�的 SOC。�时还有通过 I2C 或 SPI 串行总线连接的“GPIO扩展器�
	芯片。大多数 PC 的�桥有一些拥有 GPIO 能力的引脚 (�有BIOS
	固件�知�如何使用他们)。
	
	GPIO 的实际功能因系统而异。通常用法有:
	
	  - 输出值�写 (高电平=1，低电平=0)。一些芯片也有如何驱动这些值的选项,
	    例如��许输出一个值�支�“线与��其他�值类似的模�(值得注�的是
	    “开��信�)
	
	  - 输入值�读(1�0)。一些芯片支�引脚在�置为“输出�时回读，这对于类似
	    “线与�的情况(以支���信�)是�常有用的。GPIO 控制器�能有输入
	    去毛刺/消抖逻辑,这有时需�软件控制。
	
	  - 输入通常�作为 IRQ 信�,一般是沿触�,但有时是电平触�。这样的 IRQ
	    �能�置为系统唤醒事件,以将系统从低功耗状�下唤醒。
	
	  - 通常一个 GPIO 根���产�电路�的需求,�以�置为输入或输出,也有仅
	    支���的。
	
	  - 大部分 GPIO �以在�有自旋�时访问,但是通常由串行总线扩展的 GPIO
	    ��许�有自旋�。但�些系统也支�这�类型。
	
	对于给定的电路�,�个 GPIO 都用于�个特定的目的,如监控 MMC/SD �的
	�入/移除�检测�的写�护状��驱动 LED��置收�器�模拟串行总线�
	��硬件看门狗�感知开关状�等等。
	
	
	GPIO 公约
	=========
	注�,这个��“公约�，因为这�是强制性的，��循这个公约是无伤大雅的，
	因为此时�移�性并���。GPIO 常用于�级特定的电路逻辑,甚至�能
	��电路�的版本而改�，且��能在��走线的电路�上使用。仅有在少数
	功能上�具有�移�性，其他功能是平�特定。这也是由于“胶��的逻辑造�的。
	
	此外，这�需�任何的执行框架，�是一个接�。�个平��能通过一个简�地
	访问芯片寄存器的内�函数�实现它，其他平��能通过委托一系列��的GPIO
	控制器的抽象函数�实现它。(有一些�选的代�能支�这�策略的实现,本文档
	��会介�，但作为 GPIO 接�的客户端驱动程�必须与它的实现无关。)
	
	也就是说,如果在他们的平�上支�这个公约，驱动应尽�能的使用它。平�
	必须在 Kconfig 中声明对 GENERIC_GPIO的支� (布尔型 true)，并�供
	一个 <asm/gpio.h> 文件。那些调用标准 GPIO 函数的驱动应该在 Kconfig
	入�中声明�赖GENERIC_GPIO。当驱动包�文件:
	
		#include <linux/gpio.h>
	
	则 GPIO 函数是�用,无论是“真实代��还是�优化过的语�。如果你�守
	这个公约，当你的代�完��，对其他的开�者�说会更容易看懂和维护。
	
	注�，这些�作包�所用平�的 I/O �障代�，驱动无须显�地调用他们。
	
	
	标识 GPIO
	---------
	GPIO 是通过无符�整型�标识的,范围是 0 到 MAX_INT。�留“负�数
	用于其他目的,例如标识信�“在这个��上��用�或指示错误。未接触底层
	硬件的代�会忽略这些整数。
	
	平�会定义这些整数的用法,且通常使用 #define �定义 GPIO，这样
	�级特定的�动代��以直接关�相应的原�图。相对�说，驱动应该仅使用
	�动代�传递过�的 GPIO 编�，使用 platform_data �存�级特定
	引脚�置数� (�时还有其他须�的�级特定数�)，���能出现的问题。
	
	例如一个平�使用编� 32-159 �标识 GPIO,而在�一个平�使用编�0-63
	标识一组 GPIO 控制器,64-79标识�一类 GPIO 控制器,且在一个�有
	FPGA 的特定��上使用 80-95。编��一定�连续,那些平�中，也�以
	使用编�2000-2063�标识一个 I2C 接�的 GPIO 扩展器中的 GPIO。
	
	如果你��始化一个带有无效 GPIO 编�的结构体,�以使用一些负编�
	(如"-EINVAL")，那将使其永远�会是有效。�测试这样一个结构体中的编�
	是�关�一个 GPIO，你�使用以下断言:
	
		int gpio_is_valid(int number);
	
	如果编��存在，则请求和释放 GPIO 的函数将拒�执行相关�作(�下文)。
	其他编�也�能被拒�,比如一个编��能存在，但暂时在给定的电路上��用。
	
	一个平�是�支�多个 GPIO 控制器为平�特定的实现问题，就�是��以
	在 GPIO 编�空间中有“空洞�和是��以在�行时添加新的控制器一样。
	这些问题会影�其他事情，包括相邻的 GPIO 编�是�存在等。
	
	使用 GPIO
	---------
	对于一个 GPIO，系统应该�的第一件事情就是通过 gpio_request()
	函数分�它，�下文。
	
	接下�是设置I/O方�，这通常是在�级�动代�中为所使用的 GPIO 设置
	platform_device 时完�。
	
		/* 设置为输入或输出, 返回 0 或负的错误代� */
		int gpio_direction_input(unsigned gpio);
		int gpio_direction_output(unsigned gpio, int value);
	
	返回值为零代表�功，�则返回一个负的错误代�。这个返回值需�检查，因为
	get/set(获�/设置)函数调用没法返回错误,且有�能是�置错误。通常，
	你应该在进程上下文中调用这些函数。然而,对于自旋�安全的 GPIO，在��
	�动的早期�进程�动�使用他们也是�以的。
	
	对于作为输出的 GPIO，为其�供�始输出值，对于��在系统�动期间出现
	信�毛刺是很有帮助的。
	
	为了与传统的 GPIO 接�兼容, 在设置一个 GPIO 方�时，如果它还未被申请，
	则��了申请那个 GPIO 的�作(�下文)。这�兼容性正在从�选的 gpiolib
	框架中移除。
	
	如果这个 GPIO 编��存在，或者特定的 GPIO �能用于那�模�，则方�
	设置�能失败。�赖�动固件�正确地设置方�通常是一个�主�，因为它�能
	除了�动Linux，并没有�更多的验�工作。(��, ��的�动代��能需�
	将这个�用的引脚设置为 GPIO，并正确地�置上拉/下拉电阻。)
	
	
	访问自旋�安全的 GPIO
	-------------------
	大多数 GPIO 控制器�以通过内存读/写指令�访问。这些指令�会休眠,�以
	安全地在硬(�线程)中断例程和类似的上下文中完�。
	
	对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(�下文)，使用
	以下的函数访问:
	
		/* GPIO 输入:返回零或�零 */
		int gpio_get_value(unsigned gpio);
	
		/* GPIO 输出 */
		void gpio_set_value(unsigned gpio, int value);
	
	GPIO值是布尔值，零表示低电平，�零表示高电平。当读�一个输出引脚的值时，
	返回值应该是引脚上的值。这个值�总是和输出值相符，因为存在开�输出信�和
	输出延迟问题。
	
	以上的 get/set 函数无错误返回值，因为之� gpio_direction_*()应已检查过
	其是�为“无效GPIO�。此外，还需�注�的是并�是所有平�都�以从输出引脚
	中读�数�，对于�能读�的引脚应总返回零。�外，对那些在原�上下文中无法
	安全访问的 GPIO (译者注：因为访问�能导致休眠)使用这些函数是��适的
	(�下文)。
	
	在 GPIO 编�(还有输出�值)为常数的情况下,鼓励通过平�特定的实现�优化
	这两个函数�访问 GPIO 值。这�情况(读写一个硬件寄存器)下�需�几�指令
	是很正常的,且无须自旋�。这�优化函数比起那些在�程�上花费许多指令的
	函数�以使得模拟接�(译者注:例如 GPIO 模拟 I2C�1-wire 或 SPI)的
	应用(在空间和时间上都)更具效率。
	
	
	访问�能休眠的 GPIO
	-----------------
	�些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消�访问。读或写这些
	GPIO 值的命令需�等待其信�排到队首���命令，�获得其�馈。期间需�
	休眠，这�能在 IRQ 例程(中断上下文)中执行。
	
	支�此类 GPIO 的平�通过以下函数返回�零值�区分出这� GPIO。(此函数需�
	一个之�通过 gpio_request 分�到的有效 GPIO 编�):
	
		int gpio_cansleep(unsigned gpio);
	
	为了访问这� GPIO,内核定义了一套��的函数:
	
		/* GPIO 输入:返回零或�零 ,�能会休眠 */
		int gpio_get_value_cansleep(unsigned gpio);
	
		/* GPIO 输出,�能会休眠 */
		void gpio_set_value_cansleep(unsigned gpio, int value);
	
	
	访问这样的 GPIO 需�一个�许休眠的上下文，例如线程 IRQ 处�例程，并用以上的
	访问函数替�那些没有 cansleep()�缀的自旋�安全访问函数。
	
	除了这些访问函数�能休眠，且它们�作的 GPIO �能在硬件 IRQ 处�例程中访问的
	事实，这些处�例程实际上和自旋�安全的函数是一样的。
	
	** 除此之外 ** 调用设置和�置此类 GPIO 的函数也必须在�许休眠的上下文中，
	因为它们�能也需�访问 GPIO 控制器芯片: (这些设置函数通常在�级�动代�或者
	驱动探测/断开代�中，所以这是一个容易满足的约��件。)
	
		gpio_direction_input()
		gpio_direction_output()
		gpio_request()
	
	## 	gpio_request_one()
	##	gpio_request_array()
	## 	gpio_free_array()
	
		gpio_free()
		gpio_set_debounce()
	
	
	
	声明和释放 GPIO
	----------------------------
	为了有助于�获系统�置错误,定义了两个函数。
	
		/* 申请 GPIO, 返回 0 或负的错误代�.
		 * �空标签�能有助于诊断.
		 */
		int gpio_request(unsigned gpio, const char *label);
	
		/* 释放之�声明的 GPIO */
		void gpio_free(unsigned gpio);
	
	将无效的 GPIO 编�传递给 gpio_request()会导致失败，申请一个已使用这个
	函数声明过的 GPIO 也会失败。gpio_request()的返回值必须检查。你应该在
	进程上下文中调用这些函数。然而,对于自旋�安全的 GPIO,在���动的早期�
	进入进程之�是�以申请的。
	
	这个函数完�两个基本的目标。一是标识那些实际上已作为 GPIO 使用的信�线，
	这样便于更好地诊断;系统�能需��务几百个�用的 GPIO，但是对于任何一个
	给定的电路�通常�有一些被使用。�一个目的是�获冲�，查明错误:如两个或
	更多驱动错误地认为他们已�独�了�个信�线,或是错误地认为移除一个管��
	�个已激活信�的驱动是安全的。也就是说，申请 GPIO 的作用类似一��机制。
	
	�些平��能也使用 GPIO 作为电�管�激活信�(例如通过关闭未使用芯片区和
	简�地关闭未使用时钟)。
	
	对于 GPIO 使用 pinctrl �系统已知的引脚，�系统应该被告知其使用情况；
	一个 gpiolib 驱动的 .request()�作应调用 pinctrl_request_gpio()，
	而 gpiolib 驱动的 .free()�作应调用 pinctrl_free_gpio()。pinctrl
	�系统�许 pinctrl_request_gpio()在�个引脚或引脚组以�用形�“属于�
	一个设备时都�功返回。
	
	任何须将 GPIO 信�导�适当引脚的引脚�用硬件的编程应该�生在 GPIO
	驱动的 .direction_input()或 .direction_output()函数中，以�
	任何输出 GPIO 值的设置之�。这样�使从引脚特殊功能到 GPIO 的转�
	�会在引脚产生毛刺波形。有时当用一个 GPIO 实现其信�驱动一个� GPIO
	硬件模�的解决方案时，就需�这�机制。
	
	�些平��许部分或所有 GPIO 信�使用��的引脚。类似的，GPIO 或引脚的
	其他方�也需��置，如上拉/下拉。平�软件应该在对这些 GPIO 调用
	gpio_request()�将这类细节�置好，例如使用 pinctrl �系统的映射表，
	使得 GPIO 的用户无须关注这些细节。
	
	还有一个值得注�的是在释放 GPIO �，你必须�止使用它。
	
	
	注�:申请一个 GPIO 并没有以任何方��置它，��过标识那个 GPIO 处于使用
	状�。必须有�外的代��处�引脚�置(如控制 GPIO 使用的引脚�上拉/下拉)。
	考虑到大多数情况下声明 GPIO 之�就会立��置它们,所以定义了以下三个辅助函数:
	
		/* 申请一个 GPIO 信�, �时通过特定的'flags'�始化�置,
		 * 其他和 gpio_request()的�数和返回值相�
		 *
		 */
		int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
	
		/* 在�个函数中申请多个 GPIO
		 */
		int gpio_request_array(struct gpio *array, size_t num);
	
		/* 在�个函数中释放多个 GPIO
		 */
		void gpio_free_array(struct gpio *array, size_t num);
	
	这里 'flags' 当�定义�指定以下属性:
	
		* GPIOF_DIR_IN		- �置方�为输入
		* GPIOF_DIR_OUT		- �置方�为输出
	
		* GPIOF_INIT_LOW	- 在作为输出时,�始值为低电平
		* GPIOF_INIT_HIGH	- 在作为输出时,�始值为高电平
		* GPIOF_OPEN_DRAIN	- gpio引脚为开�信�
		* GPIOF_OPEN_SOURCE	- gpio引脚为��开路信�
	
		* GPIOF_EXPORT_DIR_FIXED	- 将 gpio 导出到 sysfs，并��方�
		* GPIOF_EXPORT_DIR_CHANGEABLE	- �样是导出, 但�许改�方�
	
	因为 GPIOF_INIT_* 仅有在�置为输出的时候�存在,所以有效的组�为:
	
		* GPIOF_IN		- �置为输入
		* GPIOF_OUT_INIT_LOW	- �置为输出,并�始化为低电平
		* GPIOF_OUT_INIT_HIGH	- �置为输出,并�始化为高电平
	
	当设置 flag 为 GPIOF_OPEN_DRAIN 时，则�设引脚是开�信�。这样的引脚
	将�会在输出模�下置1。这样的引脚需�连接上拉电阻。通过使能这个标志，gpio库
	将会在被�求输出模�下置1时将引脚�为输入状��使引脚置高。引脚在输出模�下
	通过置0使其输出低电平。
	
	当设置 flag 为 GPIOF_OPEN_SOURCE 时，则�设引脚为��开路信�。这样的引脚
	将�会在输出模�下置0。这样的引脚需�连接下拉电阻。通过使能这个标志，gpio库
	将会在被�求输出模�下置0时将引脚�为输入状��使引脚置低。引脚在输出模�下
	通过置1使其输出高电平。
	
	将�这些标志�能扩展到支�更多的属性。
	
	更进一步,为了更简�地声明/释放多个 GPIO,'struct gpio'被引进��装所有
	这三个领域:
	
		struct gpio {
			unsigned	gpio;
			unsigned long	flags;
			const char	*label;
		};
	
	一个典型的用例:
	
		static struct gpio leds_gpios[] = {
			{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开� */
			{ 33, GPIOF_OUT_INIT_LOW,  "Green LED" }, /* 默认关闭 */
			{ 34, GPIOF_OUT_INIT_LOW,  "Red LED"   }, /* 默认关闭 */
			{ 35, GPIOF_OUT_INIT_LOW,  "Blue LED"  }, /* 默认关闭 */
			{ ... },
		};
	
		err = gpio_request_one(31, GPIOF_IN, "Reset Button");
		if (err)
			...
	
		err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
		if (err)
			...
	
		gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
	
	
	GPIO 映射到 IRQ
	--------------------
	GPIO 编�是无符�整数;IRQ 编�也是。这些构�了两个逻辑上��的命�空间
	(GPIO 0 �一定使用 IRQ 0)。你�以通过以下函数在它们之间实现映射:
	
		/* 映射 GPIO 编�到 IRQ 编� */
		int gpio_to_irq(unsigned gpio);
	
		/* 映射 IRQ 编�到 GPIO 编� (尽���使用) */
		int irq_to_gpio(unsigned irq);
	
	它们的返回值为对应命�空间的相关编�，或是负的错误代�(如果无法映射)。
	(例如,�些 GPIO 无法�为 IRQ 使用。)以下的编�错误是未�检测的:使用一个
	未通过 gpio_direction_input()�置为输入的 GPIO 编�，或者使用一个
	并���于gpio_to_irq()的 IRQ 编�。
	
	这两个映射函数�能会在信�编�的加�计算过程上花些时间。它们��休眠。
	
	gpio_to_irq()返回的�错误值�以传递给 request_irq()或者 free_irq()。
	它们通常通过�级特定的�始化代�存放到平�设备的 IRQ 资�中。注�:IRQ
	触�选项是 IRQ 接�的一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力
	也是如此。
	
	irq_to_gpio()返回的�错误值大多数通常�以被 gpio_get_value()所使用，
	比如在 IRQ 是沿触�时�始化或更新驱动状�。注��些平��支��映射,所以
	你应该尽���使用它。
	
	
	模拟开�信�
	----------------------------
	有时在�有低电平信�作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平
	结果为所有输出的逻辑与)的时候,共享的信�线需�使用“开��信�。(该术语
	适用于 CMOS 管；而 TTL 用“集电�开路�。)一个上拉电阻使信�为高电平。这
	有时被称为“线与�。实际上，从负逻辑(低电平为真)的角度�看，这是一个“线或�。
	
	一个开�信�的常�例�是共享的低电平使能 IRQ 信�线。此外,有时��数�总线
	信�也使用��开路信�。
	
	�些 GPIO 控制器直接支�开�输出，还有许多�支�。当你需�开�信�，但
	硬件��直接支�的时候，一个常用的方法是用任何��作输入也�作输出的 GPIO
	引脚�模拟:
	
	 LOW:	gpio_direction_output(gpio, 0) ... 这代�驱动信�并覆盖
		上拉�置。
	
	 HIGH:	gpio_direction_input(gpio) ... 这代�关闭输出,所以上拉电阻
		(或其他的一些器件)控制了信�。
	
	如果你将信�线“驱动�为高电平，但是 gpio_get_value(gpio)报告了一个
	低电平(在适当的上�时间�)，你就�以知�是其他的一些组件将共享信�线拉低了。
	这�一定是错误的。一个常�的例�就是 I2C 时钟的延长：一个需�较慢时钟的
	从设备延迟 SCK 的上�沿，而 I2C 主设备相应地调整其信�传输速率。
	
	
	这些公约忽略了什么?
	================
	这些公约忽略的最大一件事就是引脚�用，因为这属于高度芯片特定的属性且
	没有�移�性。�个平��能�需�明确的�用信�；有的对于任�给定的引脚
	�能�有两个功能选项；有的�能�个引脚有八个功能选项；有的�能�以将
	几个引脚中的任何一个作为给定的 GPIO。(是的，这些例�都�自于当��行
	Linux 的系统。)
	
	在�些系统中,与引脚�用相关的是�置和使能集�的上�下拉模�。并�是所有
	平�都支�这�模�,或者�会以相�的方��支�这�模�；且任何给定的电路�
	�能使用外置的上拉(或下拉)电阻,这时芯片上的就�应该使用。(当一个电路需�
	5kOhm 的拉动电阻,芯片上的 100 kOhm 电阻就�能�到。)�样的，驱动能力
	(2 mA vs 20 mA)和电压(1.8V vs 3.3V)是平�特定问题,就�模型一样在
	��置引脚和 GPIO 之间(没)有一一对应的关系。
	
	还有其他一些系统特定的机制没有在这里指出，例如上述的输入去毛刺和线与输出
	选项。硬件�能支�批�读或写 GPIO，但是那一般是�置相关的：对于处于�一
	�区(bank)的GPIO。(GPIO 通常以 16 或 32 个组�一个区�，一个给定的
	片上系统一般有几个这样的区�。)�些系统�以通过输出 GPIO 触� IRQ，
	或者从并�以 GPIO 管�的引脚�值。这些机制的相关代�没有必�具有�移�性。
	
	当�，动�定义 GPIO 并�是标准的，例如作为�置一个带有�些 GPIO 扩展器的
	附加电路�的副作用。
	
	GPIO 实现者的框架 (�选)
	=====================
	���到了，有一个�选的实现框架，让平�使用相�的编程接�，更加简�地支�
	���类的 GPIO 控制器。这个框架称为"gpiolib"。
	
	作为一个辅助调试功能，如果 debugfs �用，就会有一个 /sys/kernel/debug/gpio
	文件。通过这个框架，它�以列出所有注册的控制器,以�当�正在使用中的 GPIO
	的状�。
	
	
	控制器驱动: gpio_chip
	-------------------
	在框架中�个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包�了
	该类型的�个控制器的常用信�:
	
	 - 设置 GPIO 方�的方法
	 - 用于访问 GPIO 值的方法
	 - 告知调用其方法是��能休眠的标志
	 - �选的 debugfs 信�导出方法 (显示类似上拉�置一样的�外状�)
	 - 诊断标签
	
	也包�了�自 device.platform_data 的�个实例的数�：它第一个 GPIO 的
	编�和它�用的 GPIO 的数�。
	
	实现 gpio_chip 的代�应支�多控制器实例，这�能使用驱动模型。那些代��
	�置�个 gpio_chip，并�起gpiochip_add()。�载一个 GPIO 控制器很少�，
	但在必�的时候�以使用 gpiochip_remove()。
	
	大部分 gpio_chip 是一个实例特定结构体的一部分，而并�将 GPIO 接��独
	暴露出�,比如编��电�管�等。类似编解�器这样的芯片会有��的� GPIO
	状�。
	
	任何一个 debugfs 信�导出方法通常应该忽略还未申请作为 GPIO 的信�线。
	他们�以使用 gpiochip_is_requested()测试，当这个 GPIO 已�申请过了
	就返回相关的标签，�则返回 NULL。
	
	
	平�支�
	-------
	为了支�这个框架，一个平�的 Kconfig 文件将会 "select"(选择)
	ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的
	<asm/gpio.h> 包� <asm-generic/gpio.h>，�时定义三个方法:
	gpio_get_value()�gpio_set_value()和 gpio_cansleep()。
	
	它也应�供一个 ARCH_NR_GPIOS 的定义值，这样�以更好地�映该平� GPIO
	的实际数�,节���表的空间。(这个定义值应该包�片上系统内建 GPIO 和
	GPIO 扩展器中的数�。)
	
	ARCH_REQUIRE_GPIOLIB �味� gpiolib 核心在这个构架中将总是编译进内核。
	
	ARCH_WANT_OPTIONAL_GPIOLIB �味� gpiolib 核心默认关闭,且用户�以
	使能它,并将其编译进内核(�选)。
	
	如果这些选项都没被选择,该平�就�通过 GPIO-lib 支� GPIO,且代���以
	被用户使能。
	
	以下这些方法的实现�以直接使用框架代�,并总是通过 gpio_chip 调度:
	
	  #define gpio_get_value	__gpio_get_value
	  #define gpio_set_value	__gpio_set_value
	  #define gpio_cansleep		__gpio_cansleep
	
	这些定义�以用更�想的实现方法替代，那就是使用�过逻辑优化的内�函数�访问
	基于特定片上系统的 GPIO。例如,若引用的 GPIO (寄存器��移)是常�“12�，
	读�或设置它�能�需少则两或三个指令，且�会休眠。当这样的优化无法实现时，
	那些函数必须使用框架�供的代�，那就至少�几��指令��以实现。对于用 GPIO
	模拟的 I/O 接�, 如此精简指令是很有�义的。
	
	对于片上系统，平�特定代�为片上 GPIO �个区(bank)定义并注册 gpio_chip
	实例。那些 GPIO 应该根�芯片厂商的文档进行编�/标签,并直接和电路�原�图
	对应。他们应该开始于零并终止于平�特定的�制。这些 GPIO(代�)通常从
	arch_initcall()或者更早的地方集�进平��始化代�，使这些 GPIO 总是�用，
	且他们通常�以作为 IRQ 使用。
	
	�级支�
	-------
	对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器�专用芯片�多功能器件�FPGA
	或 CPLD)，大多数常用�级特定代�都�以注册控制器设备，并��他们的驱动知�
	gpiochip_add()所使用的 GPIO 编�。他们的起始编�通常跟在平�特定的 GPIO
	编�之�。
	
	例如�级�动代�应该创建结构体指明芯片公开的 GPIO 范围，并使用 platform_data
	将其传递给�个 GPIO 扩展器芯片。然�芯片驱动中的 probe()例程�以将这个
	数�传递给 gpiochip_add()。
	
	�始化顺�很��。例如，如果一个设备�赖基于 I2C 的(扩展)GPIO，那么它的
	probe()例程就应该在那个 GPIO 有效以���以被调用。这�味�设备应该在
	GPIO �以工作之���被注册。解决这类�赖的的一�方法是让这� gpio_chip
	控制器��级特定代��供 setup()和 teardown()回调函数。一旦所有必须的
	资��用之�，这些�级特定的回调函数将会注册设备，并�以在这些 GPIO 控制器
	设备��无效时移除它们。
	
	
	用户空间的 Sysfs 接�(�选)
	========================
	使用“gpiolib�实现框架的平��以选择�置一个 GPIO 的 sysfs 用户接�。
	这��于 debugfs 接�，因为它�供的是对 GPIO方�和值的控制，而��显示
	一个GPIO 的状�摘�。此外,它�以出现在没有调试支�的产�级系统中。
	
	例如，通过适当的系统硬件文档，用户空间�以知� GIOP #23 控制 Flash
	存储器的写�护(用于�护其中 Bootloader 分区)。产�的系统�级�能需�
	临时解除这个�护：首先导入一个 GPIO，改�其输出状�，然�在�新使能写�护
	��级代�。通常情况下,GPIO #23 是�会被触�的，并且内核也�需�知�他。
	
	根�适当的硬件文档，�些系统的用户空间 GPIO �以用于确定系统�置数�，
	这些数�是标准内核�知�的。在�些任务中，简�的用户空间 GPIO 驱动�能是
	系统真正需�的。
	
	注�：标准内核驱动中已�存在通用的“LED 和按键�GPIO 任务，分别是:
	"leds-gpio" 和 "gpio_keys"。请使用这些�替代直接访问 GPIO，因为集�在
	内核框架中的这类驱动比你在用户空间的代�更好。
	
	
	Sysfs 中的路径
	--------------
	在/sys/class/gpio 中有 3 类入�:
	
	   -	用于在用户空间控制 GPIO 的控制接�;
	
	   -	GPIOs 本身;以�
	
	   -	GPIO 控制器 ("gpio_chip" 实例)。
	
	除了这些标准的文件,还包�“device�符�链接。
	
	控制接�是�写的:
	
	    /sys/class/gpio/
	
	    	"export" ... 用户空间�以通过写其编�到这个文件，�求内核导出
			一个 GPIO 的控制到用户空间。
	
			例如: 如果内核代�没有申请 GPIO #19,"echo 19 > export"
			将会为 GPIO #19 创建一个 "gpio19" 节点。
	
	    	"unexport" ... 导出到用户空间的逆�作。
	
			例如: "echo 19 > unexport" 将会移除使用"export"文件导出的
			"gpio19" 节点。
	
	GPIO 信�的路径类似 /sys/class/gpio/gpio42/ (对于 GPIO #42 �说)，
	并有如下的读/写属性:
	
	    /sys/class/gpio/gpioN/
	
		"direction" ... 读�得到 "in" 或 "out"。这个值通常�行写入。
			写入"out" 时,其引脚的默认输出为低电平。为了确�无故障�行，
			"low" 或 "high" 的电平值应该写入 GPIO 的�置，作为�始输出值。
	
			注�:如果内核�支�改� GPIO 的方�，或者在导出时内核代�没有
			明确�许用户空间�以�新�置 GPIO 方�，那么这个属性将�存在。
	
		"value" ... 读�得到 0 (低电平) 或 1 (高电平)。如果 GPIO �置为
			输出,这个值�许写�作。任何�零值都以高电平看待。
	
			如果引脚�以�置为中断信�，且如果已��置了产生中断的模�
			（�"edge"的�述），你�以对这个文件使用轮询�作(poll(2))，
			且轮询�作会在任何中断触�时返回。如果你使用轮询�作(poll(2))，
			请在 events 中设置 POLLPRI 和 POLLERR。如果你使用轮询�作
			(select(2))，请在 exceptfds 设置你期望的文件�述符。在
			轮询�作(poll(2))返回之�，既�以通过 lseek(2)�作读�
			sysfs 文件的开始部分，也�以关闭这个文件并�新打开它�读�数�。
	
		"edge" ... 读�得到“none��“rising��“falling�或者“both�。
			将这些字符串写入这个文件�以选择沿触�模�，会使得轮询�作
			(select(2))在"value"文件中返回。
	
			这个文件仅有在这个引脚�以�置为�产生中断输入引脚时，�存在。
	
		"active_low" ... 读�得到 0 (�) 或 1 (真)。写入任何�零值�以
			翻转这个属性的(读写)值。已存在或之�通过"edge"属性设置了"rising"
			和 "falling" 沿触�模�的轮询�作(poll(2))将会�循这个设置。
	
	GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO
	开始实现控制的控制器),并有�以下�读属性:
	
	    /sys/class/gpio/gpiochipN/
	
	    	"base" ... 与以上的 N 相�,代表此芯片管�的第一个 GPIO 的编�
	
	    	"label" ... 用于诊断 (并�总是�有唯一值)
	
	    	"ngpio" ... 此控制器所管�的 GPIO 数�(而 GPIO 编�从 N 到
	    		N + ngpio - 1)
	
	大多数情况下,电路�的文档应当标明�个 GPIO 的使用目的。但是那些编�并�总是
	固定的,例如在扩展�上的 GPIO会根�所使用的主�或所在堆�架构中其他的��而
	有所��。在这�情况下,你�能需�使用 gpiochip 节点(尽�能地结�电路图)�
	确定给定信�所用的 GPIO 编�。
	
	
	从内核代�中导出
	-------------
	内核代��以明确地管�那些已通过 gpio_request()申请的 GPIO 的导出:
	
		/* 导出 GPIO 到用户空间 */
		int gpio_export(unsigned gpio, bool direction_may_change);
	
		/* gpio_export()的逆�作 */
		void gpio_unexport();
	
		/* 创建一个 sysfs 连接到已导出的 GPIO 节点 */
		int gpio_export_link(struct device *dev, const char *name,
			unsigned gpio)
	
		/* 改� sysfs 中的一个 GPIO 节点的�性 */
		int gpio_sysfs_set_active_low(unsigned gpio, int value);
	
	在一个内核驱动申请一个 GPIO 之�，它�以通过 gpio_export()使其在 sysfs
	接�中��。该驱动�以控制信�方�是��修改。这有助于防止用户空间代�无�间
	破���的系统状�。
	
	这个明确的导出有助于(通过使�些实验更容易�)调试，也�以�供一个始终存在的接�，
	与文档��作为�级支�包的一部分。
	
	在 GPIO 被导出之�，gpio_export_link()�许在 sysfs 文件系统的任何地方
	创建一个到这个 GPIO sysfs 节点的符�链接。这样驱动就�以通过一个�述性的
	�字，在 sysfs 中他们所拥有的设备下�供一个(到这个 GPIO sysfs 节点的)接�。
	
	驱动�以使用 gpio_sysfs_set_active_low() �在用户空间��电路�之间
	GPIO 线的�性差异。这个仅对 sysfs 接�起作用。�性的改��以在 gpio_export()
	��进行,且之�使能的轮询�作(poll(2))支�(上�或下�沿)将会被�新�置��循
	这个设置。

• [ zh_CN ]
• [ arm ]
• [ arm64 ]
• basic_profiling.txt
• CodingStyle
• email-clients.txt
• [ filesystems ]
• gpio.txt
• HOWTO
• IRQ.txt
• magic-number.txt
• oops-tracing.txt
• SecurityBugs
• sparse.txt
• stable_api_nonsense.txt
• stable_kernel_rules.txt
• SubmittingDrivers
• SubmittingPatches
• [ video4linux ]
• volatile-considered-harmful.txt
•