Linux 驱动开发 五十五：《gpio.txt》翻译

NXP提供Linux源码，具体文档目录：\linux-imx-4.1.15\Documentation\devicetree\bindings\gpio\gpio.txt。

《gpio.txt》为设备指定 GPIO 信息。

一、gpios 属性

使用 GPIO 的 gpios 属性节点应该使用一个或多个属性来指定它们，每个属性都包含一个“gpio-list”：

gpio-list ::= <single-gpio> [gpio-list]
single-gpio ::= <gpio-phandle> <gpio-specifier>
gpio-phandle : phandle to gpio controller node（phandle 到 gpio 控制器节点）
gpio-specifier : Array of #gpio-cells specifying specific gpio（指定特定 gpio 的 #gpio-cells 数组）
		 (controller specific)

GPIO 属性应命名为“[< name >-]gpios”，< name > 是此 GPIO 用于设备的用途。 虽然出于兼容性原因（解析为“gpios”属性）认为不存在的 < name > 是有效的，但它不允许用于新绑定。

GPIO 属性可以包含一个或多个 GPIO 指针，但只有在特殊情况下，它们才应该包含多个。 如果您的设备使用多个具有不同功能的 GPIO，请在各自的属性下引用每个 GPIO，并为其指定一个有意义的名称。 接受 GPIO 阵列的唯一情况是多个 GPIO 提供相同功能（例如并行数据线）。

每个 gpios 属性的确切用途必须记录在设备的设备树绑定中。

以下示例可用于描述用作设备启用和 bit-banged 数据信号的 GPIO 引脚：

gpio1: gpio1 {
	gpio-controller
	 #gpio-cells = <2>;
};
gpio2: gpio2 {
	gpio-controller
	 #gpio-cells = <1>;
};
[...]

enable-gpios = <&gpio2 2>;
data-gpios = <&gpio1 12 0>,
	     <&gpio1 13 0>,
	     <&gpio1 14 0>,
	     <&gpio1 15 0>;

请注意，gpio 说明符长度取决于控制器。 在上面的例子中，&gpio1 使用 2 个单元格来指定一个 gpio，而 &gpio2 只使用一个。

gpio-specifier 可以编码：bank、bank 内部的 pin 位置、pin 是否为开漏以及 pin 是否逻辑反转。 每个说明符单元格的确切含义是特定于控制器的，并且必须记录在设备的设备树绑定中。 尽可能使用 include/dt-bindings/gpio/gpio.h 中定义的宏：

使用 GPIO 的节点示例：

node {
	enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
};

GPIO_ACTIVE_HIGH 为 0，因此在此示例中，gpio-specifier 为“18 0”并编码 GPIO 引脚号，以及“qe_pio_e”gpio 控制器接受的 GPIO 标志。

1、GPIO 说明符最佳实践

一个 gpio-specifier 应该包含一个指示 GPIO 极性的标志； 高电平有效或低电平有效。 如果是这样，则应遵循以下最佳实践：

gpio-specifier 的极性标志应该代表 GPIO 控制器的物理级别，它在设备上实现（或表示，对于输入）逻辑断言值。 逻辑断言的确切定义应由设备的绑定定义。 如果电路板反转 GPIO 控制器和设备之间的信号，则 gpio-specifier 将表示与设备引脚上的信号相反的物理电平。

当设备的信号极性可配置时，设备的绑定必须：

1、为信号定义一个静态极性，期望任何使用该绑定的软件都会静态地对设备进行编程以使用该信号极性。

极性的静态选择可以是：

• （首选）由特定于绑定的 DT 属性决定。

或

• 由 DT 绑定本身静态定义。

特别是，不能从 gpio-specifier 导出极性，因为这会阻止 DT 分别表示器件中可配置信号极性的两个正交概念，以及可能的板级信号反转。

2、为设备信号极性选择一个选项，并在绑定中记录此选择。 gpio-specifier 应该代表信号的极性（在 GPIO 控制器上），假设设备配置为这个特定的信号极性选择。 如果软件选择对设备进行编程以生成或接收相反极性的信号，则软件将负责在 GPIO 控制器上正确解释（反转）GPIO 信号。

二、gpio 控制器节点

每个 GPIO 控制器节点都必须包含一个空的“gpio-controller”属性和一个 #gpio-cells 整数属性，该属性指示 gpio-specifier 中的单元数。

GPIO 芯片可能包含 GPIO hog 定义。 GPIO hogging 是一种提供自动 GPIO 请求和配置的机制，作为 gpio 控制器的驱动程序探测功能的一部分。

每个 GPIO hog 定义都表示为 GPIO 控制器的子节点。必需的属性：

gpio-hog：指定此子节点表示 GPIO hog 的属性。

gpios：存储 GPIO 信息（id、标志、…）。 应包含在其父节点（GPIO 控制器节点）中指定的单元数。

仅按如下所示顺序扫描以下属性之一。 这意味着当存在多个属性时，它们将按照下面显示的顺序进行搜索，并将第一个匹配项作为预期配置。

input：指定将 GPIO 方向设置为输入的属性。

output-low：一个属性，指定将 GPIO 方向设置为值为低的输出。

output-high：一个属性，指定将 GPIO 方向设置为值高的输出。

可选属性：

line-name：GPIO 标签名称。 如果不存在，则使用节点名称。

定义为 gpio-controller 节点的两个 SOC GPIO bank 的示例：

qe_pio_a: gpio-controller@1400 {
	compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
	reg = <0x1400 0x18>;
	gpio-controller;
	#gpio-cells = <2>;

	line_b {
		gpio-hog;
		gpios = <6 0>;
		output-low;
		line-name = "foo-bar-gpio";
	};
};

qe_pio_e: gpio-controller@1460 {
	compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
	reg = <0x1460 0x18>;
	gpio-controller;
	#gpio-cells = <2>;
};

1、gpio-和pin-controller交互

GPIO 控制器提供的部分或全部 GPIO 可以通过引脚控制器路由到封装上的引脚。 这允许在 GPIO 和其他功能之间复用这些引脚。

表示哪些 GPIO 对应于哪些引脚控制器上的哪些引脚很有用。 下面描述的 gpio-ranges 属性代表了这一点，并包含如下信息结构：

gpio-range-list ::= <single-gpio-range> [gpio-range-list]
single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range>
numeric-gpio-range ::=
		<pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
pinctrl-phandle : phandle to pin controller node
gpio-base : Base GPIO ID in the GPIO controller
pinctrl-base : Base pinctrl pin ID in the pin controller
count : The number of GPIOs/pins in this range

上面提到的“pin 控制器节点”必须符合 …/pinctrl/pinctrl-bindings.txt 中描述的绑定。

如果使用命名的 gpio 范围（< pinctrl-base > 和 < count > 都设置为 0 的范围），属性 gpio-ranges-group-names 包含一个字符串，用于 gpio-ranges 中的每个单个 gpio-range：

gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
gpiorange-name : Name of the pingroup associated to the GPIO range in
		the respective pin controller.

对应于数值范围的 gpiorange-names-list 元素包含空字符串。 与命名范围相对应的 gpiorange-names-list 元素包含在相应引脚控制器中定义的引脚组的名称。 范围内的引脚/GPIO 数是该引脚组中的引脚数。

此绑定的先前版本要求任何 gpio-ranges 属性引用的所有 pin 控制器节点都包含名为 #gpio-range-cells 且值为 <3> 的属性。 此要求现已弃用。 但是，出于兼容性原因，该属性可能仍存在于旧设备树中，即使在需要与旧软件兼容的新设备树中也仍然需要。

例子1：

qe_pio_e: gpio-controller@1460 {
	#gpio-cells = <2>;
	compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
	reg = <0x1460 0x18>;
	gpio-controller;
	gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
};

在这里，单个 GPIO 控制器的 GPIO 0…9 路由到引脚控制器 pinctrl1 的引脚 20…29，GPIO 10…19 路由到引脚控制器 pinctrl2 的引脚 50…59。

例子2：

gpio_pio_i: gpio-controller@14B0 {
	#gpio-cells = <2>;
	compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
	reg = <0x1480 0x18>;
	gpio-controller;
	gpio-ranges =	<&pinctrl1 0 20 10>,
					<&pinctrl2 10 0 0>,
					<&pinctrl1 15 0 10>,
					<&pinctrl2 25 0 0>;
	gpio-ranges-group-names =	"",
					"foo",
					"",
					"bar";
};

在这里，定义了三个 GPIO 范围。 两个引脚控制器。 pinctrl1 GPIO 范围是使用引脚号定义的，而 GPIO 范围是 wrt。 pinctrl2 被命名为“foo”和“bar”。