跳转至
项目
版本
全文检索

host_uvc 快速入门

1. 概述与作用

本样例隶属 V4L2/USB 媒体采集域，定位为 UVC Host 模式采集工具：Hi3516CV610 开发板作为 USB 主机，接收 USB UVC 摄像头数据，并保存为文件（可选）。主要解决"Hi3516CV610 作为 USB Host 直接对接 UVC 摄像头并按指定格式/分辨率采集码流或 YUV"的问题。本样例不涉及MPP媒体接口调用。

专业名词与缩写：

  • UVC — USB Video Class，USB 视频类标准；UVC Host 即开发板作为 USB 主机
  • V4L2 — Video4Linux2，Linux 视频设备框架
  • MPLANE / single-plane — V4L2 多平面/单平面缓冲格式
  • YUYV / MJPEG / H264 / H265 / NV21 / NV12 — 视频像素/编码格式
  • DQBUF / QBUF / REQBUFS / STREAMON — V4L2 buffer ioctl
  • USB host mode — 通过 /proc/wing-usb/10300000.usb20drd/mode 切换 USB 为 Host

2. 执行准备

在编译本样例之前，请参照Hi3516CV610环境搭建指南和快速上手指南完成编译环境的搭建。

2.1 编译

进入样例目录执行 make 即可完成编译：

cd samples/mpp/host_uvc && make

编译成功之后，在当前目录下会生成一个sample_host_uvc的可执行文件，可以放社区支持的开发板上运行。

请参考samples/mpp/host_uvc/readme.txt说明查看更多注意事项。

2.2 加载 KO

UVC host 走内核驱动（uvcvideo.ko 通常内置），标准 MPP KO 非必需。

确认执行模式：执行 sample 前，需将设备设置为 host 模式（默认为 device 模式）。

echo host > /proc/wing-usb/10300000.usb20drd/mode

注意：路径为 /proc/wing-usb/10300000.usb20drd/mode，含 wing-usb 段，缺失会导致命令失败。

2.3 运行时依赖

在运行样例前，需要提前准备：

  • 硬件依赖：USB UVC 摄像头 + /dev/videoX 设备节点。缺设备时 open(/dev/videoX) 失败，打印 Cannot open device 并退出。

  • 指定运行时依赖的so库路径

MPP样例依赖的so库位于soc/libs/musl下，需要将该目录下的so库拷贝到开发板上（或将这些so库所在的目录挂载到开发板上），并指定运行时依赖库的环境变量，假设这些so库位于/mnt/libs/，执行如下命令：

```shell
export LD_LIBRARY_PATH=/mnt/libs/:$LD_LIBRARY_PATH
```

如果是使用社区默认提供的镜像，这些so库已经打包到文件系统中，烧录到单板上后位于/usr/lib目录下，该目录是系统默认搜索目录，不需要执行export LD_LIBRARY_PATH命令去指定。

  • 样例运行时候需要的资源文件

无输入文件依赖。

3. 支持的 Case 列表

命令调用

调用语法为选项式，非数字 case，因此介绍参数的含义。命令的调用语法如下：

./sample_host_uvc <device> [options]

选项说明：

选项 说明
-f, --format <format> 设置视频格式：H264 / H265 / MJPEG / YUYV / NV21 / NV12
-F, --file[=name] 写入文件名
-s, --size WxH 设置分辨率（如 1920x1080）
--enum-formats 枚举设备支持的格式
-h, --help 显示帮助信息

执行 ./sample_host_uvc 不带参数可查看完整帮助：

sample_uvc_usage: ./sample_host_uvc device [options]
supported options:
-f, --format format             set the video format
-F, --file[=name]               write file
-h, --help                      show help info
-s, --size WxH                  set the frame size (eg. 1920x1080)

inquire USB device format: ./sample_host_uvc /dev/video0 --enum-formats

example of setting USB device format:
    ./sample_host_uvc /dev/video0 -fH264  -s1920x1080 -Ftest.h264
    ./sample_host_uvc /dev/video0 -fH265  -s1920x1080 -Ftest.h265
    ./sample_host_uvc /dev/video0 -fMJPEG -s1920x1080 -Ftest.mjpg
    ./sample_host_uvc /dev/video0 -fYUYV  -s1920x1080 -Ftest.yuv
    ./sample_host_uvc /dev/video0 -fNV21  -s640x360   -Ftest.yuv
序号 调用示例 简述 备注
1 ./sample_host_uvc /dev/video0 --enum-formats 列出 USB 设备支持的格式 接入摄像头后第一步
2 ./sample_host_uvc /dev/video0 -fH264 -s1920x1080 -Ftest.h264 采集 H264 1080p 到 test.h264 需设备支持 H264
3 ./sample_host_uvc /dev/video0 -fH265 -s1920x1080 -Ftest.h265 采集 H265 1080p 需设备支持 H265
4 ./sample_host_uvc /dev/video0 -fMJPEG -s1920x1080 -Ftest.mjpg 采集 MJPEG 1080p 多数 UVC 摄像头支持
5 ./sample_host_uvc /dev/video0 -fYUYV -s1920x1080 -Ftest.yuv 采集 YUYV 1080p 带宽要求高
6 ./sample_host_uvc /dev/video0 -fNV21 -s640x360 -Ftest.yuv 采集 NV21 360p 需 NV21 内核补丁

默认 640x480 YUYV 25fps 不输出文件，保存文件需要保证当前目录的可用空间足够大，持续采集（nframes=-1）直到 SIGINT/SIGTERM 触发退出。

nframes 为采集帧数，-1 表示不限

查看摄像头支持的格式

执行 ./sample_host_uvc /dev/video0 --enum-formats 可查看设备支持的视频格式、分辨率与帧率。

示例输出（以 HT-UC400 摄像头为例）：

/home/uvc # ./sample_host_uvc /dev/video0 --enum-formats
Device /dev/video0 opened.
Device `HT-UC400: HT-UC400' on `usb-xhci-hcd.0.auto-1' (driver 'uvcvideo') supports video, capture, without mplanes.
- Available formats:
    Format 0: MJPEG (47504a4d)
    Type: Video capture (1)
    Name: Motion-JPEG
    Frame size: 320x240 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 640x480 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1280x720 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1920x1080 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)

    Format 1: YUYV (56595559)
    Type: Video capture (1)
    Name: YUYV 4:2:2
    Frame size: 320x240 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 640x480 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1280x720 (1/10, 1/5)
    Frame size: 1920x1080 (1/5)

    Format 2: H264 (34363248)
    Type: Video capture (1)
    Name: H.264
    Frame size: 320x240 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 640x480 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1280x720 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1920x1080 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)

    Format 3: H265 (35363248)
    Type: Video capture (1)
    Name: H.265
    Frame size: 320x240 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 640x480 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1280x720 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
    Frame size: 1920x1080 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)

执行结果验证

执行用例

选择一个设备支持的视频格式执行采集，例如：

/home/uvc # ./sample_host_uvc /dev/video0 -fMJPEG -s1920x1080 -Ftest.mjpg

正常输出示例（MJPEG 1080p）：

Device /dev/video0 opened.
Device `HT-UC400: HT-UC400' on `usb-xhci-hcd.0.auto-1' (driver 'uvcvideo') supports video, capture, without mplanes.
video format set: MJPEG (47504a4d) 1920x1080 (stride 0) field filed_none buffer size 2073600
video format: MJPEG (47504a4d) 1920x1080 (stride 0) field filed_none buffer size 2073600
1 buffers requested.
length: 2073600 offset: 0 timestamp type/source: monotonic/soe
Buffer 0/0 mapped
^C^Cmedia exit...

正常输出示例（YUYV 1080p）：

/home/uvc # ./sample_host_uvc /dev/video0 -fYUYV  -s1920x1080 -Ftest.yuv
Device /dev/video0 opened.
Device `HT-UC400: HT-UC400' on `usb-xhci-hcd.0.auto-1' (driver 'uvcvideo') supports video, capture, without mplanes.
video format set: YUYV (56595559) 1920x1080 (stride 3840) field filed_none buffer size 4147200
video format: YUYV (56595559) 1920x1080 (stride 3840) field filed_none buffer size 4147200
1 buffers requested.
length: 4147200 offset: 0 timestamp type/source: monotonic/soe
Buffer 0/0 mapped
^C^C^C^Cmedia exit...

输出文件

仅当指定 -F 时，通过 fopen(file_name, "w+") 与 fwrite 写入落盘文件；无 -F 时不写文件。

控制台日志

启动时：Device ... opened.、video format set: ...、Buffer N/N mapped。 停止时：media exit...。 持续采集至 Ctrl+C（SIGINT）触发 g_uvc_exit 退出。

正确性判断

  • ls -l test.h264 文件大小 ≈ frame_size × fps × duration。
  • ffplay / vlc 能正常播放 H264/H265 文件。
  • YUV 文件分辨率匹配 WxH（YUYV 一帧 = W×H×2 字节，如 1920x1080 = 4147200 字节）。
  • Ctrl+C 停止后正常打印 media exit...。
  • 错误情形：Unable to start streaming、media_send_data failed!、No frames captured.、Cannot open device。

4. 其他

常见问题说明

  1. sample可能会因系统内存不足被杀掉，可以通过增大OS内存和减小MMZ内存来解决，参考docs/04参考案例/调试调优/BSP/内存布局调整指南对内存大小进行调整。

  2. 内核默认不支持NV21，参考samples/mpp/host_uvc/readme.txt修改，并重新编译烧写内核；

  3. 拉取YUV数据流时，如果CPU占用率较高，可以在third_party/linux/linux-5.10.y/drivers/media/usb/uvc/uvc_video.c文件的前面添加如下一行，确保USB驱动分配使用的内存带Cache属性，然后编译烧写内核。

    #define CONFIG_DMA_NONCOHERENT