摄像头传感器驱动

本文档介绍 fw-AC79_AIoT_SDK 中摄像头传感器（Camera Sensor）驱动子系统的整体架构、实现机制与使用方式。该子系统位于 apps/common/camera/ 目录，为 ISP（图像信号处理）与上层视频应用（如 wifi_camera / wifi_ipc）提供统一的传感器配置、寄存器读写、复位与电源控制能力。

Purpose and Scope

本页覆盖以下内容：

apps/common/camera/ 下各传感器驱动（GC、BYD、BF 等系列）的目录结构与职责划分；
传感器驱动的核心实现机制：IIC 寄存器读写、上电/复位 IO 管理、分辨率与帧率配置、产测模式；
传感器驱动与 ISP 设备、视频应用层（spi_video.c、bt656_camera_get_yuv.c）之间的调用关系与数据流；
与传感器驱动相关的编译开关配置与扩展方式（新增传感器驱动）。

以下内容属于其他页面，不在本页展开：ISP 图像处理管线（色彩、AE/AWB 算法）、视频编码（JPEG/H.264）、网络传输与流媒体服务。如需了解视频应用层行为，请参阅视频采集相关页面。

概述

在 AC79NN AIoT SDK 的摄像头方案中，"摄像头传感器"（Sensor）是将光信号转为数字图像的 CMOS 器件，例如 GalaxyCore GC0308、BYD 系列等。SDK 为每一种传感器提供一个独立的驱动目录（如 gc0308_dvp/），每个驱动目录包含 .c 与 .h 文件。

传感器驱动承担三件事：

通过 IIC 总线读写传感器寄存器——配置传感器工作模式（分辨率、帧率、AEC/AWB 开关、色彩通道等）；
管理传感器的复位与电源 IO——上电时序、复位时序由驱动内静态数组 xxx_reset_io / xxx_power_io 描述；
向 ISP/视频应用暴露配置入口——驱动被 CONFIG_VIDEO_ENABLE 宏保护，视频应用通过设备句柄（camera_hdl）与 dev_ioctl 向传感器下发复位等命令。

典型使用场景：wifi_camera / wifi_ipc 应用启动时打开摄像头设备（camera_device_open），通过 CAMERA_SET_SENSOR_RESET 等 ioctl 命令复位传感器，随后传感器输出 BT656/SPI 数据给 ISP 处理，最终编码成视频流。

架构

flowchart TD
    subgraph sg_App["应用层 (apps/wifi_camera, apps/wifi_ipc)"]
        SPI_VIDEO["spi_video.c / bt656_camera_get_yuv.c"]
    end

    subgraph sg_Driver["摄像头传感器驱动 (apps/common/camera/)"]
        GC0308["gc0308_dvp/gc0308.c"]
        GC0307["gc0307_dvp/gc0307.c"]
        GC0310["gc0310_spi/gc0310.c"]
        BYD["byd20a6 / byd30a2 / byd3720 / byd3901 / byd3a03"]
        BF2013["bydBF2013_dvp/bf2013.c"]
    end

    subgraph sg_ISP["ISP 层 (asm/isp_dev.h)"]
        ISP_DEV["isp_dev 设备"]
    end

    subgraph sg_Bus["总线与硬件"]
        IIC["IIC 总线 (asm/iic.h / device/iic.h)"]
        SENSOR_HW["CMOS 传感器硬件"]
        GPIO["复位/电源 GPIO"]
    end

    SPI_VIDEO -->|"dev_ioctl(camera_hdl, CAMERA_SET_SENSOR_RESET)"| GC0308
    GC0308 -->|"dev_ioctl(iic, IIC_IOCTL_*)"| IIC
    GC0307 --> IIC
    GC0310 --> IIC
    BYD --> IIC
    BF2013 --> IIC
    IIC --> SENSOR_HW
    GC0308 -->|"reset_io / power_io"| GPIO
    GPIO --> SENSOR_HW
    SPI_VIDEO -->|"打开摄像头设备"| ISP_DEV
    SENSOR_HW -->|"BT656 / SPI 数据"| ISP_DEV

架构说明：

应用层：spi_video.c（wifi_camera 与 wifi_ipc 各有一份）与 bt656_camera_get_yuv.c 是传感器的使用者。它们持有摄像头设备句柄 camera_hdl，通过 dev_ioctl(camera_hdl, CAMERA_SET_SENSOR_RESET, 0) 复位传感器；在跨核场景下，还会通过 server_request(..., VIDEO_REQ_DEVICE_IOCTL, &req) 把 ioctl 请求转发给视频服务端。
传感器驱动层：每个传感器一个目录，驱动内部持有静态的 IIC 句柄（static void *iic）与复位/电源 IO 数组（static u8 gc0308_reset_io[2]），实现寄存器读写原语（wrGC0308Reg / rdGC0308Reg）与初始化序列（GC0308_config_SENSOR）。
ISP 层：传感器输出的 YUV 数据进入 ISP 设备（asm/isp_dev.h），ISP 负责后续图像处理；传感器驱动与 ISP 通过 CONFIG_VIDEO_IMAGE_W/H 等宏约定输出分辨率。
总线与硬件：寄存器访问走 IIC 总线（IIC_IOCTL_START / IIC_IOCTL_TX / IIC_IOCTL_RX / IIC_IOCTL_STOP 等 ioctl 命令），复位与电源由 GPIO 控制。

驱动文件均在 apps/common/camera/ 下，例如 gc0308.c 与 gc0308.h。

驱动目录与传感器型号

apps/common/camera/ 下每个子目录对应一个传感器驱动，命名规则为 <型号>_<接口>：

目录	传感器型号	数据接口	说明
`byd20a6/`	BYD20A6	DVP	BYD 系列
`byd30a2/`	BYD30A2	DVP	BYD 系列
`byd3720/`	BYD3720	DVP	BYD 系列
`byd3901/`	BYD3901	DVP	BYD 系列
`byd3a03/`	BYD3A03	DVP	BYD 系列
`bydBF2013_dvp/`	BF2013	DVP	BF 系列 DVP 接口
`gc0307_dvp/`	GC0307	DVP	GalaxyCore，30 万像素
`gc0308_dvp/`	GC0308	DVP	GalaxyCore，30 万像素
`gc0309_dvp/`	GC0309	DVP	GalaxyCore，30 万像素
`gc0310_spi/`	GC0310	SPI	GalaxyCore，SPI 接口（单线/多线）

每个驱动的 .h 文件通常只对外暴露极少量接口。以 GC0308 为例，头文件仅声明一个函数：

void set_rev_sensor_GC0308(u16 rev_flag);

Source: gc0308.h

set_rev_sensor_GC0308 用于设置传感器是否反向（rev 标志），对应摄像头安装方向不同时对画面做镜像/翻转处理。

设计意图：CAMERA_SET_SENSOR_RESET 属于摄像头设备（ISP 设备）的 ioctl 命令集合，传感器驱动被 ISP 设备框架挂载；应用层只依赖命令宏，不直接调用传感器驱动函数，保持了"设备模型 → 驱动"的松耦合结构。bt656_camera_get_yuv.c 中的 camera_device_open() / camera_device_close() 同样以设备打开/关闭的方式管理摄像头生命周期。

核心流程

传感器上电与初始化时序

sequenceDiagram
    participant App as 视频应用 (spi_video.c)
    participant Dev as 摄像头设备 (isp_dev / camera_hdl)
    participant Drv as 传感器驱动 (gc0308.c)
    participant IIC as IIC 总线
    participant Sen as CMOS 传感器

    App->>Dev: dev_ioctl(camera_hdl, CAMERA_SET_SENSOR_RESET, 0)
    Dev->>Drv: 触发 sensor reset
    Drv->>Sen: 拉低/拉高复位 IO (reset_io)
    App->>Dev: 打开设备/配置输出
    Dev->>Drv: GC0308_config_SENSOR(w, h, format, fps)
    Drv->>IIC: wrGC0308Reg(0xfe, 0x80) / (0xfe, 0x00) 切 page0
    IIC->>Sen: 写寄存器序列
    Drv->>IIC: 关闭 AEC/AWB → 写固定参数 → 打开 AWB
    Drv->>Drv: GC0308_test_mode() 产测分支
    Sen-->>App: 输出 BT656/SPI YUV 数据
    App->>App: 数据送入 ISP 编码

流程说明：

应用打开摄像头设备后，先通过 CAMERA_SET_SENSOR_RESET 复位传感器，保证传感器从确定状态开始工作；
驱动按"page 选择 → 关算法 → 写参数 → 开算法 → 设输出尺寸/帧率"的顺序写寄存器；
传感器开始输出图像数据（DVP/SPI/BT656），进入 ISP 处理；
应用在关闭时执行 camera_device_close()，释放设备与缓冲（yuv_buf 等）。

寄存器读写错误路径

flowchart TD
    Start([发起 IIC 读写]) --> Tx{"dev_ioctl 返回非0?"}
    Tx -->|"是 (失败)"| Log["printf iic write err!!! + 记录 __LINE__"]
    Log --> Stop["IIC_IOCTL_STOP 释放总线"]
    Tx -->|"否 (成功)"| Next["继续下一步时序"]
    Next --> Done([完成])
    Stop --> Done

设计意图：任何一步失败都立即打印错误并携带 __LINE__（便于定位到具体寄存器步骤），同时确保发送 STOP 释放 IIC 总线——这是避免传感器与主控总线互锁的关键。

使用示例

示例 1：产测模式（测试图案输出）

驱动在产测宏开启时，向寄存器 0x2e 写入 BIT(1)，使传感器输出测试图案，供产线自动检测：

static void GC0308_test_mode(void)
{
#ifdef CONFIG_AUTO_PRODUCTION_ENABLE
    int prodct_jpeg_test_get(void);
    if (prodct_jpeg_test_get()) {
        wrGC0308Reg(0x2e, BIT(1));
    }
#endif
}

Source: gc0308.c

示例 2：应用层复位传感器（本地设备）

if (spi_video_info.camera_hdl) {
    dev_ioctl(spi_video_info.camera_hdl, CAMERA_SET_SENSOR_RESET, 0);
    spi_video_info.state = SPI_VIDEO_OPEN;
}

Source: spi_video.c

示例 3：应用层复位传感器（跨核服务端转发）

req.rec.priv = (void *)CAMERA_SET_SENSOR_RESET; //镜头复位命令
err = server_request(spi_video_info.net_video_rec, VIDEO_REQ_DEVICE_IOCTL, &req);//请求镜头复位IOCTL

Source: spi_video.c

示例 4：摄像头设备开关（BT656 采集）

static int camera_device_open(void)
{ ... }

static int camera_device_close(void)
{ ... }

Sources:
bt656_camera_get_yuv.c
bt656_camera_get_yuv.c

bt656_camera_get_yuv.c 的打开流程还体现了硬件配置顺序：先打开摄像头设备，最后再配置 MSB 正反向与移位（因为 camera_device_open 可能重置这些配置），这解释了为什么 2/4bit 模式下硬件接收使能要放在最后一步。

配置选项

传感器驱动相关的编译期配置如下：

配置宏	类型	默认值	说明
`CONFIG_VIDEO_ENABLE`	宏开关	关闭	总开关，驱动整体代码在 `#ifdef CONFIG_VIDEO_ENABLE` 内编译
`CONFIG_VIDEO_IMAGE_W`	整数	平台配置	视频图像宽度；`> 640` 时 GC0308 输入按 640x480 处理
`CONFIG_VIDEO_IMAGE_H`	整数	平台配置	视频图像高度，与宽度配套决定输入分辨率
`CONFIG_INPUT_FPS`	整数	20	输入帧率；0 为自动，可固定 5/10/15/20/33（33 帧需关闭 ppbuf 并加大实时流内存）
`CONFIG_AUTO_PRODUCTION_ENABLE`	宏开关	关闭	产测模式，开启后驱动支持测试图案输出（寄存器 0x2e BIT(1)）
`CONFIG_SPI_ONE_LINE_ENABLE`	宏开关	关闭	SPI 单线模式；关闭时 2/4bit 硬件接收需最后配置 MSB 正反向与移位

以上默认值依据 gc0308.c 与 bt656_camera_get_yuv.c 中的用法归纳，具体默认值以各板级 app_config.h / cpu_config.h 为准。

API 参考

传感器驱动的对外 API 因型号而异，一般由 .h 文件暴露极少量函数。以 GC0308 为例：

`set_rev_sensor_GC0308(u16 rev_flag)`

设置传感器画面反向（镜像/翻转）标志。

参数：

rev_flag (u16)：非 0 表示启用反向，0 表示正常方向

返回： 无

说明： 头文件 gc0308.h 仅暴露此接口，其余函数（wrGC0308Reg、rdGC0308Reg、GC0308_config_SENSOR、GC0308_test_mode）均为文件内静态函数，属于驱动内部实现细节，不对外导出。

驱动内部关键函数（静态，供理解实现）

函数	签名	职责
`wrGC0308Reg`	`static unsigned char (unsigned char regID, unsigned char regDat)`	写单字节寄存器，返回 1 成功 / 0 失败
`rdGC0308Reg`	`static unsigned char (unsigned char regID, unsigned char *regDat)`	读单字节寄存器，结果写入 `regDat`
`GC0308_config_SENSOR`	`static void (u16 width, u16 height, u8 format, u8 frame_freq)`	按序列配置传感器寄存器，并回填宽高/格式/帧率
`GC0308_test_mode`	`static void (void)`	产测模式：开启时写测试图案寄存器
`GC0308_set_output_size`	`static s32 (u16 width, u16 height, u8 *freq)`	设置输出尺寸与帧频

应用层 ioctl 命令

命令	说明	调用位置
`CAMERA_SET_SENSOR_RESET`	复位传感器（镜头复位命令）	spi_video.c 经 `dev_ioctl` 或 `server_request` 下发

故障模式、边界情况与并发

IIC 通信失败：读写函数的每一步 dev_ioctl 都可能失败。驱动统一打印 iic write err!!! line : N（N 为代码行号）并发送 IIC_IOCTL_STOP 释放总线。失败时返回 0，调用方应检查返回值；传感器配置失败通常表现为无图像或图像异常。
总线互锁风险：若在读写中途异常退出而未发送 STOP，IIC 总线可能被传感器拉死。驱动的 exit 统一 STOP 设计正是为了防止该问题。
时序敏感：寄存器读写之间插入 delay(DELAY_TIME)（10ms），上电/复位时序依赖 reset_io/power_io 的拉高拉低顺序。修改时序或 IO 配置不当会导致传感器无法稳定出图。
配置顺序约束（边界情况）：BT656 采集在 2/4bit 模式下，硬件接收使能（MSB 正反向与移位配置）必须在 camera_device_open 之后进行，因为打开设备可能重置这些寄存器配置。
高帧率资源约束：33 帧输入需要关闭 ppbuf、加大实时流内存（cpu_config.h），否则内存/带宽不足会导致丢帧或编码失败。
并发/多核访问：跨核场景下应用不直接持有摄像头句柄，而是通过 server_request(VIDEO_REQ_DEVICE_IOCTL) 把复位等命令转发给视频服务端执行，避免多核并发直接操作 IIC 与 GPIO。传感器驱动本身是单实例、无锁设计，所有状态保存在文件级静态变量中。

性能与运维注意事项

寄存器读写带有 10ms 级延时，初始化序列通常包含数十条寄存器写入，因此传感器上电到出图存在可感知的延迟；产线/冷启动测试应把这段初始化时间计入时序预算。
每个传感器驱动是独立目录，SDK 通过编译宏选择实际编译进固件的驱动；未使用的驱动不会占用 IIC 与 GPIO 资源。
排查"无图像"问题时，建议按以下顺序验证：复位/电源 IO 是否与板级原理图一致 → IIC 地址（0x42/0x43）是否与器件手册一致 → 输入分辨率宏是否匹配传感器能力 → MSB 正反向/移位配置（BT656 场景）→ 帧率是否超过内存预算。

扩展点：新增传感器驱动

要接入一款新的 CMOS 传感器，参照现有目录模式：

在 apps/common/camera/ 下新建 <型号>_<接口>/ 目录，包含 <型号>.c 与 <型号>.h；
在 .c 中实现：静态 IIC 句柄与 reset_io/power_io 数组、wr/rd<型号>Reg 读写原语、<型号>_config_SENSOR 初始化序列、<型号>_test_mode 产测分支；
在 .h 中暴露方向/镜像控制函数（如 set_rev_sensor_<型号>）；
驱动代码用 #ifdef CONFIG_VIDEO_ENABLE 保护，并在板级配置中选择启用对应型号；
将复位/电源 IO 按板级原理图赋值，确认器件 IIC 地址与 page 选择序列（如 GC0308 的 0xfe 寄存器用法）正确。

说明：传感器驱动的具体注册方式（如何挂载到 ISP 设备框架、camera_hdl 的来源）涉及设备框架与 ISP 初始化代码，相关实现细节未在本页全部展开，可结合 ISP 设备（asm/isp_dev.h）与视频应用初始化代码进一步阅读。