diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-extcon | 22 | ||||
| -rw-r--r-- | Documentation/filesystems/debugfs.txt | 4 | ||||
| -rw-r--r-- | Documentation/kobject.txt | 6 | ||||
| -rw-r--r-- | Documentation/zh_CN/arm/Booting | 175 | ||||
| -rw-r--r-- | Documentation/zh_CN/basic_profiling.txt | 71 | ||||
| -rw-r--r-- | Documentation/zh_CN/filesystems/sysfs.txt | 372 | ||||
| -rw-r--r-- | Documentation/zh_CN/gpio.txt | 658 | ||||
| -rw-r--r-- | Documentation/zh_CN/video4linux/omap3isp.txt | 277 | ||||
| -rw-r--r-- | Documentation/zh_CN/video4linux/v4l2-framework.txt | 983 |
9 files changed, 2553 insertions, 15 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon index 20ab361bd8c..57a72623291 100644 --- a/Documentation/ABI/testing/sysfs-class-extcon +++ b/Documentation/ABI/testing/sysfs-class-extcon @@ -13,7 +13,7 @@ Description: accessory cables have such capability. For example, the 30-pin port of Nuri board (/arch/arm/mach-exynos) may have both HDMI and Charger attached, or analog audio, - video, and USB cables attached simulteneously. + video, and USB cables attached simultaneously. If there are cables mutually exclusive with each other, such binary relations may be expressed with extcon_dev's @@ -35,7 +35,7 @@ Description: The /sys/class/extcon/.../state shows and stores the cable attach/detach information of the corresponding extcon object. If the extcon object has an optional callback "show_state" - defined, the showing function is overriden with the optional + defined, the showing function is overridden with the optional callback. If the default callback for showing function is used, the @@ -46,19 +46,19 @@ Description: TA=1 EAR_JACK=0 # - In this example, the extcon device have USB_OTG and TA + In this example, the extcon device has USB_OTG and TA cables attached and HDMI and EAR_JACK cables detached. In order to update the state of an extcon device, enter a hex - state number starting with 0x. - echo 0xHEX > state + state number starting with 0x: + # echo 0xHEX > state - This updates the whole state of the extcon dev. + This updates the whole state of the extcon device. Inputs of all the methods are required to meet the - mutually_exclusive contidions if they exist. + mutually_exclusive conditions if they exist. It is recommended to use this "global" state interface if - you need to enter the value atomically. The later state + you need to set the value atomically. The later state interface associated with each cable cannot update multiple cable states of an extcon device simultaneously. @@ -73,7 +73,7 @@ What: /sys/class/extcon/.../cable.x/state Date: February 2012 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: - The /sys/class/extcon/.../cable.x/name shows and stores the + The /sys/class/extcon/.../cable.x/state shows and stores the state of cable "x" (integer between 0 and 31) of an extcon device. The state value is either 0 (detached) or 1 (attached). @@ -83,8 +83,8 @@ Date: December 2011 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: Shows the relations of mutually exclusiveness. For example, - if the mutually_exclusive array of extcon_dev is - {0x3, 0x5, 0xC, 0x0}, the, the output is: + if the mutually_exclusive array of extcon device is + {0x3, 0x5, 0xC, 0x0}, then the output is: # ls mutually_exclusive/ 0x3 0x5 diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 7a34f827989..3a863f69272 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -15,8 +15,8 @@ Debugfs is typically mounted with a command like: mount -t debugfs none /sys/kernel/debug (Or an equivalent /etc/fstab line). -The debugfs root directory is accessible by anyone by default. To -restrict access to the tree the "uid", "gid" and "mode" mount +The debugfs root directory is accessible only to the root user by +default. To change access to the tree the "uid", "gid" and "mode" mount options can be used. Note that the debugfs API is exported GPL-only to modules. diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index 49578cf1aea..c5182bb2c16 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -284,9 +284,11 @@ instead, it is associated with the ktype. So let us introduce struct kobj_type: struct kobj_type { - void (*release)(struct kobject *); + void (*release)(struct kobject *kobj); const struct sysfs_ops *sysfs_ops; - struct attribute **default_attrs; + struct attribute **default_attrs; + const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj); + const void *(*namespace)(struct kobject *kobj); }; This structure is used to describe a particular type of kobject (or, more diff --git a/Documentation/zh_CN/arm/Booting b/Documentation/zh_CN/arm/Booting new file mode 100644 index 00000000000..6158a64df80 --- /dev/null +++ b/Documentation/zh_CN/arm/Booting @@ -0,0 +1,175 @@ +Chinese translated version of Documentation/arm/Booting + +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: Russell King <linux@arm.linux.org.uk> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arm/Booting 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Russell King <linux@arm.linux.org.uk> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + + 启动 ARM Linux + ============== + +作者：Russell King +日期：2002年5月18日 + +以下文档适用于 2.4.18-rmk6 及以上版本。 + +为了启动 ARM Linux，你需要一个引导装载程序（boot loader）， +它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种 +设备，并最终调用 Linux 内核，将信息传递给内核。 + +从本质上讲，引导装载程序应提供（至少）以下功能： + +1、设置和初始化 RAM。 +2、初始化一个串口。 +3、检测机器的类型（machine type）。 +4、设置内核标签列表（tagged list）。 +5、调用内核映像。 + + +1、设置和初始化 RAM +------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 +这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有 +RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序 +设计者想到的匹配方法。） + + +2、初始化一个串口 +----------------------------- + +现有的引导加载程序: 可选、建议 +新开发的引导加载程序: 可选、建议 + +引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动 +自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。) + +作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' +选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： + + Documentation/kernel-parameters.txt。 + + +3、检测机器类型 +-------------------------- + +现有的引导加载程序: 可选 +新开发的引导加载程序: 强制 + +引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件 +代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。 +引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。 +(详见 linux/arch/arm/tools/mach-types )。 + +4、设置启动数据 +------------------ + +现有的引导加载程序: 可选、强烈建议 +新开发的引导加载程序: 强制 + +引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动 +数据的物理地址通过寄存器 r2 传递给内核。 + +4a、设置内核标签列表 +-------------------------------- + +bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以 +ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是 +空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为 +‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。 + +在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签 +所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为 +是前者，其他是后者。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +因此，最小的标签列表如下所示： + + +-----------+ +基地址 -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | 地址增长方向 + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +标签列表应该保存在系统的 RAM 中。 + +标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。 +建议放在 RAM 的头 16KiB 中。 + +4b、设置设备树 +------------------------- + +bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 +RAM 中，并用启动数据初始化它。dtb 格式在文档 +Documentation/devicetree/booting-without-of.txt 中。内核将会在 +dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 +标签列表被传递进来。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB +中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着 +没有标签列表和 dtb 传递过来。 + +5、调用内核映像 +--------------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了 +在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中 +直接调用 zImage。 + +zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像 +基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。 + +对于以上任意一种情况，都必须符合以下启动状态： + +- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。 + 这可能可以节省你许多的调试时间。 + +- CPU 寄存器配置 + r0 = 0， + r1 = （在上面 3 中获取的）机器类型码。 + r2 = 标签列表在系统 RAM 中的物理地址，或 + 设备树块(dtb)在系统 RAM 中的物理地址 + +- CPU 模式 + 所有形式的中断必须被禁止 (IRQs 和 FIQs) + CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在) + +- 缓存，MMUs + MMU 必须关闭。 + 指令缓存开启或关闭都可以。 + 数据缓存必须关闭。 + +- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。 + + 对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使 + 对于 Thumb-2 内核也是如此。 + + 对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 + 内核入口时必须处于 Thumb 状态。 diff --git a/Documentation/zh_CN/basic_profiling.txt b/Documentation/zh_CN/basic_profiling.txt new file mode 100644 index 00000000000..1e6bf0bdf8f --- /dev/null +++ b/Documentation/zh_CN/basic_profiling.txt @@ -0,0 +1,71 @@ +Chinese translated version of Documentation/basic_profiling + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Liang Xie <xieliang@xiaomi.com> +--------------------------------------------------------------------- +Documentation/basic_profiling的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 谢良 Liang Xie <xieliang007@gmail.com> +中文版翻译者： 谢良 Liang Xie <xieliang007@gmail.com> +中文版校译者： +以下为正文 +--------------------------------------------------------------------- + +下面这些说明指令都是非常基础的，如果你想进一步了解请阅读相关专业文档：） +请不要再在本文档增加新的内容，但可以修复文档中的错误：）(mbligh@aracnet.com) +感谢John Levon，Dave Hansen等在撰写时的帮助 + +<test> 用于表示要测量的目标 +请先确保您已经有正确的System.map / vmlinux配置！ + +对于linux系统来说，配置vmlinuz最容易的方法可能就是使用“make install”，然后修改 +/sbin/installkernel将vmlinux拷贝到/boot目录，而System.map通常是默认安装好的 + +Readprofile +----------- +2.6系列内核需要版本相对较新的readprofile，比如util-linux 2.12a中包含的，可以从: + +http://www.kernel.org/pub/linux/utils/util-linux/ 下载 + +大部分linux发行版已经包含了. + +启用readprofile需要在kernel启动命令行增加”profile=2“ + +clear readprofile -r + <test> +dump output readprofile -m /boot/System.map > captured_profile + +Oprofile +-------- + +从http://oprofile.sourceforge.net/获取源代码（请参考Changes以获取匹配的版本） +在kernel启动命令行增加“idle=poll” + +配置CONFIG_PROFILING=y和CONFIG_OPROFILE=y然后重启进入新kernel + +./configure --with-kernel-support +make install + +想得到好的测量结果，请确保启用了本地APIC特性。如果opreport显示有0Hz CPU， +说明APIC特性没有开启。另外注意idle=poll选项可能有损性能。 + +One time setup: + opcontrol --setup --vmlinux=/boot/vmlinux + +clear opcontrol --reset +start opcontrol --start + <test> +stop opcontrol --stop +dump output opreport > output_file + +如果只看kernel相关的报告结果，请运行命令 opreport -l /boot/vmlinux > output_file + +通过reset选项可以清理过期统计数据，相当于重启的效果。 + diff --git a/Documentation/zh_CN/filesystems/sysfs.txt b/Documentation/zh_CN/filesystems/sysfs.txt new file mode 100644 index 00000000000..e230eaa3312 --- /dev/null +++ b/Documentation/zh_CN/filesystems/sysfs.txt @@ -0,0 +1,372 @@ +Chinese translated version of Documentation/filesystems/sysfs.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: Patrick Mochel <mochel@osdl.org> + Mike Murphy <mamurph@cs.clemson.edu> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/filesystems/sysfs.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Patrick Mochel <mochel@osdl.org> + Mike Murphy <mamurph@cs.clemson.edu> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +sysfs - 用于导出内核对象(kobject)的文件系统 + +Patrick Mochel <mochel@osdl.org> +Mike Murphy <mamurph@cs.clemson.edu> + +修订: 16 August 2011 +原始版本: 10 January 2003 + + +sysfs 简介: +~~~~~~~~~~ + +sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核 +数据结构及其属性，以及它们之间的关联到用户空间的方法。 + +sysfs 始终与 kobject 的底层结构紧密相关。请阅读 +Documentation/kobject.txt 文档以获得更多关于 kobject 接口的 +信息。 + + +使用 sysfs +~~~~~~~~~~~ + +只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可 +通过以下命令挂载它: + + mount -t sysfs sysfs /sys + + +创建目录 +~~~~~~~~ + +任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个 +目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递 +内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的 +共同祖先；例如：某些对象属于某个子系统。 + +Sysfs 在与其目录关联的 sysfs_dirent 对象中内部保存一个指向实现 +目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于 +kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject +引用计数只能通过 sysfs_schedule_callback() 函数直接修改。 + + +属性 +~~~~ + +kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义 +了面向文件 I/O 操作的方法，以提供对内核属性的读写。 + + +属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个 +文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值 +数组也被广泛地接受。 + +混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是 +很丢脸的,而且其代码会在未通知作者的情况下被重写。 + + +一个简单的属性结构定义如下: + +struct attribute { + char * name; + struct module *owner; + umode_t mode; +}; + + +int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); +void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); + + +一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定 +对象类型的属性定义自己的属性结构体和封装函数。 + +例如:驱动程序模型定义的 device_attribute 结构体如下: + +struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); +}; + +int device_create_file(struct device *, const struct device_attribute *); +void device_remove_file(struct device *, const struct device_attribute *); + +为了定义设备属性，同时定义了一下辅助宏: + +#define DEVICE_ATTR(_name, _mode, _show, _store) \ +struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) + +例如:声明 + +static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); + +等同于如下代码： + +static struct device_attribute dev_attr_foo = { + .attr = { + .name = "foo", + .mode = S_IWUSR | S_IRUGO, + .show = show_foo, + .store = store_foo, + }, +}; + + +子系统特有的回调函数 +~~~~~~~~~~~~~~~~~~~ + +当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作， +以帮助读写调用实现属性所有者的显示和储存方法。 + +struct sysfs_ops { + ssize_t (*show)(struct kobject *, struct attribute *, char *); + ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); +}; + +[子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的 +描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的 +文档] + +sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会 +将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后 +调用相关联的函数。 + + +示例: + +#define to_dev(obj) container_of(obj, struct device, kobj) +#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) + +static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, + char *buf) +{ + struct device_attribute *dev_attr = to_dev_attr(attr); + struct device *dev = to_dev(kobj); + ssize_t ret = -EIO; + + if (dev_attr->show) + ret = dev_attr->show(dev, dev_attr, buf); + if (ret >= (ssize_t)PAGE_SIZE) { + print_symbol("dev_attr_show: %s returned bad count\n", + (unsigned long)dev_attr->show); + } + return ret; +} + + + +读写属性数据 +~~~~~~~~~~~~ + +在声明属性时，必须指定 show() 或 store() 方法，以实现属性的 +读或写。这些方法的类型应该和以下的设备属性定义一样简单。 + +ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); +ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); + +也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。 + +sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。 +Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时 +会出现以下的行为: + +- 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性 + 应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将 + 不会不太高。 + + 这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间 + 向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将 + 再次被调用，以重新填充缓存。 + +- 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。 + 之后 Sysfs 传递整个缓冲区给 store() 方法。 + + 当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要 + 改变的值，然后回写整个缓冲区。 + + 在读写属性值时，属性方法的执行应操作相同的缓冲区。 + +注记: + +- 写操作导致的 show() 方法重载，会忽略当前文件位置。 + +- 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。 + +- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的 + 返回值。 + +- show() 应始终使用 snprintf()。 + +- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回 + count 参数。 + +- show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个 + 错误值。 + +- 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在 + 内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要， + 应该实现一个检测机制。 + +一个简单的(未经实验证实的)设备属性实现如下： + +static ssize_t show_name(struct device *dev, struct device_attribute *attr, + char *buf) +{ + return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); +} + +static ssize_t store_name(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count) +{ + snprintf(dev->name, sizeof(dev->name), "%.*s", + (int)min(count, sizeof(dev->name) - 1), buf); + return count; +} + +static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); + + +（注意：真正的实现不允许用户空间设置设备名。） + +顶层目录布局 +~~~~~~~~~~~~ + +sysfs 目录的安排显示了内核数据结构之间的关系。 + +顶层 sysfs 目录如下: + +block/ +bus/ +class/ +dev/ +devices/ +firmware/ +net/ +fs/ + +devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核 +设备树，反映了设备的层次结构。 + +bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个 +子目录: + + devices/ + drivers/ + +devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的 +设备目录。 + +drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里 +假定驱动没有跨越多个总线类型)。 + +fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须 +在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.txt)。 + +dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以 +<major>:<minor> 格式命名的符号链接。这些符号链接指向 sysfs 目录 +中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找 +设备 sysfs 接口快捷的方法。 + +更多有关 driver-model 的特性信息可以在 Documentation/driver-model/ +中找到。 + + +TODO: 完成这一节。 + + +当前接口 +~~~~~~~~ + +以下的接口层普遍存在于当前的sysfs中: + +- 设备 (include/linux/device.h) +---------------------------------- +结构体: + +struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); +}; + +声明: + +DEVICE_ATTR(_name, _mode, _show, _store); + +增/删属性: + +int device_create_file(struct device *dev, const struct device_attribute * attr); +void device_remove_file(struct device *dev, const struct device_attribute * attr); + + +- 总线驱动程序 (include/linux/device.h) +-------------------------------------- +结构体: + +struct bus_attribute { + struct attribute attr; + ssize_t (*show)(struct bus_type *, char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); +}; + +声明: + +BUS_ATTR(_name, _mode, _show, _store) + +增/删属性: + +int bus_create_file(struct bus_type *, struct bus_attribute *); +void bus_remove_file(struct bus_type *, struct bus_attribute *); + + +- 设备驱动程序 (include/linux/device.h) +----------------------------------------- + +结构体: + +struct driver_attribute { + struct attribute attr; + ssize_t (*show)(struct device_driver *, char * buf); + ssize_t (*store)(struct device_driver *, const char * buf, + size_t count); +}; + +声明: + +DRIVER_ATTR(_name, _mode, _show, _store) + +增/删属性： + +int driver_create_file(struct device_driver *, const struct driver_attribute *); +void driver_remove_file(struct device_driver *, const struct driver_attribute *); + + +文档 +~~~~ + +sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。 +对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs +属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。 diff --git a/Documentation/zh_CN/gpio.txt b/Documentation/zh_CN/gpio.txt new file mode 100644 index 00000000000..4fa7b4e6f85 --- /dev/null +++ b/Documentation/zh_CN/gpio.txt @@ -0,0 +1,658 @@ +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))支持(上升或下降沿)将会被重新配置来遵循 +这个设置。 diff --git a/Documentation/zh_CN/video4linux/omap3isp.txt b/Documentation/zh_CN/video4linux/omap3isp.txt new file mode 100644 index 00000000000..67ffbf352ae --- /dev/null +++ b/Documentation/zh_CN/video4linux/omap3isp.txt @@ -0,0 +1,277 @@ +Chinese translated version of Documentation/video4linux/omap3isp.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: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/video4linux/omap3isp.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +OMAP 3 图像信号处理器 (ISP) 驱动 + +Copyright (C) 2010 Nokia Corporation +Copyright (C) 2009 Texas Instruments, Inc. + +联系人: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> + + +介绍 +=== + +本文档介绍了由 drivers/media/video/omap3isp 加载的德州仪器 +（TI）OMAP 3 图像信号处理器 (ISP) 驱动。原始驱动由德州仪器（TI） +编写，但此后由诺基亚重写了两次。 + +驱动已在以下 OMAP 3 系列的芯片中成功使用： + + 3430 + 3530 + 3630 + +驱动实现了 V4L2、媒体控制器和 v4l2_subdev 接口。支持内核中使用 +v4l2_subdev 接口的传感器、镜头和闪光灯驱动。 + + +拆分为子设备 +========== + +OMAP 3 ISP 被拆分为 V4L2 子设备，ISP中的每个模块都由一个子设备 +来表示。每个子设备向用户空间提供一个 V4L2 子设备接口。 + + OMAP3 ISP CCP2 + OMAP3 ISP CSI2a + OMAP3 ISP CCDC + OMAP3 ISP preview + OMAP3 ISP resizer + OMAP3 ISP AEWB + OMAP3 ISP AF + OMAP3 ISP histogram + +ISP 中每个可能的连接都通过一个链接嵌入到媒体控制器接口中。详见例程 [2]。 + + +控制 OMAP 3 ISP +============== + +通常，对 OMAP 3 ISP 的配置会在下一帧起始时生效。在传感器垂直消隐期间， +模块变为空闲时完成配置。在内存到内存的操作中，视频管道一次处理一帧。 +应用配置应在帧间完成。 + +ISP 中的所有模块，除 CSI-2 和 （可能存在的）CCP2 接收器外，都必须 +接收完整的帧数据。因此，传感器必须保证从不发送部分帧数据给ISP。 + +Autoidle（自动空闲）功能至少在 3430 的 ISP 模块中确实存在一些问题。 +当 omap3isp 模块参数 autoidle 非零时，autoidle（自动空闲）功能 +仅在 3630 中启用了。 + + +事件机制 +====== + +OMAP 3 ISP 驱动在 CCDC 和统计（AEWB、AF 和 直方图）子设备中支持 +V4L2 事件机制接口。 + +CCDC 子设备通过 HS_VS 中断，处理 V4L2_EVENT_FRAME_SYNC 类型 +事件，用于告知帧起始。早期版本的驱动则使用 V4L2_EVENT_OMAP3ISP_HS_VS。 +当在 CCDC 模块中接收到起始帧的第一行时，会准确地触发事件。这个事件 +可以在 CCDC 子设备中“订阅”。 + +（当使用并行接口时，必须注意正确地配置 VS 信号极性。而当使用串行接收时 +这个会自动校正。） + +每个统计子设备都可以产生事件。每当一个统计缓冲区可由用户空间应用程序 +通过 VIDIOC_OMAP3ISP_STAT_REQ IOCTL 操作获取时，就会产生一个 +事件。当前存在以下事件： + + V4L2_EVENT_OMAP3ISP_AEWB + V4L2_EVENT_OMAP3ISP_AF + V4L2_EVENT_OMAP3ISP_HIST + +这些 ioctl 的事件数据类型为 struct omap3isp_stat_event_status +结构体。如果出现计算错误的统计，也同样会产生一个事件，但没有相关的统计 +数据缓冲区。这种情况下 omap3isp_stat_event_status.buf_err 会被 +设置为非零值。 + + +私有 IOCTL +========== + +OMAP 3 ISP 驱动支持标准的 V4L2 IOCTL 以及可能存在且实用的控制。但 +ISP 提供的许多功能都不在标准 IOCTL 之列，例如 gamma（伽马）表和统计 +数据采集配置等。 + +通常，会有一个私有 ioctl 用于配置每个包含硬件依赖功能的模块。 + +支持以下私有 IOCTL： + + VIDIOC_OMAP3ISP_CCDC_CFG + VIDIOC_OMAP3ISP_PRV_CFG + VIDIOC_OMAP3ISP_AEWB_CFG + VIDIOC_OMAP3ISP_HIST_CFG + VIDIOC_OMAP3ISP_AF_CFG + VIDIOC_OMAP3ISP_STAT_REQ + VIDIOC_OMAP3ISP_STAT_EN + +在 include/linux/omap3isp.h 中描述了这些 ioctl 使用的参数结构体。 +与特定 ISP 模块相关的 ISP 自身的详细功能在技术参考手册 (TRMs)中有 +描述，详见文档结尾。 + +虽然在不使用任何私有 IOCTL 的情况下使用 ISP 驱动是可能的，但这样无法 +获得最佳的图像质量。AEWB、AF 和 直方图（译者注：一般用于自动曝光和增益 +控制，以及图像均衡等）模块无法在未使用适当的私有 IOCTL 配置的情况下使用。 + + +CCDC 和 preview（预览）模块 IOCTL +=============================== + +VIDIOC_OMAP3ISP_CCDC_CFG 和 VIDIOC_OMAP3ISP_PRV_CFG IOCTL +被分别用于配置、启用和禁用 CCDC 和 preview（预览）模块的功能。在它们 +所控制的模块中，两个 IOCTL 控制多种功能。VIDIOC_OMAP3ISP_CCDC_CFG IOCTL +接受一个指向 omap3isp_ccdc_update_config 结构体的指针作为它的参数。 +同样的，VIDIOC_OMAP3ISP_PRV_CFG 接受一个指向 omap3isp_prev_update_config +结构体的指针。以上两个结构体定义位于 [1]。 + +这些结构体中的 update 域标识是否针对指定的功能更新配置，而 flag 域 +则标识是启用还是禁用此功能。 + +update 和 flag 位接受以下掩码值。CCDC 和 preview（预览）模块的 +每个单独功能都与一个 flag 关联（禁用或启用；在结构体中 flag 域的 +一部分）和一个指向功能配置数据的指针。 + +对于 VIDIOC_OMAP3ISP_CCDC_CFG，下面列出了 update 和 flag 域 +中的有效值。 这些值可能会在同一个 IOCTL 调用中配置多个功能。 + + OMAP3ISP_CCDC_ALAW + OMAP3ISP_CCDC_LPF + OMAP3ISP_CCDC_BLCLAMP + OMAP3ISP_CCDC_BCOMP + OMAP3ISP_CCDC_FPC + OMAP3ISP_CCDC_CULL + OMAP3ISP_CCDC_CONFIG_LSC + OMAP3ISP_CCDC_TBL_LSC + +针对 VIDIOC_OMAP3ISP_PRV_CFG 的相应值如下： + + OMAP3ISP_PREV_LUMAENH + OMAP3ISP_PREV_INVALAW + OMAP3ISP_PREV_HRZ_MED + OMAP3ISP_PREV_CFA + OMAP3ISP_PREV_CHROMA_SUPP + OMAP3ISP_PREV_WB + OMAP3ISP_PREV_BLKADJ + OMAP3ISP_PREV_RGB2RGB + OMAP3ISP_PREV_COLOR_CONV + OMAP3ISP_PREV_YC_LIMIT + OMAP3ISP_PREV_DEFECT_COR + OMAP3ISP_PREV_GAMMABYPASS + OMAP3ISP_PREV_DRK_FRM_CAPTURE + OMAP3ISP_PREV_DRK_FRM_SUBTRACT + OMAP3ISP_PREV_LENS_SHADING + OMAP3ISP_PREV_NF + OMAP3ISP_PREV_GAMMA + +在启用某个功能的时候，相关的配置数据指针不可为 NULL。在禁用某个功能时， +配置数据指针会被忽略。 + + +统计模块 IOCTL +============= + +统计子设备相较于其他子设备提供了更多动态配置选项。在图像处理流水线处于 +工作状态时，它们可以被启用、禁用和重配。 + +统计模块总是从 CCDC 中获取输入的图像数据（由于直方图内存读取未实现）。 +统计数据可由用户通过统计子设备节点使用私有 IOCTL 获取。 + +AEWB、AF 和 直方图子设备提供的私有 IOCTL 极大程度上反应了 ISP 硬件 +提供的寄存器级接口。有些方面纯粹和驱动程序的实现相关，这些将在下面讨论。 + +VIDIOC_OMAP3ISP_STAT_EN +----------------------- + +这个私有 IOCTL 启用/禁用 一个统计模块。如果这个申请在视频流启动前完成， +它将在视频流水线开始工作时生效。如果视频流水线已经处于工作状态了，它将在 +CCDC 变为空闲时生效。 + +VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG +----------------------------------------------------------------------------- + +这些 IOCTL 用于配置模块。它们要求用户应用程序对硬件有深入的认识。对 +大多数域的解释可以在 OMAP 的 TRM 中找到。以下两个域对于以上所有的 +私有 IOCTL 配置都很常见，由于他们没有在 TRM 中提及，故需要对其有 +更好的认识。 + +omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size: + +模块在内部处理自身缓冲。对模块数据输出所必需的缓存大小依赖于已申请的配置。 +虽然驱动支持在视频流工作时重新配置，但对于所需缓存量大于模块启用时内部 +所分配数量的情况，则不支持重新配置。在这种情况下将返回 -EBUSY。为了避免 +此类状况，无论是禁用/重配/启用模块，还是第一次配置时申请必须的缓存大小， +都应在模块禁用的情况下进行。 + +内部缓冲分配的大小需综合考虑所申请配置的最小缓存量以及 buf_size 域中 +所设的值。如果 buf_size 域在[minimum（最小值）, maximum（最大值）] +缓冲大小范围之外，则应该将其调整到其范围中。驱动则会选择最大值。正确的 +buf_size 值将回写到用户应用程序中。 + +omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter: + +由于配置并未在申请之后同步生效，驱动必须提供一个跟踪这类信息的方法， +以提供更准确的数据。在一个配置被申请之后，返回到用户空间应用程序的 +config_counter 是一个与其配置相关的唯一值。当用户应用程序接收到 +一个缓冲可用或一个新的缓冲申请事件时，这个 config_counter 用于 +一个缓冲数据和一个配置的匹配。 + +VIDIOC_OMAP3ISP_STAT_REQ +------------------------ + +将内部缓冲队列中最早的数据发送到用户空间，然后丢弃此缓冲区。 +omap3isp_stat_data.frame_number 域与视频缓冲的 field_count +域相匹配。 + + +技术参考手册 (TRMs) 和其他文档 +========================== + +OMAP 3430 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip> +参考于 2011-03-05. + +OMAP 35xx TRM: +<URL:http://www.ti.com/litv/pdf/spruf98o> 参考于 2011-03-05. + +OMAP 3630 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip> +参考于 2011-03-05. + +DM 3730 TRM: +<URL:http://www.ti.com/litv/pdf/sprugn4h> 参考于 2011-03-06. + + +参考资料 +======= + +[1] include/linux/omap3isp.h + +[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary diff --git a/Documentation/zh_CN/video4linux/v4l2-framework.txt b/Documentation/zh_CN/video4linux/v4l2-framework.txt new file mode 100644 index 00000000000..3e74f13af42 --- /dev/null +++ b/Documentation/zh_CN/video4linux/v4l2-framework.txt @@ -0,0 +1,983 @@ +Chinese translated version of Documentation/video4linux/v4l2-framework.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: Mauro Carvalho Chehab <mchehab@infradead.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/video4linux/v4l2-framework.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Mauro Carvalho Chehab <mchehab@infradead.org> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +V4L2 驱动框架概览 +============== + +本文档描述 V4L2 框架所提供的各种结构和它们之间的关系。 + + +介绍 +---- + +大部分现代 V4L2 设备由多个 IC 组成，在 /dev 下导出多个设备节点， +并同时创建非 V4L2 设备（如 DVB、ALSA、FB、I2C 和红外输入设备）。 +由于这种硬件的复杂性，V4L2 驱动也变得非常复杂。 + +尤其是 V4L2 必须支持 IC 实现音视频的多路复用和编解码，这就更增加了其 +复杂性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器，但也可 +使用其他总线。这些设备称为“子设备”。 + +长期以来，这个框架仅限于通过 video_device 结构体创建 V4L 设备节点， +并使用 video_buf 处理视频缓冲（注：本文不讨论 video_buf 框架）。 + +这意味着所有驱动必须自己设置设备实例并连接到子设备。其中一部分要正确地 +完成是比较复杂的，使得许多驱动都没有正确地实现。 + +由于框架的缺失，有很多通用代码都不可重复利用。 + +因此，这个框架构建所有驱动都需要的基本结构块，而统一的框架将使通用代码 +创建成实用函数并在所有驱动中共享变得更加容易。 + + +驱动结构 +------- + +所有 V4L2 驱动都有如下结构： + +1) 每个设备实例的结构体--包含其设备状态。 + +2) 初始化和控制子设备的方法（如果有）。 + +3) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX) + 并跟踪设备节点的特定数据。 + +4) 特定文件句柄结构体--包含每个文件句柄的数据。 + +5) 视频缓冲处理。 + +以下是它们的初略关系图： + + device instances（设备实例） + | + +-sub-device instances（子设备实例） + | + \-V4L2 device nodes（V4L2 设备节点） + | + \-filehandle instances（文件句柄实例） + + +框架结构 +------- + +该框架非常类似驱动结构：它有一个 v4l2_device 结构用于保存设备 +实例的数据；一个 v4l2_subdev 结构体代表子设备实例；video_device +结构体保存 V4L2 设备节点的数据；将来 v4l2_fh 结构体将跟踪文件句柄 +实例（暂未尚未实现）。 + +V4L2 框架也可与媒体框架整合（可选的）。如果驱动设置了 v4l2_device +结构体的 mdev 域，子设备和视频节点的入口将自动出现在媒体框架中。 + + +v4l2_device 结构体 +---------------- + +每个设备实例都通过 v4l2_device (v4l2-device.h)结构体来表示。 +简单设备可以仅分配这个结构体，但在大多数情况下，都会将这个结构体 +嵌入到一个更大的结构体中。 + +你必须注册这个设备实例： + + v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); + +注册操作将会初始化 v4l2_device 结构体。如果 dev->driver_data 域 +为 NULL，就将其指向 v4l2_dev。 + +需要与媒体框架整合的驱动必须手动设置 dev->driver_data，指向包含 +v4l2_device 结构体实例的驱动特定设备结构体。这可以在注册 V4L2 设备 +实例前通过 dev_set_drvdata() 函数完成。同时必须设置 v4l2_device +结构体的 mdev 域，指向适当的初始化并注册过的 media_device 实例。 + +如果 v4l2_dev->name 为空，则它将被设置为从 dev 中衍生出的值（为了 +更加精确，形式为驱动名后跟 bus_id）。如果你在调用 v4l2_device_register +前已经设置好了，则不会被修改。如果 dev 为 NULL，则你*必须*在调用 +v4l2_device_register 前设置 v4l2_dev->name。 + +你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号，通过 +v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等 +名字。若驱动名以数字结尾，则会在编号和驱动名间插入一个破折号，如： +cx18-0、cx18-1 等。此函数返回实例编号。 + +第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或 +platform_device 的指针。很少使其为 NULL，除非是一个ISA设备或者 +当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备 +关联。 + +你也可以提供一个 notify() 回调，使子设备可以调用它实现事件通知。 +但这个设置与子设备相关。子设备支持的任何通知必须在 +include/media/<subdevice>.h 中定义一个消息头。 + +注销 v4l2_device 使用如下函数： + + v4l2_device_unregister(struct v4l2_device *v4l2_dev); + +如果 dev->driver_data 域指向 v4l2_dev，将会被重置为 NULL。注销同时 +会自动从设备中注销所有子设备。 + +如果你有一个热插拔设备（如USB设备），则当断开发生时，父设备将无效。 +由于 v4l2_device 有一个指向父设备的指针必须被清除，同时标志父设备 +已消失，所以必须调用以下函数： + + v4l2_device_disconnect(struct v4l2_device *v4l2_dev); + +这个函数并*不*注销子设备，因此你依然要调用 v4l2_device_unregister() +函数。如果你的驱动器并非热插拔的，就没有必要调用 v4l2_device_disconnect()。 + +有时你需要遍历所有被特定驱动注册的设备。这通常发生在多个设备驱动使用 +同一个硬件的情况下。如：ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动， +同时 alsa 驱动也使用此硬件。 + +你可以使用如下例程遍历所有注册的设备： + +static int callback(struct device *dev, void *p) +{ + struct v4l2_device *v4l2_dev = dev_get_drvdata(dev); + + /* 测试这个设备是否已经初始化 */ + if (v4l2_dev == NULL) + return 0; + ... + return 0; +} + +int iterate(void *p) +{ + struct device_driver *drv; + int err; + + /* 在PCI 总线上查找ivtv驱动。 + pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */ + drv = driver_find("ivtv", &pci_bus_type); + /* 遍历所有的ivtv设备实例 */ + err = driver_for_each_device(drv, NULL, p, callback); + put_driver(drv); + return err; +} + +有时你需要一个设备实例的运行计数。这个通常用于映射一个设备实例到一个 +模块选择数组的索引。 + +推荐方法如下： + +static atomic_t drv_instance = ATOMIC_INIT(0); + +static int __devinit drv_probe(struct pci_dev *pdev, + const struct pci_device_id *pci_id) +{ + ... + state->instance = atomic_inc_return(&drv_instance) - 1; +} + +如果你有多个设备节点，对于热插拔设备，知道何时注销 v4l2_device 结构体 +就比较困难。为此 v4l2_device 有引用计数支持。当调用 video_register_device +时增加引用计数，而设备节点释放时减小引用计数。当引用计数为零，则 +v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。 + +如果创建了其他设备节点（比如 ALSA），则你可以通过以下函数手动增减 +引用计数： + +void v4l2_device_get(struct v4l2_device *v4l2_dev); + +或: + +int v4l2_device_put(struct v4l2_device *v4l2_dev); + +由于引用技术初始化为 1 ，你也需要在 disconnect() 回调（对于 USB 设备）中 +调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），否则 +引用计数将永远不会为 0 。 + +v4l2_subdev结构体 +------------------ + +许多驱动需要与子设备通信。这些设备可以完成各种任务，但通常他们负责 +音视频复用和编解码。如网络摄像头的子设备通常是传感器和摄像头控制器。 + +这些一般为 I2C 接口设备，但并不一定都是。为了给驱动提供调用子设备的 +统一接口，v4l2_subdev 结构体（v4l2-subdev.h）产生了。 + +每个子设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体可以单独 +代表一个简单的子设备，也可以嵌入到一个更大的结构体中，与更多设备状态 +信息保存在一起。通常有一个下级设备结构体（比如：i2c_client）包含了 +内核创建的设备数据。建议使用 v4l2_set_subdevdata() 将这个结构体的 +指针保存在 v4l2_subdev 的私有数据域(dev_priv)中。这使得通过 v4l2_subdev +找到实际的低层总线特定设备数据变得容易。 + +你同时需要一个从低层结构体获取 v4l2_subdev 指针的方法。对于常用的 +i2c_client 结构体，i2c_set_clientdata() 函数可用于保存一个 v4l2_subdev +指针；对于其他总线你可能需要使用其他相关函数。 + +桥驱动中也应保存每个子设备的私有数据，比如一个指向特定桥的各设备私有 +数据的指针。为此 v4l2_subdev 结构体提供主机私有数据域(host_priv)， +并可通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata() +访问。 + +从总线桥驱动的视角，驱动加载子设备模块并以某种方式获得 v4l2_subdev +结构体指针。对于 i2c 总线设备相对简单：调用 i2c_get_clientdata()。 +对于其他总线也需要做类似的操作。针对 I2C 总线上的子设备辅助函数帮你 +完成了大部分复杂的工作。 + +每个 v4l2_subdev 都包含子设备驱动需要实现的函数指针（如果对此设备 +不适用，可为NULL）。由于子设备可完成许多不同的工作，而在一个庞大的 +函数指针结构体中通常仅有少数有用的函数实现其功能肯定不合适。所以， +函数指针根据其实现的功能被分类，每一类都有自己的函数指针结构体。 + +顶层函数指针结构体包含了指向各类函数指针结构体的指针，如果子设备驱动 +不支持该类函数中的任何一个功能，则指向该类结构体的指针为NULL。 + +这些结构体定义如下： + +struct v4l2_subdev_core_ops { + int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip); + int (*log_status)(struct v4l2_subdev *sd); + int (*init)(struct v4l2_subdev *sd, u32 val); + ... +}; + +struct v4l2_subdev_tuner_ops { + ... +}; + +struct v4l2_subdev_audio_ops { + ... +}; + +struct v4l2_subdev_video_ops { + ... +}; + +struct v4l2_subdev_pad_ops { + ... +}; + +struct v4l2_subdev_ops { + const struct v4l2_subdev_core_ops *core; + const struct v4l2_subdev_tuner_ops *tuner; + const struct v4l2_subdev_audio_ops *audio; + const struct v4l2_subdev_video_ops *video; + const struct v4l2_subdev_pad_ops *video; +}; + +其中 core（核心）函数集通常可用于所有子设备，其他类别的实现依赖于 +子设备。如视频设备可能不支持音频操作函数，反之亦然。 + +这样的设置在限制了函数指针数量的同时，还使增加新的操作函数和分类 +变得较为容易。 + +子设备驱动可使用如下函数初始化 v4l2_subdev 结构体： + + v4l2_subdev_init(sd, &ops); + +然后，你必须用一个唯一的名字初始化 subdev->name，并初始化模块的 +owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。 + +若需同媒体框架整合，你必须调用 media_entity_init() 初始化 v4l2_subdev +结构体中的 media_entity 结构体（entity 域）： + + struct media_pad *pads = &my_sd->pads; + int err; + + err = media_entity_init(&sd->entity, npads, pads, 0); + +pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和 +name 域，但如有必要，revision 域必须初始化。 + +当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 + +在子设备被注销之后，不要忘记清理 media_entity 结构体： + + media_entity_cleanup(&sd->entity); + +如果子设备驱动趋向于处理视频并整合进了媒体框架，必须使用 v4l2_subdev_pad_ops +替代 v4l2_subdev_video_ops 实现格式相关的功能。 + +这种情况下，子设备驱动应该设置 link_validate 域，以提供它自身的链接 +验证函数。链接验证函数应对管道（两端链接的都是 V4L2 子设备）中的每个 +链接调用。驱动还要负责验证子设备和视频节点间格式配置的正确性。 + +如果 link_validate 操作没有设置，默认的 v4l2_subdev_link_validate_default() +函数将会被调用。这个函数保证宽、高和媒体总线像素格式在链接的收发两端 +都一致。子设备驱动除了它们自己的检测外，也可以自由使用这个函数以执行 +上面提到的检查。 + +设备（桥）驱动程序必须向 v4l2_device 注册 v4l2_subdev： + + int err = v4l2_device_register_subdev(v4l2_dev, sd); + +如果子设备模块在它注册前消失，这个操作可能失败。在这个函数成功返回后， +subdev->dev 域就指向了 v4l2_device。 + +如果 v4l2_device 父设备的 mdev 域为非 NULL 值，则子设备实体将被自动 +注册为媒体设备。 + +注销子设备则可用如下函数： + + v4l2_device_unregister_subdev(sd); + +此后，子设备模块就可卸载，且 sd->dev == NULL。 + +注册之设备后，可通过以下方式直接调用其操作函数： + + err = sd->ops->core->g_chip_ident(sd, &chip); + +但使用如下宏会比较容易且合适： + + err = v4l2_subdev_call(sd, core, g_chip_ident, &chip); + +这个宏将会做 NULL 指针检查，如果 subdev 为 NULL，则返回-ENODEV；如果 +subdev->core 或 subdev->core->g_chip_ident 为 NULL，则返回 -ENOIOCTLCMD； +否则将返回 subdev->ops->core->g_chip_ident ops 调用的实际结果。 + +有时也可能同时调用所有或一系列子设备的某个操作函数： + + v4l2_device_call_all(v4l2_dev, 0, core, g_chip_ident, &chip); + +任何不支持此操作的子设备都会被跳过，并忽略错误返回值。但如果你需要 +检查出错码，则可使用如下函数： + + err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_chip_ident, &chip); + +除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果（除 -ENOIOCTLCMD +外）没有错误发生，则返回 0。 + +对于以上两个函数的第二个参数为组 ID。如果为 0，则所有子设备都会执行 +这个操作。如果为非 0 值，则只有那些组 ID 匹配的子设备才会执行此操作。 +在桥驱动注册一个子设备前，可以设置 sd->grp_id 为任何期望值（默认值为 +0）。这个值属于桥驱动，且子设备驱动将不会修改和使用它。 + +组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路板上有多个 +音频芯片，每个都有改变音量的能力。但当用户想要改变音量的时候，通常 +只有一个会被实际使用。你可以对这样的子设备设置组 ID 为（例如 AUDIO_CONTROLLER） +并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有 +需要的子设备才会执行这个回调。 + +如果子设备需要通知它的 v4l2_device 父设备一个事件，可以调用 +v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个 +notify() 回调被注册，如果没有，返回 -ENODEV。否则返回 notify() 调用 +结果。 + +使用 v4l2_subdev 的好处在于它是一个通用结构体，且不包含任何底层硬件 +信息。所有驱动可以包含多个 I2C 总线的子设备，但也有子设备是通过 GPIO +控制。这个区别仅在配置设备时有关系，一旦子设备注册完成，对于 v4l2 +子系统来说就完全透明了。 + + +V4L2 子设备用户空间API +-------------------- + +除了通过 v4l2_subdev_ops 结构导出的内核 API，V4L2 子设备也可以直接 +通过用户空间应用程序来控制。 + +可以在 /dev 中创建名为 v4l-subdevX 设备节点，以通过其直接访问子设备。 +如果子设备支持用户空间直接配置，必须在注册前设置 V4L2_SUBDEV_FL_HAS_DEVNODE +标志。 + +注册子设备之后， v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes() +函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的子设备创建 +设备节点。这些设备节点会在子设备注销时自动删除。 + +这些设备节点处理 V4L2 API 的一个子集。 + +VIDIOC_QUERYCTRL +VIDIOC_QUERYMENU +VIDIOC_G_CTRL +VIDIOC_S_CTRL +VIDIOC_G_EXT_CTRLS +VIDIOC_S_EXT_CTRLS +VIDIOC_TRY_EXT_CTRLS + + 这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同，唯一的 + 不同是他们只处理子设备的控制实现。根据驱动程序，这些控制也 + 可以通过一个（或多个） V4L2 设备节点访问。 + +VIDIOC_DQEVENT +VIDIOC_SUBSCRIBE_EVENT +VIDIOC_UNSUBSCRIBE_EVENT + + 这些 ioctls 事件与 V4L2 中定义的一致。他们行为相同，唯一的 + 不同是他们只处理子设备产生的事件。根据驱动程序，这些事件也 + 可以通过一个（或多个） V4L2 设备节点上报。 + + 要使用事件通知的子设备驱动，在注册子设备前必须在 v4l2_subdev::flags + 中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents + 中初始化事件队列深度。注册完成后，事件会在 v4l2_subdev::devnode + 设备节点中像通常一样被排队。 + + 为正确支持事件机制，poll() 文件操作也应被实现。 + +私有 ioctls + + 不在以上列表中的所有 ioctls 会通过 core::ioctl 操作直接传递 + 给子设备驱动。 + + +I2C 子设备驱动 +------------- + +由于这些驱动很常见，所以内特提供了特定的辅助函数(v4l2-common.h)让这些 +设备的使用更加容易。 + +添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体 +嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态 +结构体，此时可以直接创建一个 v4l2_subdev 结构体。 + +一个典型的状态结构体如下所示（‘chipname’用芯片名代替）： + +struct chipname_state { + struct v4l2_subdev sd; + ... /* 附加的状态域*/ +}; + +初始化 v4l2_subdev 结构体的方法如下： + + v4l2_i2c_subdev_init(&state->sd, client, subdev_ops); + +这个函数将填充 v4l2_subdev 结构体中的所有域，并保证 v4l2_subdev 和 +i2c_client 都指向彼此。 + +同时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针 +添加一个辅助内联函数。 + +static inline struct chipname_state *to_state(struct v4l2_subdev *sd) +{ + return container_of(sd, struct chipname_state, sd); +} + +使用以下函数可以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体 +指针： + + struct i2c_client *client = v4l2_get_subdevdata(sd); + +而以下函数则相反，通过 i2c_client 结构体指针获得 v4l2_subdev 结构体 +指针： + + struct v4l2_subdev *sd = i2c_get_clientdata(client); + +当 remove()函数被调用前，必须保证先调用 v4l2_device_unregister_subdev(sd)。 +此操作将会从桥驱动中注销子设备。即使子设备没有注册，调用此函数也是 +安全的。 + +必须这样做的原因是：当桥驱动注销 i2c 适配器时，remove()回调函数 +会被那个适配器上的 i2c 设备调用。此后，相应的 v4l2_subdev 结构体 +就不存在了，所有它们必须先被注销。在 remove()回调函数中调用 +v4l2_device_unregister_subdev(sd)，可以保证执行总是正确的。 + + +桥驱动也有一些辅组函数可用： + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, + "module_foo", "chipid", 0x36, NULL); + +这个函数会加载给定的模块（如果没有模块需要加载，可以为 NULL）， +并用给定的 i2c 适配器结构体指针（i2c_adapter）和 器件地址（chip/address） +作为参数调用 i2c_new_device()。如果一切顺利，则就在 v4l2_device +中注册了子设备。 + +你也可以利用 v4l2_i2c_new_subdev()的最后一个参数，传递一个可能的 +I2C 地址数组，让函数自动探测。这些探测地址只有在前一个参数为 0 的 +情况下使用。非零参数意味着你知道准确的 i2c 地址，所以此时无须进行 +探测。 + +如果出错，两个函数都返回 NULL。 + +注意：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。 +它允许你指定一个芯片的变体，比如“saa7114”或“saa7115”。一般通过 +i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与 +i2c 驱动不同，较容易混淆。要知道支持哪些芯片变体，你可以查阅 i2c +驱动代码的 i2c_device_id 表，上面列出了所有可能支持的芯片。 + +还有两个辅助函数： + +v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data +参数，并有‘addr’和‘probed_addrs’参数：如果 addr 非零，则被使用 +（不探测变体），否则 probed_addrs 中的地址将用于自动探测。 + +例如：以下代码将会探测地址（0x10）： + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter, + "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10)); + +v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其 +替代 irq、platform_data 和 add r参数传递给 i2c 驱动。 + +如果子设备支持 s_config 核心操作，这个操作会在子设备配置好之后以 irq 和 +platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数 +同样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。 + +video_device结构体 +----------------- + +在 /dev 目录下的实际设备节点根据 video_device 结构体(v4l2-dev.h) +创建。此结构体既可以动态分配也可以嵌入到一个更大的结构体中。 + +动态分配方法如下： + + struct video_device *vdev = video_device_alloc(); + + if (vdev == NULL) + return -ENOMEM; + + vdev->release = video_device_release; + +如果将其嵌入到一个大结构体中，则必须自己实现 release()回调。 + + struct video_device *vdev = &my_vdev->vdev; + + vdev->release = my_vdev_release; + +release()回调必须被设置，且在最后一个 video_device 用户退出之后 +被调用。 + +默认的 video_device_release()回调只是调用 kfree 来释放之前分配的 +内存。 + +你应该设置这些域： + +- v4l2_dev: 设置为 v4l2_device 父设备。 + +- name: 设置为唯一的描述性设备名。 + +- fops: 设置为已有的 v4l2_file_operations 结构体。 + +- ioctl_ops: 如果你使用v4l2_ioctl_ops 来简化 ioctl 的维护 + (强烈建议使用，且将来可能变为强制性的!)，然后设置你自己的 + v4l2_ioctl_ops 结构体. + +- lock: 如果你要在驱动中实现所有的锁操作，则设为 NULL 。否则 + 就要设置一个指向 struct mutex_lock 结构体的指针，这个锁将 + 在 unlocked_ioctl 文件操作被调用前由内核获得，并在调用返回后 + 释放。详见下一节。 + +- prio: 保持对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果 + 设置为 NULL，则会使用 v4l2_device 中的 v4l2_prio_state 结构体。 + 如果要对每个设备节点（组）实现独立的优先级，可以将其指向自己 + 实现的 v4l2_prio_state 结构体。 + +- parent: 仅在使用 NULL 作为父设备结构体参数注册 v4l2_device 时 + 设置此参数。只有在一个硬件设备包含多一个 PCI 设备，共享同一个 + v4l2_device 核心时才会发生。 + + cx88 驱动就是一个例子：一个 v4l2_device 结构体核心，被一个裸的 + 视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于 + v4l2_device 无法与特定的 PCI 设备关联，所有没有设置父设备。但当 + video_device 配置后，就知道使用哪个父 PCI 设备了。 + +- flags：可选。如果你要让框架处理设置 VIDIOC_G/S_PRIORITY ioctls， + 请设置 V4L2_FL_USE_FH_PRIO。这要求你使用 v4l2_fh 结构体。 + 一旦所有驱动使用了核心的优先级处理，最终这个标志将消失。但现在它 + 必须被显式设置。 + +如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中 +设置 .unlocked_ioctl 指向 video_ioctl2。 + +请勿使用 .ioctl！它已被废弃，今后将消失。 + +某些情况下你要告诉核心：你在 v4l2_ioctl_ops 指定的某个函数应被忽略。 +你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。 + +void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd); + +基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想 +要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。 + +v4l2_file_operations 结构体是 file_operations 的一个子集。其主要 +区别在于：因 inode 参数从未被使用，它将被忽略。 + +如果需要与媒体框架整合，你必须通过调用 media_entity_init() 初始化 +嵌入在 video_device 结构体中的 media_entity（entity 域）结构体： + + struct media_pad *pad = &my_vdev->pad; + int err; + + err = media_entity_init(&vdev->entity, 1, pad, 0); + +pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和 +name 域。 + +当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 + +v4l2_file_operations 与锁 +-------------------------- + +你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常 +这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下，此锁 +用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数可禁用锁定： + + void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd); + +例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF); + +你必须在注册 video_device 前调用这个函数。 + +特别是对于 USB 驱动程序，某些命令（如设置控制）需要很长的时间，可能 +需要自行为缓冲区队列的 ioctls 实现锁定。 + +如果你需要更细粒度的锁，你必须设置 mutex_lock 为 NULL，并完全自己实现 +锁机制。 + +这完全由驱动开发者决定使用何种方法。然而，如果你的驱动存在长延时操作 +（例如，改变 USB 摄像头的曝光时间可能需要较长时间），而你又想让用户 +在等待长延时操作完成期间做其他的事，则你最好自己实现锁机制。 + +如果指定一个锁，则所有 ioctl 操作将在这个锁的作用下串行执行。如果你 +使用 videobuf，则必须将同一个锁传递给 videobuf 队列初始化函数；如 +videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动 +也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程 +可以在第一个进程阻塞时访问设备节点。 + +在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调 +在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用 +锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。 + +热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。 + +video_device注册 +--------------- + +接下来你需要注册视频设备：这会为你创建一个字符设备。 + + err = video_register_device(vdev, VFL_TYPE_GRABBER, -1); + if (err) { + video_device_release(vdev); /* or kfree(my_vdev); */ + return err; + } + +如果 v4l2_device 父设备的 mdev 域为非 NULL 值，视频设备实体将自动 +注册为媒体设备。 + +注册哪种设备是根据类型（type）参数。存在以下类型： + +VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX +VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视) +VFL_TYPE_RADIO: 用于广播调谐器的 radioX + +最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。 +通常你可以传入-1，让 v4l2 框架自己选择第一个空闲的编号。但是有时用户 +需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的 +设备节点号是很普遍的。这个编号将会传递给这个函数，且 video_register_device +将会试图选择这个设备节点号。如果这个编号被占用，下一个空闲的设备节点 +编号将被选中，并向内核日志中发送一个警告信息。 + +另一个使用场景是当驱动创建多个设备时。这种情况下，对不同的视频设备在 +编号上使用不同的范围是很有用的。例如，视频捕获设备从 0 开始，视频 +输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值， +而 v4l2 框架会试图选择第一个的空闲编号（等于或大于你提供的编号）。 +如果失败，则它会就选择第一个空闲的编号。 + +由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用 +video_register_device_no_warn() 函数避免警告信息的产生。 + +只要设备节点被创建，一些属性也会同时创建。在 /sys/class/video4linux +目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和 +‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。 + +‘index’属性值就是设备节点的索引值：每次调用 video_register_device()， +索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。 + +用户可以设置 udev 规则，利用索引属性生成花哨的设备名（例如：用‘mpegX’ +代表 MPEG 视频捕获设备节点）。 + +在设备成功注册后，就可以使用这些域： + +- vfl_type: 传递给 video_register_device 的设备类型。 +- minor: 已指派的次设备号。 +- num: 设备节点编号 (例如 videoX 中的 X)。 +- index: 设备索引号。 + +如果注册失败，你必须调用 video_device_release() 来释放已分配的 +video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中， +你也必须释放它。vdev->release() 回调不会在注册失败之后被调用， +你也不应试图在注册失败后注销设备。 + + +video_device 注销 +---------------- + +当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销 +它们： + + video_unregister_device(vdev); + +这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。 + +video_unregister_device() 返回之后，就无法完成打开操作。尽管如此， +USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备 +节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。 + +当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用， +并且你可以做最后的清理操作。 + +不要忘记清理与视频设备相关的媒体入口（如果被初始化过）： + + media_entity_cleanup(&vdev->entity); + +这可以在 release 回调中完成。 + + +video_device 辅助函数 +--------------------- + +一些有用的辅助函数如下： + +- file/video_device 私有数据 + +你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据： + +void *video_get_drvdata(struct video_device *vdev); +void video_set_drvdata(struct video_device *vdev, void *data); + +注意：在调用 video_register_device() 前执行 video_set_drvdata() +是安全的。 + +而以下函数： + +struct video_device *video_devdata(struct file *file); + +返回 file 结构体中拥有的的 video_device 指针。 + +video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata +的功能： + +void *video_drvdata(struct file *file); + +你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体 +指针： + +struct v4l2_device *v4l2_dev = vdev->v4l2_dev; + +- 设备节点名 + +video_device 设备节点在内核中的名称可以通过以下函数获得 + +const char *video_device_node_name(struct video_device *vdev); + +这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用 +此功能，而非访问 video_device::num 和 video_device::minor 域。 + + +视频缓冲辅助函数 +--------------- + +v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。 +这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。 +目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、 +线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc +分配的缓冲(videobuf-vmalloc)。 + +请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf +层的使用信息。 + +v4l2_fh 结构体 +------------- + +v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。 +如果 video_device 的 flag 设置了 V4L2_FL_USE_FH_PRIO 标志，新驱动 +必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。 + +v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试 +video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用 +v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init() +时被设置。 + +v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在 +其打开函数中将 file->private_data 指向它。 + +在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下， +应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中 +调用 v4l2_fh_del+v4l2_fh_exit。 + +驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如： + +struct my_fh { + int blah; + struct v4l2_fh fh; +}; + +... + +int my_open(struct file *file) +{ + struct my_fh *my_fh; + struct video_device *vfd; + int ret; + + ... + + my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + + ... + + v4l2_fh_init(&my_fh->fh, vfd); + + ... + + file->private_data = &my_fh->fh; + v4l2_fh_add(&my_fh->fh); + return 0; +} + +int my_release(struct file *file) +{ + struct v4l2_fh *fh = file->private_data; + struct my_fh *my_fh = container_of(fh, struct my_fh, fh); + + ... + v4l2_fh_del(&my_fh->fh); + v4l2_fh_exit(&my_fh->fh); + kfree(my_fh); + return 0; +} + +以下是 v4l2_fh 函数使用的简介： + +void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) + + 初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open() + 函数中执行。 + +void v4l2_fh_add(struct v4l2_fh *fh) + + 添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄 + 初始化完成就必须调用。 + +void v4l2_fh_del(struct v4l2_fh *fh) + + 从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也 + 将被调用。 + +void v4l2_fh_exit(struct v4l2_fh *fh) + + 清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。 + + +如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数： + +int v4l2_fh_open(struct file *filp) + + 分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的 + video_device 结构体中。 + +int v4l2_fh_release(struct file *filp) + + 从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理 + v4l2_fh 并释放空间。 + +这两个函数可以插入到 v4l2_file_operation 的 open() 和 release() +操作中。 + + +某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些 +工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备 +节点打开的唯一文件句柄。 + +int v4l2_fh_is_singular(struct v4l2_fh *fh) + + 如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。 + +int v4l2_fh_is_singular_file(struct file *filp) + + 功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。 + + +V4L2 事件机制 +----------- + +V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用 +v4l2_fh 才能支持 V4L2 事件机制。 + + +事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如 +一个控制 ID。如果未使用，则 ID 为 0。 + +当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个 +事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果 +一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。 + +但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的 +事件将被丢弃，并加入新事件。 + +此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和 +replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。 +replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期 +净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个 +kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷 +到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent +结构体时，它将被调用。 + +这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。 + + +关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于 +控制事件的 ctrls_replace() 和 ctrls_merge() 回调。 + +注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。 + +有用的函数： + +void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev) + + 将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。 + 其他域由 V4L2 填充。 + +int v4l2_event_subscribe(struct v4l2_fh *fh, + struct v4l2_event_subscription *sub, unsigned elems, + const struct v4l2_subscribed_event_ops *ops) + + video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能 + 产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。 + + elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型） + 填充默认值。 + + ops 参数允许驱动指定一系列回调： + * add: 当添加一个新监听者时调用（重复订阅同一个事件，此回调 + 仅被执行一次）。 + * del: 当一个监听者停止监听时调用。 + * replace: 用‘新’事件替换‘早期‘事件。 + * merge: 将‘早期‘事件合并到‘新’事件中。 + 这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。 + +int v4l2_event_unsubscribe(struct v4l2_fh *fh, + struct v4l2_event_subscription *sub) + + v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。 + 驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。 + + 特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊 + 情况下需要做此操作。 + +int v4l2_event_pending(struct v4l2_fh *fh) + + 返回未决事件的数量。有助于实现轮询（poll）操作。 + +事件通过 poll 系统调用传递到用户空间。驱动可用 +v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。 + +事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型 +编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为 +V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个 +类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件 +类型编号是‘class base + 1’。 + +V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动 +(drivers/media/video/omap3isp)中找到。 |