linux驱动常用函数

设备树常用 OF 操作函数
- 查找节点的 OF 函数
- - 1、of_find_node_by_name
  - 2、of_find_node_by_type
  - 3、of_find_compatible_node
  - 4、of_find_matching_node_and_match
  - 5、of_find_node_by_path
- 查找父/子节点的 OF 函数
- - 1、of_get_parent
  - 2、of_get_next_child
- 提取属性值的 OF 函数
- - 1、of_find_property
  - 2、of_property_count_elems_of_size
  - 4、of_property_read_u8_array
  - 5、of_property_read_u8
  - 6、of_property_read_string
  - 7、of_n_addr_cells
  - 8、of_n_size_cells
- 其他常用的 OF 函数
- - 1、of_device_is_compatible
  - 2、of_get_address
  - 3、of_translate_address
  - 4、of_address_to_resource
  - 5、of_iomap
gpio 子系统 API 函数
- 1、 gpio_request 函数
- 2、 gpio_free 函数
- 3、 gpio_direction_input 函数
- 4、 gpio_direction_output 函数
- 5、 gpio_get_value 函数
- 6、 gpio_set_value 函数
与 gpio 相关的 OF 函数
- 1、 of_gpio_named_count 函数
- 2、 of_gpio_count 函数
- 3、 of_get_named_gpio 函数

设备树常用 OF 操作函数

设备树描述了设备的详细信息，这些信息包括数字类型的、字符串类型的、数组类型的，我们在编写驱动的时候需要获取到这些信息。比如设备树使用 reg 属性描述了某个外设的寄存器地址为 0X02005482 ，长度为 0X400 ，我们在编写驱动的时候需要获取到 reg 属性的0X02005482 和 0X400 这两个值，然后初始化外设。Linux 内核给我们提供了一系列的函数来获取设备树中的节点或者属性信息，这一系列的函数都有一个统一的前缀“of_”，所以在很多资料里面也被叫做 OF 函数。这些 OF 函数原型都定义在 include/linux/of.h 文件中。

查找节点的 OF 函数

设备都是以节点的形式“挂”到设备树上的，因此要想获取这个设备的其他属性信息，必须先获取到这个设备的节点。Linux 内核使用 device_node 结构体来描述一个节点，此结构体定义在文件 include/linux/of.h 中，定义如下：

49 struct device_node {50     const char *name; /* 节点名字 */
51     const char *type; /* 设备类型 */
52     phandle phandle;
53     const char *full_name; /* 节点全名 */
54     struct fwnode_handle fwnode;
55
56     struct property *properties; /* 属性 */
57     struct property *deadprops; /* removed 属性 */
58     struct device_node *parent; /* 父节点 */
59     struct device_node *child; /* 子节点 */
60     struct device_node *sibling;
61    struct kobject kobj;
62     unsigned long _flags;
63     void *data;
64 #if defined(CONFIG_SPARC)
65     const char *path_component_name;
66     unsigned int unique_id;
67     struct of_irq_controller *irq_trans;
68 #endif
69 };

与查找节点有关的 OF 函数有 5 个，我们依次来看一下。

1、of_find_node_by_name

of_find_node_by_name 函数通过节点名字查找指定的节点，函数原型如下：

struct device_node *of_find_node_by_name(struct device_node *from,const char *name);

函数参数和返回值含义如下：
from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。
name：要查找的节点名字。
返回值：找到的节点，如果为 NULL 表示查找失败。

2、of_find_node_by_type

of_find_node_by_type 函数通过 device_type 属性查找指定的节点，函数原型如下：

struct device_node *of_find_node_by_type(struct device_node *from, const char *type)

函数参数和返回值含义如下：
from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。
type：要查找的节点对应的 type 字符串，也就是 device_type 属性值。
返回值：找到的节点，如果为 NULL 表示查找失败。

3、of_find_compatible_node

of_find_compatible_node 函数根据 device_type 和 compatible 这两个属性查找指定的节点，函数原型如下：

struct device_node *of_find_compatible_node(struct device_node *from,const char *type,const char *compatible)

函数参数和返回值含义如下：
from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。
type：要查找的节点对应的 type 字符串，也就是 device_type 属性值，可以为 NULL，表示忽略掉 device_type 属性。
compatible：要查找的节点所对应的 compatible 属性列表。
返回值：找到的节点，如果为 NULL 表示查找失败

4、of_find_matching_node_and_match

of_find_matching_node_and_match 函数通过 of_device_id 匹配表来查找指定的节点，函数原型如下：

struct device_node *of_find_matching_node_and_match(struct device_node *from,
const struct of_device_id *matches,
const struct of_device_id **match)

函数参数和返回值含义如下：
from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。
matches：of_device_id 匹配表，也就是在此匹配表里面查找节点。
match 找到的匹配的 of_device_id。
返回值：找到的节点，如果为 NULL 表示查找失败

5、of_find_node_by_path

of_find_node_by_path 函数通过路径来查找指定的节点，函数原型如下：

     inline struct device_node *of_find_node_by_path(const char *path)

函数参数和返回值含义如下：
path：带有全路径的节点名，可以使用节点的别名，比如“/backlight”就是 backlight 这个节点的全路径。
返回值：找到的节点，如果为 NULL 表示查找失败

查找父/子节点的 OF 函数

Linux 内核提供了几个查找节点对应的父节点或子节点的 OF 函数，我们依次来看一下。

1、of_get_parent

of_get_parent 函数用于获取指定节点的父节点(如果有父节点的话)，函数原型如下：

struct device_node *of_get_parent(const struct device_node *node)

函数参数和返回值含义如下：
node：要查找的父节点的节点。
返回值：找到的父节点。

2、of_get_next_child

of_get_next_child 函数用迭代的方式查找子节点，函数原型如下：

struct device_node *of_get_next_child(const struct device_node *node,
struct device_node *prev)

函数参数和返回值含义如下：
node：父节点。
prev：前一个子节点，也就是从哪一个子节点开始迭代的查找下一个子节点。可以设置为NULL，表示从第一个子节点开始。
返回值：找到的下一个子节点。

提取属性值的 OF 函数

节点的属性信息里面保存了驱动所需要的内容，因此对于属性值的提取非常重要，Linux 内核中使用结构体 property 表示属性，此结构体同样定义在文件include/linux/of.h 中，内容如下：

35 struct property {36     char *name; /* 属性名字 */
37     int length; /* 属性长度 */
38     void *value; /* 属性值 */
39     struct property *next; /* 下一个属性 */
40     unsigned long _flags;
41     unsigned int unique_id;
42     struct bin_attribute attr;
43 };

Linux 内核也提供了提取属性值的 OF 函数，我们依次来看一下。

1、of_find_property

of_find_property 函数用于查找指定的属性，函数原型如下：

property *of_find_property(const struct device_node *np,
const char *name,
int *lenp)

函数参数和返回值含义如下：
np：设备节点。
name：属性名字。
lenp：属性值的字节数
返回值：找到的属性。

2、of_property_count_elems_of_size

of_property_count_elems_of_size 函数用于获取属性中元素的数量，比如 reg 属性值是一个数组，那么使用此函数可以获取到这个数组的大小，此函数原型如下：

int of_property_count_elems_of_size(const struct device_node *np,
const char *propname,
int elem_size)

函数参数和返回值含义如下：
np：设备节点。
proname：需要统计元素数量的属性名字。
elem_size：元素长度。
返回值：得到的属性元素数量。

3、of_property_read_u32_index
of_property_read_u32_index 函数用于从属性中获取指定标号的 u32 类型数据值(无符号 32 位)，比如某个属性有多个 u32 类型的值，那么就可以使用此函数来获取指定标号的数据值，此函数原型如下：

int of_property_read_u32_index(const struct device_node *np,
const char *propname,
u32 index,
u32 *out_value)

函数参数和返回值含义如下：
np：设备节点。
proname：要读取的属性名字。
index：要读取的值标号。
out_value：读取到的值
返回值：0 读取成功，负值，读取失败，-EINVAL 表示属性不存在，-ENODATA 表示没有要读取的数据，-EOVERFLOW 表示属性值列表太小。

4、of_property_read_u8_array

of_property_read_u16_array
of_property_read_u32_array
of_property_read_u64_array
这 4 个函数分别是读取属性中 u8、u16、u32 和 u64 类型的数组数据，比如大多数的 reg 属性都是数组数据，可以使用这 4 个函数一次读取出 reg 属性中的所有数据。这四个函数的原型如下：

int of_property_read_u8_array(const struct device_node *np,
const char *propname,
u8 *out_values,
size_t sz)

函数参数和返回值含义如下：
np：设备节点。
proname：要读取的属性名字。
out_value：读取到的数组值，分别为 u8、u16、u32 和 u64。
sz 要读取的数组元素数量。
返回值：0，读取成功，负值，读取失败，-EINVAL 表示属性不存在，-ENODATA 表示没有要读取的数据，-EOVERFLOW 表示属性值列表太小。

5、of_property_read_u8

of_property_read_u16
of_property_read_u32
of_property_read_u64
有些属性只有一个整形值，这四个函数就是用于读取这种只有一个整形值的属性，分别用于读取 u8、u16、u32 和 u64 类型属性值，函数原型如下：

 int of_property_read_u8(const struct device_node *np,
const char *propname,
u8 *out_value)

函数参数和返回值含义如下：
np：设备节点。
proname：要读取的属性名字。
out_value：读取到的数组值。
返回值：0，读取成功，负值，读取失败，-EINVAL 表示属性不存在，-ENODATA 表示没有要读取的数据，-EOVERFLOW 表示属性值列表太小。

6、of_property_read_string

of_property_read_string 函数用于读取属性中字符串值，函数原型如下：

int of_property_read_string(struct device_node   *np,
const char  *propname,
const char  **out_string)

函数参数和返回值含义如下：
np：设备节点。
proname：要读取的属性名字。
out_string：读取到的字符串值。
返回值：0，读取成功，负值，读取失败。

7、of_n_addr_cells

of_n_addr_cells 函数用于获取#address-cells 属性值，函数原型如下：

int of_n_addr_cells(struct device_node *np)

函数参数和返回值含义如下：
np：设备节点。
返回值：获取到的#address-cells 属性值。

8、of_n_size_cells

of_size_cells 函数用于获取#size-cells 属性值，函数原型如下：

int of_n_size_cells(struct device_node *np)

函数参数和返回值含义如下：
np：设备节点。
返回值：获取到的#size-cells 属性值。

其他常用的 OF 函数

1、of_device_is_compatible

of_device_is_compatible 函数用于查看节点的 compatible 属性是否有包含 compat 指定的字符串，也就是检查设备节点的兼容性，函数原型如下：

int of_device_is_compatible(const struct device_node *device,
const char *compat)

函数参数和返回值含义如下：
device：设备节点。
compat：要查看的字符串。
返回值：0，节点的 compatible 属性中不包含 compat 指定的字符串；正数，节点的 compatible属性中包含 compat 指定的字符串。

2、of_get_address

of_get_address 函数用于获取地址相关属性，主要是“reg”或者“assigned-addresses”属性值，函数原型如下：

const __be32 *of_get_address(struct device_node *dev,
int index,
u64 *size,
unsigned int *flags)

函数参数和返回值含义如下：
dev：设备节点。
index：要读取的地址标号。
size：地址长度。
flags：参数，比如 IORESOURCE_IO、IORESOURCE_MEM 等
返回值：读取到的地址数据首地址，为 NULL 的话表示读取失败。

3、of_translate_address

of_translate_address 函数负责将从设备树读取到的地址转换为物理地址，函数原型如下：

u64 of_translate_address(struct device_node *dev,
const __be32 *in_addr)

函数参数和返回值含义如下：
dev：设备节点。
in_addr：要转换的地址。
返回值：得到的物理地址，如果为 OF_BAD_ADDR 的话表示转换失败。

4、of_address_to_resource

IIC、SPI、GPIO 等这些外设都有对应的寄存器，这些寄存器其实就是一组内存空间，Linux 内核使用 resource 结构体来描述一段内存空间，“resource”翻译出来就是“资源”，因此用 resource 结构体描述的都是设备资源信息，resource 结构体定义在文件 include/linux/ioport.h 中，定义如下：

18 struct resource {19     resource_size_t start;
20     resource_size_t end;
21     const char *name;
22     unsigned long flags;
23     struct resource *parent, *sibling, *child;
24 };

对于 32 位的 SOC 来说，resource_size_t 是 u32 类型的。其中 start 表示开始地址，end 表示结束地址，name 是这个资源的名字，flags 是资源标志位，一般表示资源类型，可选的资源标志定义在文件 include/linux/ioport.h 中，如下所示：

1 #define IORESOURCE_BITS 0x000000ff
2 #define IORESOURCE_TYPE_BITS 0x00001f00
3 #define IORESOURCE_IO 0x00000100
4 #define IORESOURCE_MEM 0x00000200
5 #define IORESOURCE_REG 0x00000300
6 #define IORESOURCE_IRQ 0x00000400
7 #define IORESOURCE_DMA 0x00000800
8 #define IORESOURCE_BUS 0x00001000
9 #define IORESOURCE_PREFETCH 0x00002000
10 #define IORESOURCE_READONLY 0x00004000
11 #define IORESOURCE_CACHEABLE 0x00008000
12 #define IORESOURCE_RANGELENGTH 0x00010000
13 #define IORESOURCE_SHADOWABLE 0x00020000
14 #define IORESOURCE_SIZEALIGN 0x00040000
15 #define IORESOURCE_STARTALIGN 0x00080000
16 #define IORESOURCE_MEM_64 0x00100000
17 #define IORESOURCE_WINDOW 0x00200000
18 #define IORESOURCE_MUXED 0x00400000
19 #define IORESOURCE_EXCLUSIVE 0x08000000
20 #define IORESOURCE_DISABLED 0x10000000
21 #define IORESOURCE_UNSET 0x20000000
22 #define IORESOURCE_AUTO 0x40000000
23 #define IORESOURCE_BUSY 0x80000000

大家一般最常见的资源标志就是IORESOURCE_MEM 、 IORESOURCE_REG 和
IORESOURCE_IRQ 等。接下来我们回到 of_address_to_resource 函数，此函数看名字像是从设备树里面提取资源值，但是本质上就是将 reg 属性值，然后将其转换为 resource 结构体类型，函数原型如下所示

int of_address_to_resource(struct device_node *dev,
int index,
struct resource *r)

函数参数和返回值含义如下：
dev：设备节点。
index：地址资源标号。
r：得到的 resource 类型的资源值。
返回值：0，成功；负值，失败。

5、of_iomap

of_iomap 函数用于直接内存映射，以前我们会通过 ioremap 函数来完成物理地址到虚拟地址的映射，采用设备树以后就可以直接通过 of_iomap 函数来获取内存地址所对应的虚拟地址，不需要使用 ioremap 函数了。当然了，你也可以使用 ioremap 函数来完成物理地址到虚拟地址的内存映射，只是在采用设备树以后，大部分的驱动都使用 of_iomap 函数了。of_iomap 函数本质上也是将 reg 属性中地址信息转换为虚拟地址，如果 reg 属性有多段的话，可以通过 index 参数指定要完成内存映射的是哪一段，of_iomap 函数原型如下：

void __iomem *of_iomap(struct device_node *np,
int index)

函数参数和返回值含义如下：
np：设备节点。
index：reg 属性中要完成内存映射的段，如果 reg 属性只有一段的话 index 就设置为 0。
返回值：经过内存映射后的虚拟内存首地址，如果为 NULL 的话表示内存映射失败。

gpio 子系统 API 函数

对于驱动开发人员，设置好设备树以后就可以使用 gpio 子系统提供的 API 函数来操作指定的 GPIO， gpio 子系统向驱动开发人员屏蔽了具体的读写寄存器过程。这就是驱动分层与分离的好处，大家各司其职，做好自己的本职工作即可。 gpio 子系统提供的常用的 API 函数有下面几个：

1、 gpio_request 函数

gpio_request 函数用于申请一个 GPIO 管脚，在使用一个 GPIO 之前一定要使用 gpio_request进行申请，函数原型如下：

int gpio_request(unsigned gpio, const char *label)

函数参数和返回值含义如下：
gpio：要申请的 gpio 标号，使用 of_get_named_gpio 函数从设备树获取指定 GPIO 属性信息，此函数会返回这个 GPIO 的标号。
label：给 gpio 设置个名字。
返回值： 0，申请成功；其他值，申请失败。

2、 gpio_free 函数

如果不使用某个 GPIO 了，那么就可以调用 gpio_free 函数进行释放。函数原型如下：

void gpio_free(unsigned gpio)

函数参数和返回值含义如下：
gpio：要释放的 gpio 标号。
返回值：无。

3、 gpio_direction_input 函数

此函数用于设置某个 GPIO 为输入，函数原型如下所示：

int gpio_direction_input(unsigned gpio)

函数参数和返回值含义如下：
gpio：要设置为输入的 GPIO 标号。
返回值： 0，设置成功；负值，设置失败。

4、 gpio_direction_output 函数

此函数用于设置某个 GPIO 为输出，并且设置默认输出值，函数原型如下：

int gpio_direction_output(unsigned gpio, int value)

函数参数和返回值含义如下：
gpio：要设置为输出的 GPIO 标号。
value： GPIO 默认输出值。
返回值： 0，设置成功；负值，设置失败。

5、 gpio_get_value 函数

此函数用于获取某个 GPIO 的值(0 或 1)，此函数是个宏，定义所示：

#define gpio_get_value __gpio_get_value
int __gpio_get_value(unsigned gpio)

函数参数和返回值含义如下：
gpio：要获取的 GPIO 标号。
返回值：非负值，得到的 GPIO 值；负值，获取失败。

6、 gpio_set_value 函数

此函数用于设置某个 GPIO 的值，此函数是个宏，定义如下

#define gpio_set_value __gpio_set_value
void __gpio_set_value(unsigned gpio, int value)

函数参数和返回值含义如下：
gpio：要设置的 GPIO 标号。
value：要设置的值。
返回值：无
关于 gpio 子系统常用的 API 函数就讲这些，这些是我们用的最多的。

与 gpio 相关的 OF 函数

在示例代码 45.2.4.3 中，我们定义了一个名为“gpio”的属性， gpio 属性描述了 test 这个设备所使用的 GPIO。在驱动程序中需要读取 gpio 属性内容， Linux 内核提供了几个与 GPIO 有关的 OF 函数，常用的几个 OF 函数如下所示：

1、 of_gpio_named_count 函数

of_gpio_named_count 函数用于获取设备树某个属性里面定义了几个 GPIO 信息，要注意的是空的 GPIO 信息也会被统计到，比如：

gpios = <0&gpio1 1 20 &gpio2 3 4>;

上述代码的“gpios”节点一共定义了 4 个 GPIO，但是有 2 个是空的，没有实际的含义。
通过 of_gpio_named_count 函数统计出来的 GPIO 数量就是 4 个，此函数原型如下：

int of_gpio_named_count(struct device_node *np, const char *propname)

函数参数和返回值含义如下：
np：设备节点。
propname：要统计的 GPIO 属性。
返回值：正值，统计到的 GPIO 数量；负值，失败。

2、 of_gpio_count 函数

和 of_gpio_named_count 函数一样，但是不同的地方在于，此函数统计的是“gpios”这个属性的 GPIO 数量，而of_gpio_named_count 函数可以统计任意属性的 GPIO 信息，函数原型如下所示：

int of_gpio_count(struct device_node *np)

函数参数和返回值含义如下：
np：设备节点。
返回值：正值，统计到的 GPIO 数量；负值，失败。

3、 of_get_named_gpio 函数

此函数获取 GPIO 编号，因为 Linux 内核中关于 GPIO 的 API 函数都要使用 GPIO 编号，此函数会将设备树中类似<&gpio5 7 GPIO_ACTIVE_LOW>的属性信息转换为对应的 GPIO 编号，此函数在驱动中使用很频繁！函数原型如下：

int of_get_named_gpio(struct device_node *np,
const char *propname,
int index)

函数参数和返回值含义如下：
np：设备节点。
propname：包含要获取 GPIO 信息的属性名。
index： GPIO 索引，因为一个属性里面可能包含多个 GPIO，此参数指定要获取哪个 GPIO的编号，如果只有一个 GPIO 信息的话此参数为 0。
返回值：正值，获取到的 GPIO 编号；负值，失败。