v4l2 编程接口 — driver

转自：http://c.chinaitlab.com/example/914870.html

    V4L2 驱动随着硬件的变化也越来越复杂，现在大部分设备有里面包含了多个IC, 在/dev目录下不仅要建立 V4L2 的节点，而且还需要建立如：DVB、ALSA、FB、I2C、input等设备节点。事实上 V4L2 驱动需要支持音频/视频的混音/编码/解码等IC所以比其他驱动都要复杂很多，通常这些IC通过 i2c 总线连接到主板，这些设备都统称为sub-devices.在很长的一段时间里 V4L2 被限制只能在 video_device 结构体里面创建，并且用video_buf 控制视频缓存，这意味着所有的驱动创建自己的实例都将连接到自己的sub-devices,这些工作通常很复杂并经常引起错误，许多常见的代码因为缺乏一个框架而无法重构。因此这个框架建立起了基本的机制，所有的驱动都需要和这个框架结合以便共用其中的函数。因此 V4L2  框架作了相应的优化：它有一个 v4l2_device 结构作为设备实例，一个v4l2_subdev 结构作为子设备实例，video_device 结构包含了v4l2_device 节点，以后将会有一个 v4l2_fh 的结构作为与文件句柄的实例。每个设备都采用 v4l2_device 结构来表示。非常简单的设备都可以申请这个结构，但通常会将这个结构嵌入一个更大的结构中。

    1、 video_device

    在 v4l2 中用 struct video_device 代表一个视频设备，该结构说明如下：

    [cpp]

    struct video_device

    {

    /* 设备操作合集 */

    const struct v4l2_file_operations *fops;

    /* sysfs节点 */

    struct device dev;      /* v4l device */

    struct cdev *cdev;      /* 字符设备节点 */

    /* Set either parent or v4l2_dev if your driver uses v4l2_device */

    struct device *parent;      /* 父设备 */

    struct v4l2_device *v4l2_dev;   /* v4l2_device parent */

    /* 设备信息 */

    char name[32];

    int vfl_type;

    /* 如果注册失败 minor 将被设置为 -1 */

    int minor;

    u16 num;

    /* 需要用位操作 flags */

    unsigned long flags;

    /* attribute to differentiate multiple indices on one physical device */

    int index;

    int debug;          /* Activates debug level*/

    /* Video standard vars */

    v4l2_std_id tvnorms;        /* Supported tv norms */

    v4l2_std_id current_norm;   /* Current tvnorm */

    /* 释放设备的回调函数 */

    void （*release）（struct video_device *vdev）；

    /* ioctl 回调函数 */

    const struct v4l2_ioctl_ops *ioctl_ops;

    };

    其中

    struct cdev {

    struct kobject kobj;    /* 内核对象 */

    struct module *owner;

    const struct file_operations *ops;  /* 设备操作合集 */

    struct list_head list;

    dev_t dev;

    unsigned int count;

    };

    struct v4l2_file_operations {

    struct module *owner;

    ssize_t （*read） （struct file *, char __user *, size_t, loff_t *）；        /* 读数据 */

    ssize_t （*write） （struct file *, const char __user *, size_t, loff_t *）； /* 写数据 */

    unsigned int （*poll） （struct file *, struct poll_table_struct *）；        /* 同步操作 */

    long （*ioctl） （struct file *, unsigned int, unsigned long）；              /* 特殊命令 */

    long （*unlocked_ioctl） （struct file *, unsigned int, unsigned long）；

    unsigned long （*get_unmapped_area） （struct file *, unsigned long,

    unsigned long, unsigned long, unsigned long）；

    int （*mmap） （struct file *, struct vm_area_struct *）；                    /* 内存映射 */

    int （*open） （struct file *）；                                             /* 打开设备 */

    int （*release） （struct file *）；                                          /* 释放设备 */

    };

视频设备在 linux 中作为字符设备出现，域 cdev 与 /dev/videox 节点关联，打开节点就相当于执行cdev 的 open 函数，cdev 的 ops 域即 file_operations 的一些接口在经过一定的参数过滤后最终都调用了video_device 的 fops 域即v4l2_file_operations的成员，所以在编写驱动程序的时候需要实现 v4l2_file_operations 的接口：其中 open 用于打开视频设备， read 接口用于读取视频数据，poll 接口用于视频流的同步，mmap 将视频设备的保存数据的内存空间的物理地址映射到用户空间，ioctl 用于向视频设备发送命令并查询相关信息（ioctl 一般设置为 v4l2 提供的 video_ioctl2 函数，并最终调用 video_device 的 ioctl_ops 域即 v4l2_ioctl_ops），通常需要实现的 ioctl 接口如下：

    [cpp]

    static const struct v4l2_ioctl_ops xxx_cam_ioctl_ops = {

    .vidioc_querycap         = vidioc_querycap,

    .vidioc_enum_input       = vidioc_enum_input,

    .vidioc_g_input          = vidioc_g_input,

    .vidioc_s_input          = vidioc_s_input,

    .vidioc_queryctrl        = vidioc_queryctrl,

    .vidioc_s_ctrl           = vidioc_s_ctrl,

    .vidioc_g_ctrl           = vidioc_g_ctrl,

    .vidioc_enum_fmt_vid_cap = vidioc_enum_fmt_vid_cap,

    .vidioc_try_fmt_vid_cap  = vidioc_try_fmt_vid_cap,

    .vidioc_g_fmt_vid_cap    = vidioc_g_fmt_vid_cap,

    .vidioc_s_fmt_vid_cap    = vidioc_s_fmt_vid_cap,

    .vidioc_reqbufs          = vidioc_reqbufs,

    .vidioc_querybuf         = vidioc_querybuf,

    .vidioc_qbuf             = vidioc_qbuf,

    .vidioc_dqbuf            = vidioc_dqbuf,

    .vidioc_streamon         = vidioc_streamon,

    .vidioc_streamoff        = vidioc_streamoff,

    .vidioc_default          = vidioc_default,

    };

    该结构各域的作用如上篇文章所述。video_device 通过 video_register_device 函数注册，函数原型如下：

    [cpp]

    /**

    *  video_register_device - 注册一个 v4l2 设备

    *  @vdev: video_device 结构

    *  @type: v4l2 设备的类型

    *  @nr:   从设备号（0 == /dev/video0, 1 == /dev/video1, -1 == first free）

    *

    *  注册代码将会根据注册设备的类型指派从设备号，如果没有合适的从设备号将会返回错误值。

    *

    *  通常有如下几种设备类型

    *

    *  %VFL_TYPE_GRABBER - 视频采集设备

    *

    *  %VFL_TYPE_VTX     - 图文电视设备

    *

    *  %VFL_TYPE_VBI     - 场消隐区解码设备（undecoded）

    *

    *  %VFL_TYPE_RADIO   - 无线设备

    */

    int video_register_device（struct video_device *vdev, int type, int nr）

    {

    return __video_register_device（vdev, type, nr, 1）；

    }

    EXPORT_SYMBOL（video_register_device）；

    该函数注册流程较简单：首先会根据设备类型确定在 /dev 目录下的节点名称以及从设备号的偏移和值，然后为 cdev 申请内存空间并注册，将 vdev->cdev->ops 设置为内核提供的 v4l2_fops,最后将 vdev->dev 注册到 sysfs 中。

    2、v4l2_subdev

    许多驱动需要与子设备通信，这些设备做的任务比较常见的是音视频处理、编解码等， 网络摄像头比较常见的子设备是传感器和摄像头控制器。为了提供一个统一的接口给这些子设备，内核将涉及到子设备控制的那部分（如 vidioc_s_ctrl、vidioc_s_frequency 等）独立了出来，用 struct v4l2_subdev 来表示以方便用户实现 v4l2 驱动程序：

    [cpp]

    struct v4l2_subdev {

    struct list_head list;              /* 链接至 v4l2_device */

    struct module *owner;

    u32 flags;

    struct v4l2_device *v4l2_dev;       /* 指向 v4l2_device */

    const struct v4l2_subdev_ops *ops;  /* subdev 操作合集 */

    /* name must be unique */

    char name[V4L2_SUBDEV_NAME_SIZE];

    /* can be used to group similar subdevs, value is driver-specific */

    u32 grp_id;

    /* 私有数据 */

    void *priv;

    };

    其中 list 域作为链表节点链接至 v4l2_dev 指向的  v4l2_device 结构中，这个结构中最重要的成员就是 struct v4l2_subdev_ops *ops,该域包含了 v4l2 设备支持的所有操作，定义如下：

    [cpp]

    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;  /* 视频操作合集 */

    };

    v4l2_subdev_core_ops 包含的操作合集是各种类型设备通用的：

    [cpp]

    struct v4l2_subdev_core_ops {

    int （*g_chip_ident）（struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip）；  /* 获取设备id */

    int （*log_status）（struct v4l2_subdev *sd）；                                      /* 状态消息 */

    int （*s_config）（struct v4l2_subdev *sd, int irq, void *platform_data）；          /* 设置配置信息 */

    int （*init）（struct v4l2_subdev *sd, u32 val）；                                   /* 初始化设备 */

    int （*load_fw）（struct v4l2_subdev *sd）；                                         /* 加载firmware */

    int （*reset）（struct v4l2_subdev *sd, u32 val）；                                  /* 重置设备 */

    int （*s_gpio）（struct v4l2_subdev *sd, u32 val）；                                 /* 设置gpio */

    int （*queryctrl）（struct v4l2_subdev *sd, struct v4l2_queryctrl *qc）；            /* 查询设备支持的操作 */

    int （*g_ctrl）（struct v4l2_subdev *sd, struct v4l2_control *ctrl）；               /* 获取当前命令值 */

    int （*s_ctrl）（struct v4l2_subdev *sd, struct v4l2_control *ctrl）；               /* 设置当前命令值 */

    int （*g_ext_ctrls）（struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls）；    /* 获取外置命令值 */

    int （*s_ext_ctrls）（struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls）；    /* 设置外置命令值 */

    int （*try_ext_ctrls）（struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls）；

    int （*querymenu）（struct v4l2_subdev *sd, struct v4l2_querymenu *qm）；            /* 查询操作菜单 */

    int （*s_std）（struct v4l2_subdev *sd, v4l2_std_id norm）；                         /* 设置数据标准 */

    long （*ioctl）（struct v4l2_subdev *sd, unsigned int cmd, void *arg）；             /* 处理特殊命令 */

    #ifdef CONFIG_VIDEO_ADV_DEBUG

    int （*g_register）（struct v4l2_subdev *sd, struct v4l2_dbg_register *reg）；       /* 获取寄存器值 */

    int （*s_register）（struct v4l2_subdev *sd, struct v4l2_dbg_register *reg）；       /* 设置寄存器值 */

    #endif

    };

    v4l2_subdev_tuner_ops 包含的操作合集则是调谐器独有的：

    [cpp]

    struct v4l2_subdev_tuner_ops {

    int （*s_mode）（struct v4l2_subdev *sd, enum v4l2_tuner_type）；               /* 设置调谐器模式 */

    int （*s_radio）（struct v4l2_subdev *sd）；                                    /* 设置无线设备信息 */

    int （*s_frequency）（struct v4l2_subdev *sd, struct v4l2_frequency *freq）；   /* 设置频率 */

    int （*g_frequency）（struct v4l2_subdev *sd, struct v4l2_frequency *freq）；   /* 获取频率 */

    int （*g_tuner）（struct v4l2_subdev *sd, struct v4l2_tuner *vt）；             /* 获取调谐器信息 */

    int （*s_tuner）（struct v4l2_subdev *sd, struct v4l2_tuner *vt）；             /* 设置调谐器信息 */

    int （*g_modulator）（struct v4l2_subdev *sd, struct v4l2_modulator *vm）；     /* 获取调幅器信息 */

    int （*s_modulator）（struct v4l2_subdev *sd, struct v4l2_modulator *vm）；     /* 设置调幅器信息 */

    int （*s_type_addr）（struct v4l2_subdev *sd, struct tuner_setup *type）；      /* 安装调谐器 */

    int （*s_config）（struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config）；   /* 设置配置信息 */

    int （*s_standby）（struct v4l2_subdev *sd）；                                  /* 设置标准 */

    };

    v4l2_subdev_audio_ops 包含的操作合集则是音频部分独有的：

    [cpp] view plaincopy

    struct v4l2_subdev_audio_ops {

    int （*s_clock_freq）（struct v4l2_subdev *sd, u32 freq）；       /* 设置音频设备频率 */

    int （*s_i2s_clock_freq）（struct v4l2_subdev *sd, u32 freq）；   /* 设置i2s总线频率 */

    int （*s_routing）（struct v4l2_subdev *sd, u32 input, u32 output, u32 config）；   /* 设置音频路由 */

    };

    v4l2_subdev_video_ops 包含的操作合集则是视频部分独有的：

    [cpp]

    struct v4l2_subdev_video_ops {

    int （*s_routing）（struct v4l2_subdev *sd, u32 input, u32 output, u32 config）；             /* 设置视频路由 */

    int （*s_crystal_freq）（struct v4l2_subdev *sd, u32 freq, u32 flags）；                      /* 设置设备频率 */

    int （*decode_vbi_line）（struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line）；   /* 消隐区信息解码 */

    int （*s_vbi_data）（struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data）；  /* 设置消隐区数据 */

    int （*g_vbi_data）（struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data）；        /* 获取消隐区数据 */

    int （*g_sliced_vbi_cap）（struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap）；

    int （*s_std_output）（struct v4l2_subdev *sd, v4l2_std_id std）；                            /* 设置标准输出 */

    int （*querystd）（struct v4l2_subdev *sd, v4l2_std_id *std）；                               /* 查询标准 */

    int （*g_input_status）（struct v4l2_subdev *sd, u32 *status）；                              /* 获取输入状态 */

    int （*s_stream）（struct v4l2_subdev *sd, int enable）；                                     /* 设置数据流 */

    int （*enum_fmt）（struct v4l2_subdev *sd, struct v4l2_fmtdesc *fmtdesc）；                   /* 枚举视频格式 */

    int （*g_fmt）（struct v4l2_subdev *sd, struct v4l2_format *fmt）；                           /* 获取视频格式 */

    int （*try_fmt）（struct v4l2_subdev *sd, struct v4l2_format *fmt）；                         /* 尝试设置视频格式 */

    int （*s_fmt）（struct v4l2_subdev *sd, struct v4l2_format *fmt）；                           /* 设置视频格式 */

    int （*cropcap）（struct v4l2_subdev *sd, struct v4l2_cropcap *cc）；                         /* 视频剪辑功能 */

    int （*g_crop）（struct v4l2_subdev *sd, struct v4l2_crop *crop）；                           /* 获取剪辑功能 */

    int （*s_crop）（struct v4l2_subdev *sd, struct v4l2_crop *crop）；                           /* 设置剪辑功能 */

    int （*g_parm）（struct v4l2_subdev *sd, struct v4l2_streamparm*param）；                    /* 获取参数 */

    int （*s_parm）（struct v4l2_subdev *sd, struct v4l2_streamparm*param）；                    /* 设置参数 */

    int （*enum_framesizes）（struct v4l2_subdev *sd, struct v4l2_frmsizeenum *fsize）；          /* 枚举帧大小 */

    int （*enum_frameintervals）（struct v4l2_subdev *sd, struct v4l2_frmivalenum *fival）；      /* 枚举帧间隔 */

    };

    因为 v4l2 设备一般用 i2c 总线通信，所以注册函数需要提供 i2c_client,函数原型如下：

    [cpp]

    /**

    *  v4l2_i2c_subdev_init - 注册一个 v4l2_subdev

    *  @sd: v4l2_subdev 结构

    *  @client: 通信用的i2c设备

    *  @ops: v4l2_subdev_ops 操作合集

    */

    void v4l2_i2c_subdev_init（struct v4l2_subdev *sd, struct i2c_client *client, const struct v4l2_subdev_ops *ops）

    当 video_device 中的接口需要调用 v4l2_subdev 的成员函数时一般采用如下宏定义：

    [cpp]

    /* 调用成员函数之前需要先检查成员函数是否被设置

    *  v4l2_subdev_call - 调用 v4l2_subdev 成员函数

    *  @sd: v4l2_subdev 结构

    *  @o:  v4l2_subdev_ops 成员名称

    *  @f:  v4l2_subdev 成员函数

    *  @args:  v4l2_subdev 成员函数的参数

    使用示例： err = v4l2_subdev_call（sd, core, g_chip_ident, &chip）；

    */

    #define v4l2_subdev_call（sd, o, f, args…）             \

    （！（sd） ? -ENODEV : （（（sd） && （sd）->ops->o && （sd）->ops->o->f） ?  \

    （sd）->ops->o->f（（sd） , ##args） : -ENOIOCTLCMD））