V4L2 (Video4Linux2) 서브시스템

V4L2 서브시스템을 카메라 입력부터 코덱 처리와 출력까지 이어지는 미디어 파이프라인(Pipeline) 관점에서 심층 분석합니다. V4L2 ioctl 계약과 상태 머신, videobuf2 큐 모델과 DMA 버퍼(Buffer) 수명주기, Media Controller 그래프와 서브디바이스 링크, 센서·ISP·M2M 코덱 통합, UVC 및 Device Tree 바인딩 패턴, 포맷 협상과 프레임 동기화, gstreamer/v4l2-ctl/media-ctl 기반 검증·디버깅(Debugging) 절차까지 실전 영상 장치 드라이버(Device Driver) 개발에 필요한 핵심을 다룹니다.

V4L2 개요

Video4Linux2(V4L2)는 Linux 커널의 비디오 캡처/출력 프레임워크입니다. 원래 Video4Linux(V4L) API가 커널 2.1에서 도입되었으나, 설계상 한계로 커널 2.5에서 V4L2로 전면 재설계되었습니다. V4L2는 웹캠, TV 튜너(Tuner), 하드웨어 코덱(Codec), ISP(Image Signal Processor) 등 모든 비디오 관련 디바이스를 통합 관리합니다.

V4L2의 설계 철학은 다양한 하드웨어를 단일 사용자 공간(User Space) API로 추상화하는 것입니다. 단순한 USB 웹캠부터 복잡한 SoC 카메라 파이프라인, 하드웨어 비디오 코덱까지 같은 ioctl 인터페이스로 제어할 수 있습니다.

V4L2 서브시스템은 Linux 미디어 생태계에서 중심적 역할을 합니다. 웹 회의, 보안 카메라, 자율 주행(Autonomous Driving), 의료 영상(Medical Imaging), 드론(Drone), 산업 검사 등 다양한 영역에서 활용됩니다. 최근에는 AI/ML 추론(Inference) 가속기와의 통합도 진행되고 있어, 카메라 입력부터 추론 출력까지 제로카피 파이프라인을 구성하는 사례가 늘고 있습니다.

이를 위해 V4L2는 다음과 같은 핵심 추상화 계층을 제공합니다:

• 디바이스 모델 — v4l2_device / video_device / v4l2_subdev 계층 구조
• 버퍼 관리 — videobuf2(vb2) 프레임워크가 DMA 버퍼 할당/매핑/큐잉을 통합 처리
• 미디어 토폴로지 — Media Controller가 하드웨어 블록 간 연결 그래프를 유저스페이스에 노출
• 컨트롤 프레임워크 — 밝기/대비/노출 등 파라미터를 타입 안전(Type-safe)하게 관리
• 포맷 협상(Format Negotiation) — FourCC 기반 픽셀 포맷과 미디어 버스(Bus) 코드로 데이터 형식 합의

V4L2 진화 이력

디바이스 유형

V4L2는 여러 유형의 디바이스 노드(Device Node)를 생성합니다:

커널 소스 구조

V4L2와 DRM/KMS 비교

V4L2와 DRM(Direct Rendering Manager)/KMS(Kernel Mode Setting)는 모두 미디어 데이터를 다루지만 역할이 다릅니다:

V4L2 핵심 기능 특징

V4L2는 단순한 웹캠 API를 넘어, 임베디드·자동차·산업용 영상 시스템을 위한 완전한 미디어 프레임워크입니다. 다음은 V4L2가 제공하는 핵심 기능과 각 기능이 해결하는 문제를 정리한 것입니다:

주요 지원 하드웨어 및 드라이버

V4L2 서브시스템은 이미지 센서, SoC ISP, 하드웨어 코덱, USB 카메라, PCIe 캡처 카드, HDMI 브릿지, TV 튜너 등 폭넓은 하드웨어를 지원합니다. 이 섹션에서는 메인라인 커널에 포함된 주요 드라이버를 카테고리별로 정리합니다.

이미지 센서 드라이버

V4L2 I2C 서브디바이스 드라이버로 구현된 주요 이미지 센서입니다. 대부분 drivers/media/i2c/ 경로에 위치합니다:

SoC 카메라/ISP 플랫폼 드라이버

SoC에 내장된 카메라 인터페이스 및 ISP(Image Signal Processor) 드라이버입니다. 대부분 drivers/media/platform/ 하위에 위치합니다:

하드웨어 비디오 코덱 드라이버

하드웨어 비디오 인코더/디코더는 V4L2 M2M(Memory-to-Memory) 프레임워크를 사용합니다. 상세 동작은 V4L2 M2M 섹션을 참조하세요. 아래는 주요 코덱 드라이버의 코덱 지원 매트릭스입니다:

E = 인코딩, D = 디코딩, E/D = 인코딩+디코딩 모두 지원

USB 비디오 디바이스

UVC(USB Video Class) 호환 디바이스는 커널의 uvcvideo 드라이버 하나로 모두 지원됩니다. 별도 드라이버 설치가 필요 없으며, 장치를 연결하면 자동으로 /dev/videoN이 생성됩니다. 상세 UVC 아키텍처는 UVC 섹션을 참조하세요.

PCIe 캡처 카드

PCIe 기반 비디오 캡처 카드는 아날로그/디지털 비디오 입력을 처리합니다:

HDMI/비디오 브릿지 IC 드라이버

HDMI 수신기, 아날로그-디지털 변환기, GMSL 디시리얼라이저(Deserializer) 등 비디오 브릿지 IC는 V4L2 서브디바이스로 구현됩니다:

TV 튜너 및 SDR

V4L2는 역사적으로 TV 튜너 지원에서 시작되었습니다. 아날로그/디지털 TV와 SDR(Software Defined Radio)을 포함합니다:

특수 V4L2 디바이스

일반적인 카메라/코덱 외에도 V4L2 프레임워크를 활용하는 특수 디바이스가 있습니다:

V4L2 프레임워크 아키텍처

V4L2 프레임워크는 계층적 구조로 설계되어 있습니다. 최상위에 v4l2_device가 있고, 그 아래 하나 이상의 video_device와 v4l2_subdev가 연결됩니다. 이 구조는 하나의 물리 디바이스가 여러 비디오 노드(캡처, 출력, 메타데이터)와 여러 서브디바이스(센서, ISP, CSI 리시버)를 가질 수 있는 현실을 반영합니다.

위 다이어그램에서 핵심 관계를 정리하면:

• v4l2_device — 물리 디바이스당 1개 생성. 모든 하위 요소의 부모 역할
• video_device — 유저스페이스에 노출되는 /dev/videoN. 하나의 v4l2_device에 여러 개 등록 가능
• v4l2_subdev — 파이프라인 내 개별 하드웨어 블록 (센서, ISP 등). v4l2_device에 등록
• vb2_queue — 각 video_device에 연결되어 DMA 버퍼 큐잉 관리
• v4l2_ctrl_handler — video_device 또는 v4l2_subdev에 연결되어 컨트롤 관리
• media_device — 선택적으로 연결. 복잡한 파이프라인의 토폴로지를 유저스페이스에 노출

v4l2_device 구조체

v4l2_device는 V4L2 드라이버의 최상위 컨테이너(Container)입니다. 하나의 물리 디바이스에 대해 하나의 인스턴스를 생성하며, 산하의 모든 video_device와 v4l2_subdev를 관리합니다.

/* include/media/v4l2-device.h */
struct v4l2_device {
    struct device          *dev;          /* 부모 struct device */
    struct media_device    *mdev;         /* Media Controller (선택) */
    struct list_head        subdevs;      /* v4l2_subdev 리스트 */
    struct v4l2_ctrl_handler *ctrl_handler; /* 디바이스 레벨 컨트롤 */
    char                    name[36];    /* 드라이버 이름 */
    void                    (*notify)(struct v4l2_subdev *, unsigned, void *);
    struct mutex            lock;         /* 직렬화 */
    ...
};

/* 등록/해제 */
int  v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
void v4l2_device_unregister(struct v4l2_device *v4l2_dev);

video_device 구조체

video_device는 유저스페이스에 노출되는 /dev/videoN 디바이스 노드를 나타냅니다. video_register_device()로 등록하면 캐릭터 디바이스가 생성됩니다.

/* include/media/v4l2-dev.h */
struct video_device {
    const struct v4l2_file_operations *fops;
    const struct v4l2_ioctl_ops      *ioctl_ops;
    struct v4l2_device              *v4l2_dev;
    struct vb2_queue               *queue;       /* vb2 큐 연결 */
    struct v4l2_ctrl_handler       *ctrl_handler;
    struct mutex                   *lock;
    u32                              device_caps; /* V4L2_CAP_* */
    enum vfl_devnode_type            vfl_type;
    int                              minor;
    char                             name[32];
    ...
};

/* 등록: type은 VFL_TYPE_VIDEO 등 */
int video_register_device(struct video_device *vdev,
                         enum vfl_devnode_type type, int nr);
void video_unregister_device(struct video_device *vdev);

ioctl 디스패치(Dispatch) 메커니즘

V4L2의 ioctl 처리 흐름을 이해하면 드라이버 디버깅에 도움이 됩니다:

유저스페이스 ioctl() 호출 경로:

1. sys_ioctl() → vfs_ioctl()
2. video_device->fops->unlocked_ioctl = video_ioctl2
3. video_ioctl2() → video_usercopy() → __video_do_ioctl()
4. __video_do_ioctl() → v4l2_ioctl_ops의 해당 콜백

video_ioctl2의 역할:

• 유저스페이스 ↔ 커널 데이터 복사 (copy_from_user/copy_to_user)
• video_device.lock 기반 직렬화(Serialization)
• 입력 검증 (버퍼 타입, 인덱스 범위 등)
• v4l2_fh 기반 우선순위(Priority) 확인

v4l2_fh (파일 핸들)

v4l2_fh는 유저스페이스의 open() 호출마다 생성되는 per-open 핸들입니다. 이벤트 구독, 우선순위 관리 등에 사용됩니다.

struct v4l2_fh {
    struct list_head         list;       /* video_device의 fh_list에 연결 */
    struct video_device     *vdev;
    struct v4l2_ctrl_handler *ctrl_handler;
    enum v4l2_priority       prio;       /* 우선순위 */
    struct v4l2_events      *events;     /* 이벤트 큐 */
    ...
};

/* open/close 콜백에서 사용 */
void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
void v4l2_fh_add(struct v4l2_fh *fh);
void v4l2_fh_del(struct v4l2_fh *fh);
void v4l2_fh_exit(struct v4l2_fh *fh);

ioctl 디스패치 내부 동작

V4L2 코어의 ioctl 처리는 v4l2-ioctl.c에 정의된 v4l2_ioctls[] 디스패치 테이블(Dispatch Table)을 기반으로 동작합니다. 각 ioctl 번호(_IOC_NR)를 배열 인덱스로 사용하여 O(1)으로 핸들러를 찾습니다:

/* drivers/media/v4l2-core/v4l2-ioctl.c — 디스패치 경로 */

/* 1. 유저스페이스 ioctl() 호출 → 커널 진입 */
/*    video_device->fops->unlocked_ioctl = video_ioctl2 */

long video_ioctl2(struct file *file, unsigned int cmd, unsigned long arg)
{
    /* 2. 유저 메모리 ↔ 커널 버퍼 복사 처리 */
    return video_usercopy(file, cmd, arg, __video_do_ioctl);
}

static long __video_do_ioctl(struct file *file, unsigned int cmd, void *arg)
{
    /* 3. v4l2_ioctls[] 테이블에서 핸들러 검색 */
    const struct v4l2_ioctl_info *info = &v4l2_ioctls[_IOC_NR(cmd)];

    /* 4. valid_ioctls 비트맵 확인 — 드라이버가 구현하지 않은 ioctl 거부 */
    if (!test_bit(_IOC_NR(cmd), vfd->valid_ioctls))
        return -ENOTTY;

    /* 5. 핸들러 호출 — info->func가 실제 v4l2_ioctl_ops 콜백으로 전달 */
    return info->func(ops, file, fh, arg);
}

valid_ioctls 비트맵(Bitmap)은 video_register_device() 시점에 드라이버가 제공한 v4l2_ioctl_ops의 콜백 존재 여부를 검사하여 자동으로 설정됩니다. 유저스페이스의 VIDIOC_QUERYCAP이 반환하는 capabilities 플래그도 이 비트맵에 기반합니다.

vb2 상태 머신(State Machine) 구현 상세

videobuf2는 버퍼와 큐 각각에 독립적인 상태 머신을 유지합니다. 내부 구현의 핵심은 queued_list에서 드라이버로 버퍼를 전달하는 __enqueue_in_driver() 호출입니다:

큐 수준의 상태 전이는 다음과 같습니다:

Media Pipeline 유효성 검증

media_pipeline_start()는 스트리밍 시작 전에 파이프라인 전체의 유효성을 검증합니다. 비디오 노드에서 시작하여 그래프를 역방향으로 탐색하며 모든 엔터티(Entity)의 링크 상태를 확인합니다:

/* 스트리밍 시작 시 파이프라인 검증 패턴 */
static int my_start_streaming(struct vb2_queue *q, unsigned int count)
{
    struct my_device *dev = vb2_get_drv_priv(q);
    int ret;

    /* 파이프라인 시작 — 그래프 탐색 + 유효성 검증 */
    ret = media_pipeline_start(&dev->vdev.entity, &dev->pipe);
    if (ret) {
        /* 링크 비활성화 또는 포맷 불일치 시 -EPIPE 반환 */
        dev_err(dev->dev, "pipeline validation failed: %d\n", ret);
        return ret;
    }

    /* 파이프라인의 모든 서브디바이스에 s_stream(1) 전파 */
    ret = v4l2_subdev_call(dev->sensor, video, s_stream, 1);
    if (ret) {
        media_pipeline_stop(&dev->vdev.entity);
        return ret;
    }
    return 0;
}

static void my_stop_streaming(struct vb2_queue *q)
{
    struct my_device *dev = vb2_get_drv_priv(q);

    v4l2_subdev_call(dev->sensor, video, s_stream, 0);
    media_pipeline_stop(&dev->vdev.entity);
    /* 모든 버퍼 반환 — 필수! */
    return_all_buffers(dev, VB2_BUF_STATE_ERROR);
}

media_pipeline_start() 내부에서는 streaming_count를 증가시켜 파이프라인 활성 중 토폴로지 변경(MEDIA_IOC_SETUP_LINK)을 방지합니다. 이미 스트리밍 중인 엔터티가 있으면 해당 파이프라인에 합류(join)합니다.

서브디바이스 상태 관리와 포맷 전파

커널 6.3부터 도입된 v4l2_subdev_state는 서브디바이스의 per-pad 포맷과 셀렉션(Selection) 정보를 체계적으로 관리합니다. active state와 try state를 분리하여 하드웨어에 영향을 주지 않고 포맷을 검증할 수 있습니다:

/* 서브디바이스 set_fmt 구현 패턴 (active state 사용) */
static int my_subdev_set_fmt(struct v4l2_subdev *sd,
                              struct v4l2_subdev_state *state,
                              struct v4l2_subdev_format *fmt)
{
    struct v4l2_mbus_framefmt *framefmt;

    /* state에서 해당 패드의 포맷 슬롯 참조 */
    framefmt = v4l2_subdev_state_get_format(state, fmt->pad);

    /* 하드웨어 제약 조건에 맞게 조정 */
    fmt->format.width = clamp(fmt->format.width, 64U, 3840U);
    fmt->format.height = clamp(fmt->format.height, 64U, 2160U);

    /* state에 저장 (active면 하드웨어 반영, try면 검증만) */
    *framefmt = fmt->format;

    /* source 패드라면 연결된 sink 패드로 포맷 전파 */
    if (fmt->pad == MY_PAD_SOURCE) {
        struct v4l2_mbus_framefmt *sink_fmt;
        sink_fmt = v4l2_subdev_state_get_format(state, MY_PAD_SINK);
        /* sink 패드 포맷도 함께 업데이트 */
        sink_fmt->width = fmt->format.width;
        sink_fmt->height = fmt->format.height;
    }

    return 0;
}

/* 동시성 제어 — state 락 사용 */
struct v4l2_subdev_state *state;
state = v4l2_subdev_lock_and_get_active_state(sd);
/* ... state 접근 ... */
v4l2_subdev_unlock_state(state);

포맷 전파(Format Propagation)는 파이프라인에서 source 패드의 포맷 변경이 연결된 다음 엔터티의 sink 패드로 자동 전파되는 메커니즘입니다. media-ctl로 포맷을 설정할 때 센서 출력 → CSI-2 입력 → CSI-2 출력 → ISP 입력 순서로 포맷을 전파해야 합니다.

videobuf2 (vb2) 버퍼 관리

videobuf2(vb2)는 V4L2의 핵심 버퍼 관리 프레임워크입니다. DMA 버퍼 할당, 유저스페이스 매핑, 스트리밍 큐 관리를 담당합니다. 드라이버는 직접 버퍼를 관리할 필요 없이 vb2 콜백(Callback)만 구현하면 됩니다.

vb2 버퍼 수명주기(Lifecycle)

vb2 버퍼는 엄격한 상태 머신(State Machine)을 따릅니다. 각 버퍼는 다음 상태 중 하나에 있습니다:

버퍼 큐 상태 전이 사이클

실제 스트리밍에서 버퍼는 유저스페이스와 드라이버 사이를 순환합니다. VIDIOC_QBUF로 제출된 버퍼는 하드웨어 DMA가 완료되면 VIDIOC_DQBUF로 반환되고, 다시 큐에 제출되는 사이클을 반복합니다:

vb2_queue 구조체와 초기화

/* include/media/videobuf2-core.h */
struct vb2_queue {
    unsigned int              type;           /* V4L2_BUF_TYPE_* */
    enum vb2_io_modes         io_modes;       /* VB2_MMAP | VB2_USERPTR | VB2_DMABUF */
    const struct vb2_ops     *ops;            /* 드라이버 콜백 */
    const struct vb2_mem_ops *mem_ops;        /* 메모리 할당자 */
    struct mutex             *lock;           /* 직렬화 lock */
    unsigned int              min_queued_buffers;
    u32                       timestamp_flags;
    struct device            *dev;            /* DMA 용 디바이스 */
    ...
};

/* 초기화 예제 */
static int my_queue_init(struct my_device *mydev)
{
    struct vb2_queue *q = &mydev->vb_queue;

    q->type             = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    q->io_modes         = VB2_MMAP | VB2_DMABUF;
    q->ops              = &my_vb2_ops;
    q->mem_ops          = &vb2_dma_contig_memops;
    q->drv_priv         = mydev;
    q->buf_struct_size  = sizeof(struct my_buffer);
    q->timestamp_flags  = V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC;
    q->lock             = &mydev->mutex;
    q->dev              = mydev->dev;

    return vb2_queue_init(q);
}

vb2_buffer / vb2_v4l2_buffer

개별 버퍼는 vb2_buffer로 관리됩니다. V4L2 드라이버는 이를 감싸는 vb2_v4l2_buffer를 사용하며, 드라이버 고유 구조체에 임베딩하는 패턴이 일반적입니다.

/* 드라이버 고유 버퍼 구조체 — 임베딩 패턴 */
struct my_buffer {
    struct vb2_v4l2_buffer  vb;      /* 반드시 첫 번째 멤버 */
    struct list_head        list;    /* 드라이버 내부 큐 */
    dma_addr_t              paddr;   /* DMA 물리 주소 */
};

/* container_of로 변환 */
static inline struct my_buffer *to_my_buffer(struct vb2_v4l2_buffer *vbuf)
{
    return container_of(vbuf, struct my_buffer, vb);
}

메모리 타입 비교

vb2 메모리 할당자(Allocator) 비교

vb2는 세 가지 메모리 할당자를 제공합니다. 드라이버의 DMA 요구사항에 따라 선택합니다:

/* DMA scatter-gather 할당자 사용 예 — IOMMU 환경 */
static int my_queue_init_sg(struct my_device *mydev)
{
    struct vb2_queue *q = &mydev->vb_queue;

    q->type             = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    q->io_modes         = VB2_MMAP | VB2_DMABUF;
    q->ops              = &my_vb2_ops;
    q->mem_ops          = &vb2_dma_sg_memops;  /* SG 할당자 */
    q->drv_priv         = mydev;
    q->buf_struct_size  = sizeof(struct my_buffer);
    q->timestamp_flags  = V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC;
    q->lock             = &mydev->mutex;
    q->dev              = mydev->dev;
    q->gfp_flags        = GFP_DMA32;  /* 32-bit DMA 주소 제한 시 */

    return vb2_queue_init(q);
}

/* SG 버퍼에서 DMA 주소 가져오기 */
static void my_buf_queue_sg(struct vb2_buffer *vb)
{
    struct sg_table *sgt = vb2_dma_sg_plane_desc(vb, 0);
    /* sgt->sgl, sgt->nents 로 하드웨어 SG DMA 프로그래밍 */
}

DMA-BUF 버퍼 공유 패턴

V4L2 캡처 버퍼를 GPU/디스플레이와 제로카피로 공유하는 대표적 패턴:

/* 패턴 1: V4L2 MMAP → EXPBUF → DRM import */
/* V4L2 측: MMAP 버퍼를 DMA-BUF fd로 내보내기 */
struct v4l2_exportbuffer expbuf = {
    .type  = V4L2_BUF_TYPE_VIDEO_CAPTURE,
    .index = buf_index,
    .flags = O_RDONLY,
};
ioctl(v4l2_fd, VIDIOC_EXPBUF, &expbuf);
int dmabuf_fd = expbuf.fd;  /* 다른 디바이스에 전달 가능 */

/* DRM 측: DMA-BUF fd로 GEM 핸들 생성 (제로카피) */
struct drm_prime_handle prime = { .fd = dmabuf_fd };
ioctl(drm_fd, DRM_IOCTL_PRIME_FD_TO_HANDLE, &prime);

/* 패턴 2: 외부 DMA-BUF → V4L2 DMABUF import */
/* V4L2 측: 외부 DMA-BUF fd를 캡처 버퍼로 사용 */
struct v4l2_buffer buf = {
    .type   = V4L2_BUF_TYPE_VIDEO_CAPTURE,
    .memory = V4L2_MEMORY_DMABUF,
    .m.fd   = external_dmabuf_fd,  /* GPU가 할당한 버퍼 */
};
ioctl(v4l2_fd, VIDIOC_QBUF, &buf);

vb2_ops 콜백

드라이버는 vb2_ops 콜백을 구현하여 vb2 프레임워크와 상호작용합니다:

static const struct vb2_ops my_vb2_ops = {
    .queue_setup     = my_queue_setup,     /* 버퍼 수/크기 결정 */
    .buf_prepare     = my_buf_prepare,     /* 큐잉 전 버퍼 검증 */
    .buf_queue       = my_buf_queue,       /* 버퍼를 하드웨어에 전달 */
    .start_streaming = my_start_streaming, /* DMA 시작 */
    .stop_streaming  = my_stop_streaming,  /* DMA 중지, 버퍼 반환 */
    .buf_init        = my_buf_init,        /* (선택) 버퍼 초기 설정 */
    .buf_cleanup     = my_buf_cleanup,     /* (선택) 버퍼 정리 */
    .wait_prepare    = vb2_ops_wait_prepare,  /* lock 해제 헬퍼 */
    .wait_finish     = vb2_ops_wait_finish,   /* lock 획득 헬퍼 */
};

각 콜백의 호출 시점:

스트리밍 흐름

유저스페이스의 전형적인 V4L2 캡처 루프:

/* 1. 버퍼 요청 */
ioctl(fd, VIDIOC_REQBUFS, &reqbufs);    /* → queue_setup() */

/* 2. 버퍼 정보 조회 + mmap */
for (i = 0; i < n; i++) {
    ioctl(fd, VIDIOC_QUERYBUF, &buf[i]);
    buffers[i] = mmap(NULL, buf[i].length,
                      PROT_READ | PROT_WRITE, MAP_SHARED,
                      fd, buf[i].m.offset);
}

/* 3. 모든 버퍼 큐잉 */
for (i = 0; i < n; i++)
    ioctl(fd, VIDIOC_QBUF, &buf[i]);      /* → buf_prepare() → buf_queue() */

/* 4. 스트리밍 시작 */
ioctl(fd, VIDIOC_STREAMON, &type);       /* → start_streaming() */

/* 5. 캡처 루프 */
while (running) {
    poll(fds, 1, -1);                       /* 프레임 대기 */
    ioctl(fd, VIDIOC_DQBUF, &buf);          /* 완료된 버퍼 수거 */
    process_frame(buffers[buf.index], buf.bytesused);
    ioctl(fd, VIDIOC_QBUF, &buf);           /* 버퍼 재큐잉 */
}

/* 6. 스트리밍 중지 */
ioctl(fd, VIDIOC_STREAMOFF, &type);      /* → stop_streaming() */

vb2_mem_ops 상세

vb2_mem_ops는 메모리 할당자의 저수준 인터페이스입니다. 커널이 제공하는 3가지 구현 외에 커스텀 할당자도 만들 수 있습니다:

V4L2 ioctl 인터페이스

V4L2는 include/uapi/linux/videodev2.h에 정의된 풍부한 ioctl 세트를 제공합니다. 핵심 ioctl을 범주별로 살펴봅니다.

VIDIOC_QUERYCAP — 디바이스 능력 조회

struct v4l2_capability cap;
ioctl(fd, VIDIOC_QUERYCAP, &cap);
/* cap.capabilities: 전체 디바이스, cap.device_caps: 이 노드의 능력 */

주요 capability 플래그:

포맷 ioctl (ENUM_FMT / G_FMT / S_FMT / TRY_FMT)

포맷 negotiation은 V4L2의 핵심 메커니즘입니다:

/* 지원 포맷 열거 */
struct v4l2_fmtdesc fmtdesc = { .type = V4L2_BUF_TYPE_VIDEO_CAPTURE };
while (ioctl(fd, VIDIOC_ENUM_FMT, &fmtdesc) == 0) {
    printf("[%d] %s (%.4s)\\n", fmtdesc.index,
           fmtdesc.description, (char *)&fmtdesc.pixelformat);
    fmtdesc.index++;
}

/* 현재 포맷 조회 */
struct v4l2_format fmt = { .type = V4L2_BUF_TYPE_VIDEO_CAPTURE };
ioctl(fd, VIDIOC_G_FMT, &fmt);

/* 포맷 설정 */
fmt.fmt.pix.width       = 1920;
fmt.fmt.pix.height      = 1080;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
fmt.fmt.pix.field       = V4L2_FIELD_NONE;
ioctl(fd, VIDIOC_S_FMT, &fmt);
/* 드라이버가 요청값을 가장 가까운 지원값으로 조정할 수 있음 */

포맷 협상 흐름

유저스페이스는 TRY_FMT → S_FMT → G_FMT 시퀀스를 통해 드라이버와 포맷을 협상합니다. 드라이버는 요청된 값을 하드웨어 능력에 맞게 조정하여 반환합니다:

주요 픽셀 포맷:

버퍼 ioctl

스트리밍 제어와 이벤트

/* 스트리밍 시작/중지 */
enum v4l2_buf_type type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
ioctl(fd, VIDIOC_STREAMON,  &type);
ioctl(fd, VIDIOC_STREAMOFF, &type);

/* 이벤트 구독 (예: EOS, 소스 변경) */
struct v4l2_event_subscription sub = {
    .type = V4L2_EVENT_EOS,   /* 또는 V4L2_EVENT_SOURCE_CHANGE */
};
ioctl(fd, VIDIOC_SUBSCRIBE_EVENT, &sub);

/* 이벤트 수신 (DQEVENT) */
struct v4l2_event ev;
ioctl(fd, VIDIOC_DQEVENT, &ev);

Selection API (크롭/컴포즈)

Selection API는 레거시 crop API를 대체합니다. 캡처 시 소스 영역(crop)과 출력 시 대상 영역(compose)을 설정합니다:

struct v4l2_selection sel = {
    .type   = V4L2_BUF_TYPE_VIDEO_CAPTURE,
    .target = V4L2_SEL_TGT_CROP,       /* 캡처할 소스 영역 */
    .r      = { .left = 100, .top = 100, .width = 640, .height = 480 },
};
ioctl(fd, VIDIOC_S_SELECTION, &sel);

/* 주요 target 값 */
/* V4L2_SEL_TGT_CROP          — 캡처: 소스에서 읽을 영역 */
/* V4L2_SEL_TGT_CROP_BOUNDS   — 크롭 가능 최대 범위 */
/* V4L2_SEL_TGT_COMPOSE       — 출력: 버퍼 내 배치 영역 */
/* V4L2_SEL_TGT_COMPOSE_BOUNDS— 컴포즈 가능 최대 범위 */

포맷과 컬러스페이스(Colorspace)

V4L2의 포맷 시스템은 FourCC 코드(4바이트 식별자)로 픽셀 포맷을 식별합니다. 올바른 색 재현을 위해 컬러스페이스, 전송 함수(Transfer Function), 양자화(Quantization) 범위를 함께 지정해야 합니다.

FourCC 시스템

FourCC(Four Character Code)는 4바이트 정수로 픽셀 포맷을 고유하게 식별합니다. V4L2는 v4l2_fourcc() 매크로로 FourCC를 생성합니다:

/* include/uapi/linux/videodev2.h */
#define v4l2_fourcc(a, b, c, d) \
    ((__u32)(a) | ((__u32)(b) << 8) | \
     ((__u32)(c) << 16) | ((__u32)(d) << 24))

/* 예: V4L2_PIX_FMT_YUYV = v4l2_fourcc('Y','U','Y','V') = 0x56595559 */

YUV 포맷 상세

YUV 포맷은 밝기(Y, Luma)와 색차(U/V, Chroma) 성분으로 분리됩니다. 크로마 서브샘플링(Chroma Subsampling)에 따라 다양한 변형이 있습니다:

메모리 레이아웃(Layout) 변형:

Bayer(RAW) 포맷

이미지 센서는 Bayer 패턴(Color Filter Array)으로 RAW 데이터를 출력합니다. 각 픽셀은 R/G/B 중 하나의 색만 캡처하며, ISP의 디모자이크(Demosaic) 과정을 거쳐야 완전한 이미지가 됩니다:

컬러스페이스와 관련 파라미터

v4l2_pix_format은 픽셀 포맷 외에 올바른 색 재현을 위한 추가 파라미터를 포함합니다:

struct v4l2_pix_format {
    ...
    __u32 colorspace;    /* V4L2_COLORSPACE_* */
    __u32 xfer_func;     /* V4L2_XFER_FUNC_*  — 전송 함수 */
    __u32 ycbcr_enc;     /* V4L2_YCBCR_ENC_*  — YCbCr 인코딩 */
    __u32 quantization;  /* V4L2_QUANTIZATION_* — 양자화 범위 */
};

싱글플레인 vs 멀티플레인 API

V4L2는 두 가지 버퍼 타입 API를 제공합니다:

/* 멀티플레인 포맷 설정 예: NV12 (2 플레인) */
struct v4l2_format fmt = { .type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE };
fmt.fmt.pix_mp.width        = 1920;
fmt.fmt.pix_mp.height       = 1080;
fmt.fmt.pix_mp.pixelformat  = V4L2_PIX_FMT_NV12;
fmt.fmt.pix_mp.num_planes   = 2;
fmt.fmt.pix_mp.colorspace   = V4L2_COLORSPACE_REC709;

ioctl(fd, VIDIOC_S_FMT, &fmt);

/* 플레인별 크기 확인 */
printf("Plane 0 (Y): %u bytes, stride %u\n",
       fmt.fmt.pix_mp.plane_fmt[0].sizeimage,
       fmt.fmt.pix_mp.plane_fmt[0].bytesperline);
printf("Plane 1 (UV): %u bytes, stride %u\n",
       fmt.fmt.pix_mp.plane_fmt[1].sizeimage,
       fmt.fmt.pix_mp.plane_fmt[1].bytesperline);

V4L2 드라이버 개발

V4L2 캡처 드라이버의 핵심 구성 요소를 살펴봅니다.

v4l2_file_operations 설정

static const struct v4l2_file_operations my_fops = {
    .owner          = THIS_MODULE,
    .open           = v4l2_fh_open,          /* 기본 핸들러 사용 가능 */
    .release        = vb2_fop_release,       /* vb2 정리 포함 */
    .read           = vb2_fop_read,          /* read() I/O (선택) */
    .poll           = vb2_fop_poll,          /* poll/select 지원 */
    .mmap           = vb2_fop_mmap,          /* mmap 매핑 */
    .unlocked_ioctl = video_ioctl2,          /* V4L2 ioctl 디스패처 */
};

v4l2_ioctl_ops 스켈레톤

static const struct v4l2_ioctl_ops my_ioctl_ops = {
    /* 능력 조회 */
    .vidioc_querycap         = my_querycap,

    /* 포맷 */
    .vidioc_enum_fmt_vid_cap = my_enum_fmt,
    .vidioc_g_fmt_vid_cap    = my_g_fmt,
    .vidioc_s_fmt_vid_cap    = my_s_fmt,
    .vidioc_try_fmt_vid_cap  = my_try_fmt,

    /* 버퍼 — vb2 헬퍼 사용 */
    .vidioc_reqbufs          = vb2_ioctl_reqbufs,
    .vidioc_querybuf         = vb2_ioctl_querybuf,
    .vidioc_qbuf             = vb2_ioctl_qbuf,
    .vidioc_dqbuf            = vb2_ioctl_dqbuf,
    .vidioc_expbuf           = vb2_ioctl_expbuf,
    .vidioc_create_bufs      = vb2_ioctl_create_bufs,
    .vidioc_streamon         = vb2_ioctl_streamon,
    .vidioc_streamoff        = vb2_ioctl_streamoff,

    /* 입력 */
    .vidioc_enum_input       = my_enum_input,
    .vidioc_g_input          = my_g_input,
    .vidioc_s_input          = my_s_input,

    /* 이벤트 */
    .vidioc_subscribe_event   = v4l2_ctrl_subscribe_event,
    .vidioc_unsubscribe_event = v4l2_event_unsubscribe,
};

완전한 캡처 드라이버 예제

#include <linux/module.h>
#include <linux/platform_device.h>
#include <media/v4l2-device.h>
#include <media/v4l2-ioctl.h>
#include <media/v4l2-ctrls.h>
#include <media/videobuf2-dma-contig.h>

struct my_cam {
    struct v4l2_device       v4l2_dev;
    struct video_device      vdev;
    struct vb2_queue         queue;
    struct v4l2_ctrl_handler ctrl_handler;
    struct mutex            lock;
    struct v4l2_format      fmt;
    struct list_head        buf_list;
    spinlock_t              slock;
};

struct my_buffer {
    struct vb2_v4l2_buffer vb;
    struct list_head       list;
};

/* vb2 콜백 */
static int my_queue_setup(struct vb2_queue *q,
    unsigned int *nbuffers, unsigned int *nplanes,
    unsigned int sizes[], struct device *alloc_devs[])
{
    struct my_cam *cam = vb2_get_drv_priv(q);
    sizes[0] = cam->fmt.fmt.pix.sizeimage;
    *nplanes = 1;
    return 0;
}

static void my_buf_queue(struct vb2_buffer *vb)
{
    struct my_cam *cam = vb2_get_drv_priv(vb->vb2_queue);
    struct my_buffer *buf = container_of(
        to_vb2_v4l2_buffer(vb), struct my_buffer, vb);
    unsigned long flags;

    spin_lock_irqsave(&cam->slock, flags);
    list_add_tail(&buf->list, &cam->buf_list);
    spin_unlock_irqrestore(&cam->slock, flags);
}

static int my_start_streaming(struct vb2_queue *q, unsigned int count)
{
    /* 하드웨어 DMA 시작 */
    return 0;
}

static void my_stop_streaming(struct vb2_queue *q)
{
    struct my_cam *cam = vb2_get_drv_priv(q);
    struct my_buffer *buf, *tmp;
    unsigned long flags;

    /* 하드웨어 DMA 중지 */
    spin_lock_irqsave(&cam->slock, flags);
    list_for_each_entry_safe(buf, tmp, &cam->buf_list, list) {
        list_del(&buf->list);
        vb2_buffer_done(&buf->vb.vb2_buf, VB2_BUF_STATE_ERROR);
    }
    spin_unlock_irqrestore(&cam->slock, flags);
}

/* probe 함수 (간략화) */
static int my_cam_probe(struct platform_device *pdev)
{
    struct my_cam *cam;
    int ret;

    cam = devm_kzalloc(&pdev->dev, sizeof(*cam), GFP_KERNEL);
    mutex_init(&cam->lock);
    spin_lock_init(&cam->slock);
    INIT_LIST_HEAD(&cam->buf_list);

    /* v4l2_device 등록 */
    ret = v4l2_device_register(&pdev->dev, &cam->v4l2_dev);

    /* vb2_queue 초기화 */
    cam->queue.type      = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    cam->queue.io_modes  = VB2_MMAP | VB2_DMABUF;
    cam->queue.ops       = &my_vb2_ops;
    cam->queue.mem_ops   = &vb2_dma_contig_memops;
    cam->queue.drv_priv  = cam;
    cam->queue.buf_struct_size = sizeof(struct my_buffer);
    cam->queue.lock      = &cam->lock;
    cam->queue.dev       = &pdev->dev;
    vb2_queue_init(&cam->queue);

    /* video_device 설정 */
    cam->vdev.v4l2_dev    = &cam->v4l2_dev;
    cam->vdev.queue       = &cam->queue;
    cam->vdev.fops        = &my_fops;
    cam->vdev.ioctl_ops   = &my_ioctl_ops;
    cam->vdev.lock        = &cam->lock;
    cam->vdev.device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_STREAMING;
    strscpy(cam->vdev.name, "my-cam", sizeof(cam->vdev.name));
    video_set_drvdata(&cam->vdev, cam);

    return video_register_device(&cam->vdev, VFL_TYPE_VIDEO, -1);
}

인터럽트(Interrupt) 핸들러와 버퍼 완료 패턴

실제 캡처 드라이버에서 프레임 완료 인터럽트를 처리하는 패턴:

static irqreturn_t my_cam_irq(int irq, void *data)
{
    struct my_cam *cam = data;
    struct my_buffer *buf;
    unsigned long flags;
    u32 status;

    /* 인터럽트 상태 읽기 */
    status = readl(cam->regs + REG_INT_STATUS);
    if (!(status & INT_FRAME_DONE))
        return IRQ_NONE;

    /* 인터럽트 클리어 */
    writel(status, cam->regs + REG_INT_CLEAR);

    spin_lock_irqsave(&cam->slock, flags);

    /* 현재 활성 버퍼 가져오기 */
    buf = list_first_entry_or_null(&cam->buf_list,
                                    struct my_buffer, list);
    if (buf) {
        list_del(&buf->list);

        /* 타임스탬프와 시퀀스 번호 기록 */
        buf->vb.vb2_buf.timestamp = ktime_get_ns();
        buf->vb.sequence = cam->sequence++;
        buf->vb.field = V4L2_FIELD_NONE;

        /* 실제 사용된 바이트 수 설정 */
        vb2_set_plane_payload(&buf->vb.vb2_buf, 0,
                              cam->fmt.fmt.pix.sizeimage);

        /* 버퍼 완료 → 유저스페이스 poll/DQBUF 깨움 */
        vb2_buffer_done(&buf->vb.vb2_buf, VB2_BUF_STATE_DONE);
    }

    /* 다음 버퍼가 있으면 DMA 주소 프로그래밍 */
    buf = list_first_entry_or_null(&cam->buf_list,
                                    struct my_buffer, list);
    if (buf) {
        dma_addr_t addr = vb2_dma_contig_plane_dma_addr(
            &buf->vb.vb2_buf, 0);
        writel(addr, cam->regs + REG_DMA_ADDR);
    }

    spin_unlock_irqrestore(&cam->slock, flags);
    return IRQ_HANDLED;
}

에러 처리와 복구

V4L2 드라이버에서 자주 발생하는 에러 상황과 올바른 처리 패턴:

/* start_streaming 실패 시: 큐잉된 모든 버퍼를 ERROR 상태로 반환 */
static int my_start_streaming_safe(struct vb2_queue *q, unsigned int count)
{
    struct my_cam *cam = vb2_get_drv_priv(q);
    int ret;

    cam->sequence = 0;

    /* 클록/전원 활성화 */
    ret = clk_prepare_enable(cam->clk);
    if (ret)
        goto err_return_bufs;

    /* 하드웨어 초기화 */
    ret = my_hw_init(cam);
    if (ret)
        goto err_clk;

    /* DMA 시작 */
    ret = my_dma_start(cam);
    if (ret)
        goto err_hw;

    return 0;

err_hw:
    my_hw_deinit(cam);
err_clk:
    clk_disable_unprepare(cam->clk);
err_return_bufs:
    /* 필수: 실패 시 모든 버퍼를 ERROR로 반환 */
    {
        struct my_buffer *buf, *tmp;
        unsigned long flags;

        spin_lock_irqsave(&cam->slock, flags);
        list_for_each_entry_safe(buf, tmp, &cam->buf_list, list) {
            list_del(&buf->list);
            vb2_buffer_done(&buf->vb.vb2_buf, VB2_BUF_STATE_QUEUED);
        }
        spin_unlock_irqrestore(&cam->slock, flags);
    }
    return ret;
}

/* probe 에러 처리 — 역순 해제 패턴 */
static int my_cam_probe_safe(struct platform_device *pdev)
{
    struct my_cam *cam;
    int ret;

    cam = devm_kzalloc(&pdev->dev, sizeof(*cam), GFP_KERNEL);
    if (!cam)
        return -ENOMEM;

    ret = v4l2_device_register(&pdev->dev, &cam->v4l2_dev);
    if (ret)
        return ret;

    ret = my_ctrl_init(cam);
    if (ret)
        goto err_v4l2;

    ret = my_queue_init(cam);
    if (ret)
        goto err_ctrl;

    ret = video_register_device(&cam->vdev, VFL_TYPE_VIDEO, -1);
    if (ret)
        goto err_ctrl;

    dev_info(&pdev->dev, "registered as /dev/video%d\n", cam->vdev.num);
    return 0;

err_ctrl:
    v4l2_ctrl_handler_free(&cam->ctrl_handler);
err_v4l2:
    v4l2_device_unregister(&cam->v4l2_dev);
    return ret;
}

런타임 PM(Power Management) 통합

비디오 디바이스는 유휴(Idle) 시 전력 소모가 크므로 런타임 PM 통합이 중요합니다:

/* open 시 PM resume */
static int my_cam_open(struct file *file)
{
    struct my_cam *cam = video_drvdata(file);
    int ret;

    ret = v4l2_fh_open(file);
    if (ret)
        return ret;

    /* 첫 번째 open이면 하드웨어 전원 켜기 */
    ret = pm_runtime_resume_and_get(cam->dev);
    if (ret < 0) {
        v4l2_fh_release(file);
        return ret;
    }
    return 0;
}

/* release 시 PM suspend */
static int my_cam_release(struct file *file)
{
    struct my_cam *cam = video_drvdata(file);
    int ret;

    ret = vb2_fop_release(file);
    pm_runtime_put(cam->dev);
    return ret;
}

/* 런타임 PM 콜백 */
static int my_cam_runtime_suspend(struct device *dev)
{
    struct my_cam *cam = dev_get_drvdata(dev);
    clk_disable_unprepare(cam->clk);
    return 0;
}

static int my_cam_runtime_resume(struct device *dev)
{
    struct my_cam *cam = dev_get_drvdata(dev);
    return clk_prepare_enable(cam->clk);
}

V4L2 서브디바이스 프레임워크

복잡한 미디어 파이프라인(센서 → CSI-2 리시버 → ISP → DMA 엔진)에서 각 하드웨어 블록을 v4l2_subdev로 모델링합니다. 서브디바이스는 v4l2_device에 등록되며, Media Controller를 통해 연결됩니다.

v4l2_subdev 구조체

/* include/media/v4l2-subdev.h */
struct v4l2_subdev {
    struct list_head             list;        /* v4l2_device의 subdevs 리스트 */
    struct v4l2_device          *v4l2_dev;
    const struct v4l2_subdev_ops *ops;
    const struct v4l2_subdev_internal_ops *internal_ops;
    struct v4l2_ctrl_handler   *ctrl_handler;
    struct media_entity         entity;      /* Media Controller 엔터티 */
    u32                          flags;       /* V4L2_SUBDEV_FL_* */
    char                         name[52];
    ...
};

/* 등록/해제 */
int  v4l2_device_register_subdev(struct v4l2_device *, struct v4l2_subdev *);
void v4l2_device_unregister_subdev(struct v4l2_subdev *);

v4l2_subdev_ops (core/video/pad)

struct v4l2_subdev_ops {
    const struct v4l2_subdev_core_ops  *core;   /* log_status, ioctl 등 */
    const struct v4l2_subdev_video_ops *video;  /* s_stream 등 */
    const struct v4l2_subdev_pad_ops   *pad;    /* 포맷/Selection 협상 */
    const struct v4l2_subdev_sensor_ops *sensor; /* 센서 전용 */
};

/* video ops — 스트리밍 제어 */
struct v4l2_subdev_video_ops {
    int (*s_stream)(struct v4l2_subdev *sd, int enable);
    int (*g_frame_interval)(...);
    int (*s_frame_interval)(...);
    ...
};

/* pad ops — 포맷 협상 */
struct v4l2_subdev_pad_ops {
    int (*enum_mbus_code)(...);     /* 미디어 버스 코드 열거 */
    int (*get_fmt)(...);             /* 패드 포맷 조회 */
    int (*set_fmt)(...);             /* 패드 포맷 설정 */
    int (*get_selection)(...);       /* 크롭/컴포즈 조회 */
    int (*set_selection)(...);       /* 크롭/컴포즈 설정 */
    int (*enable_streams)(...);     /* Streams API */
    int (*disable_streams)(...);    /* Streams API */
    ...
};

패드 오퍼레이션과 미디어 버스 포맷

서브디바이스의 패드(입출력(I/O) 포트)는 미디어 버스 포맷(v4l2_mbus_framefmt)으로 데이터 형식을 협상합니다:

struct v4l2_mbus_framefmt {
    __u32 width;          /* 이미지 너비 */
    __u32 height;         /* 이미지 높이 */
    __u32 code;           /* MEDIA_BUS_FMT_* */
    __u32 field;          /* V4L2_FIELD_NONE 등 */
    __u32 colorspace;     /* V4L2_COLORSPACE_* */
    ...
};

/* 주요 미디어 버스 코드 예시 */
/* MEDIA_BUS_FMT_SRGGB10_1X10  — 10-bit Bayer RGGB */
/* MEDIA_BUS_FMT_YUYV8_2X8     — YUV 4:2:2 8-bit */
/* MEDIA_BUS_FMT_UYVY8_1X16    — YUV 4:2:2 16-bit bus */
/* MEDIA_BUS_FMT_RGB888_1X24   — RGB 24-bit */

서브디바이스 active state (커널 6.3+)

최신 커널에서는 v4l2_subdev_state가 서브디바이스의 포맷/Selection 상태를 중앙 관리합니다. TRY와 ACTIVE 상태를 구분하여 포맷 협상의 안전성을 보장합니다:

/* 패드 포맷 조회 — state에서 가져오기 */
static int my_get_fmt(struct v4l2_subdev *sd,
                      struct v4l2_subdev_state *state,
                      struct v4l2_subdev_format *fmt)
{
    /* state가 TRY/ACTIVE를 자동으로 구분 */
    fmt->format = *v4l2_subdev_state_get_format(state, fmt->pad);
    return 0;
}

/* 패드 포맷 설정 — state에 저장 */
static int my_set_fmt(struct v4l2_subdev *sd,
                      struct v4l2_subdev_state *state,
                      struct v4l2_subdev_format *fmt)
{
    struct v4l2_mbus_framefmt *mf;

    /* 지원하는 포맷으로 조정 */
    fmt->format.code = my_find_best_code(fmt->format.code);
    fmt->format.width = clamp(fmt->format.width, 64, 4096);
    fmt->format.height = clamp(fmt->format.height, 64, 4096);

    /* state에 저장 */
    mf = v4l2_subdev_state_get_format(state, fmt->pad);
    *mf = fmt->format;

    /* source 패드도 연쇄(Cascade) 업데이트 */
    mf = v4l2_subdev_state_get_format(state, MY_SOURCE_PAD);
    *mf = fmt->format;
    /* ISP가 포맷 변환하면 source 패드 코드만 변경 */

    return 0;
}

/* init_state — 서브디바이스 기본 포맷 설정 */
static int my_init_state(struct v4l2_subdev *sd,
                         struct v4l2_subdev_state *state)
{
    struct v4l2_mbus_framefmt *fmt;

    fmt = v4l2_subdev_state_get_format(state, 0);
    fmt->code   = MEDIA_BUS_FMT_SRGGB10_1X10;
    fmt->width  = 1920;
    fmt->height = 1080;
    fmt->field  = V4L2_FIELD_NONE;
    fmt->colorspace = V4L2_COLORSPACE_RAW;

    return 0;
}

static const struct v4l2_subdev_internal_ops my_internal_ops = {
    .init_state = my_init_state,
};

포맷 협상(Format Negotiation) 흐름

파이프라인의 포맷 협상은 소스에서 싱크 방향(센서 → ISP → DMA)으로 진행됩니다. 각 서브디바이스의 싱크 패드에 포맷을 설정하면, 서브디바이스가 source 패드 포맷을 자동으로 결정합니다:

Streams API (멀티플렉스 라우팅)

최신 커널(6.3+)의 Streams API는 하나의 패드에서 여러 데이터 스트림을 다중화(Multiplexing)할 수 있습니다. CSI-2 가상 채널이나 멀티카메라 시스템에서 활용됩니다:

/* 라우팅 설정 */
struct v4l2_subdev_route routes[] = {
    { .sink_pad = 0, .sink_stream = 0,
      .source_pad = 1, .source_stream = 0,
      .flags = V4L2_SUBDEV_ROUTE_FL_ACTIVE },
    { .sink_pad = 0, .sink_stream = 1,
      .source_pad = 2, .source_stream = 0,
      .flags = V4L2_SUBDEV_ROUTE_FL_ACTIVE },
};
/* CSI-2 VC0 → 패드1, CSI-2 VC1 → 패드2 라우팅 */

I2C 센서 서브디바이스 드라이버 예제

struct my_sensor {
    struct v4l2_subdev        sd;
    struct media_pad          pad;   /* source 패드 1개 */
    struct v4l2_ctrl_handler  ctrl_handler;
    struct v4l2_mbus_framefmt fmt;
};

static int my_sensor_s_stream(struct v4l2_subdev *sd, int enable)
{
    struct my_sensor *sensor = container_of(sd, struct my_sensor, sd);
    if (enable)
        return my_sensor_start(sensor);   /* I2C 레지스터 설정 */
    return my_sensor_stop(sensor);
}

static int my_sensor_set_fmt(struct v4l2_subdev *sd,
    struct v4l2_subdev_state *state,
    struct v4l2_subdev_format *fmt)
{
    /* 포맷 협상: 드라이버가 지원하는 가장 가까운 값으로 조정 */
    fmt->format.code   = MEDIA_BUS_FMT_SRGGB10_1X10;
    fmt->format.width  = clamp(fmt->format.width, 640, 3840);
    fmt->format.height = clamp(fmt->format.height, 480, 2160);
    *v4l2_subdev_state_get_format(state, fmt->pad) = fmt->format;
    return 0;
}

static int my_sensor_probe(struct i2c_client *client)
{
    struct my_sensor *sensor;

    sensor = devm_kzalloc(&client->dev, sizeof(*sensor), GFP_KERNEL);
    v4l2_i2c_subdev_init(&sensor->sd, client, &my_sensor_ops);

    sensor->pad.flags = MEDIA_PAD_FL_SOURCE;
    sensor->sd.entity.function = MEDIA_ENT_F_CAM_SENSOR;
    media_entity_pads_init(&sensor->sd.entity, 1, &sensor->pad);

    sensor->sd.flags |= V4L2_SUBDEV_FL_HAS_DEVNODE;
    return v4l2_async_register_subdev(&sensor->sd);
}

V4L2 컨트롤 프레임워크

V4L2 컨트롤 프레임워크는 밝기, 대비, 노출, 화이트 밸런스 등의 파라미터를 통합 관리합니다. 드라이버는 v4l2_ctrl_handler를 초기화하고 컨트롤을 등록하기만 하면 됩니다.

v4l2_ctrl_handler 초기화

struct v4l2_ctrl_handler *hdl = &mydev->ctrl_handler;

v4l2_ctrl_handler_init(hdl, 8);  /* hint: 예상 컨트롤 수 */

/* 표준 컨트롤 추가 */
v4l2_ctrl_new_std(hdl, &my_ctrl_ops,
    V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);   /* min, max, step, default */
v4l2_ctrl_new_std(hdl, &my_ctrl_ops,
    V4L2_CID_CONTRAST,   0, 255, 1, 128);
v4l2_ctrl_new_std_menu(hdl, &my_ctrl_ops,
    V4L2_CID_EXPOSURE_AUTO, V4L2_EXPOSURE_APERTURE_PRIORITY, 0,
    V4L2_EXPOSURE_AUTO);

if (hdl->error)
    return hdl->error;

/* video_device 또는 v4l2_subdev에 연결 */
mydev->vdev.ctrl_handler = hdl;
/* 또는: mydev->sd.ctrl_handler = hdl; */

표준 컨트롤 (V4L2_CID_*)

커스텀/컴파운드 컨트롤

/* 커스텀 컨트롤 정의 */
static const struct v4l2_ctrl_config my_custom_ctrl = {
    .ops  = &my_ctrl_ops,
    .id   = V4L2_CID_USER_BASE + 0x1000,
    .name = "My Custom Control",
    .type = V4L2_CTRL_TYPE_INTEGER,
    .min  = 0, .max = 100, .step = 1, .def = 50,
};
v4l2_ctrl_new_custom(hdl, &my_custom_ctrl, NULL);

/* 컴파운드 컨트롤 (H.264 SPS 등) */
v4l2_ctrl_new_std_compound(hdl, &my_ctrl_ops,
    V4L2_CID_STATELESS_H264_SPS,
    v4l2_ctrl_ptr_create(NULL));

v4l2_ctrl_ops 콜백과 클러스터

static int my_s_ctrl(struct v4l2_ctrl *ctrl)
{
    struct my_device *dev = container_of(
        ctrl->handler, struct my_device, ctrl_handler);

    switch (ctrl->id) {
    case V4L2_CID_BRIGHTNESS:
        return my_hw_set_brightness(dev, ctrl->val);
    case V4L2_CID_EXPOSURE_AUTO:
        /* 클러스터: auto가 켜지면 manual exposure는 비활성 */
        return my_hw_set_exposure(dev, ctrl);
    }
    return -EINVAL;
}

static const struct v4l2_ctrl_ops my_ctrl_ops = {
    .s_ctrl = my_s_ctrl,
};

/* 클러스터: auto/manual 컨트롤 연결 */
v4l2_ctrl_auto_cluster(2, &dev->auto_exposure, V4L2_EXPOSURE_MANUAL, false);

컨트롤 상속(Inheritance)과 위임

V4L2 컨트롤은 서브디바이스에서 video_device로 자동 상속됩니다. 유저스페이스는 /dev/videoN을 통해 서브디바이스의 컨트롤에 접근할 수 있습니다:

/* 서브디바이스의 컨트롤을 video_device에 상속 */
/* video_device에 ctrl_handler를 설정하지 않으면 */
/* v4l2_device의 ctrl_handler를 자동으로 사용 */

/* 방법 1: 직접 설정 */
cam->vdev.ctrl_handler = &cam->ctrl_handler;

/* 방법 2: 서브디바이스 핸들러를 video_device에 추가 */
v4l2_ctrl_add_handler(&cam->ctrl_handler,
                       sensor_sd->ctrl_handler, NULL, true);

/* 방법 3: v4l2_device 레벨에서 설정 (모든 video_device에 적용) */
cam->v4l2_dev.ctrl_handler = &cam->ctrl_handler;

컨트롤 이벤트

컨트롤 값 변경을 유저스페이스에 알리는 이벤트 메커니즘:

/* 유저스페이스: 컨트롤 변경 이벤트 구독 */
struct v4l2_event_subscription sub = {
    .type = V4L2_EVENT_CTRL,
    .id   = V4L2_CID_EXPOSURE_ABSOLUTE,
};
ioctl(fd, VIDIOC_SUBSCRIBE_EVENT, &sub);

/* 이벤트 대기 (poll + DQEVENT) */
struct v4l2_event ev;
ioctl(fd, VIDIOC_DQEVENT, &ev);
if (ev.type == V4L2_EVENT_CTRL) {
    struct v4l2_event_ctrl *ctrl_ev = &ev.u.ctrl;
    printf("Control %08x changed: value=%d, flags=%x\n",
           ev.id, ctrl_ev->value, ctrl_ev->flags);
}

/* 드라이버 측: 커스텀 이벤트 발생 */
v4l2_ctrl_s_ctrl(ctrl, new_value);
/* → 프레임워크가 자동으로 이벤트 생성 */

유저스페이스에서 컨트롤 사용

# 모든 컨트롤 목록 조회
$ v4l2-ctl -d /dev/video0 --list-ctrls
#                      brightness 0x00980900 (int)    : min=0 max=255 step=1 default=128 value=128
#                        contrast 0x00980901 (int)    : min=0 max=255 step=1 default=128 value=128
#                      saturation 0x00980902 (int)    : min=0 max=255 step=1 default=128 value=128
#               exposure_auto (1) 0x009a0901 (menu)   : min=0 max=3 default=3 value=3

# 컨트롤 상세 조회 (확장 컨트롤 포함)
$ v4l2-ctl -d /dev/video0 --list-ctrls-menus

# 컨트롤 값 설정
$ v4l2-ctl -d /dev/video0 --set-ctrl brightness=200
$ v4l2-ctl -d /dev/video0 --set-ctrl exposure_auto=1,exposure_absolute=500

# 서브디바이스 직접 컨트롤 (Media Controller 환경)
$ v4l2-ctl -d /dev/v4l-subdev0 --list-ctrls
$ v4l2-ctl -d /dev/v4l-subdev0 --set-ctrl analogue_gain=200

Media Controller

Media Controller는 복잡한 미디어 파이프라인의 토폴로지를 유저스페이스에 노출합니다. 센서, ISP, DMA 엔진 등의 연결 관계를 엔터티/패드/링크 그래프로 표현합니다.

media_device 개요

struct media_device {
    struct device    *dev;
    char             model[32];
    struct list_head  entities;    /* media_entity 리스트 */
    struct list_head  pads;
    struct list_head  links;
    const struct media_device_ops *ops;
    ...
};

/* 초기화 + 등록 */
media_device_init(mdev);
strscpy(mdev->model, "My Camera", sizeof(mdev->model));
media_device_register(mdev);

/* v4l2_device에 연결 */
v4l2_dev->mdev = mdev;

엔터티/패드/링크

/* 엔터티: 하드웨어 블록 (센서, ISP 등) */
struct media_entity {
    char              name[32];
    u32               function;    /* MEDIA_ENT_F_* */
    struct media_pad *pads;
    u16               num_pads;
    ...
};

/* 패드: 엔터티의 입출력 포트 */
struct media_pad {
    struct media_entity *entity;
    u16                  index;
    u32                  flags;     /* MEDIA_PAD_FL_SINK/SOURCE */
};

/* 링크 생성: 센서 pad[0] → CSI pad[0] */
media_create_pad_link(&sensor->entity, 0,
                      &csi->entity, 0,
                      MEDIA_LNK_FL_ENABLED | MEDIA_LNK_FL_IMMUTABLE);

주요 엔터티 function 값:

파이프라인 관리

/* 파이프라인 유효성 검사 + 시작 */
struct media_pipeline pipe;
media_pipeline_start(&entity->pads[0], &pipe);

/* 파이프라인 중지 */
media_pipeline_stop(&entity->pads[0]);

/* 파이프라인 내 모든 엔터티 순회 */
media_pipeline_for_each_entity(&pipe, iter, entity) {
    /* entity 처리 */
}

미디어 그래프 구축 패턴

실제 카메라 파이프라인에서 Media Controller 그래프를 구성하는 완전한 예제:

static int my_platform_probe(struct platform_device *pdev)
{
    struct my_platform *plat;
    int ret;

    plat = devm_kzalloc(&pdev->dev, sizeof(*plat), GFP_KERNEL);

    /* 1. media_device 초기화 */
    media_device_init(&plat->mdev);
    plat->mdev.dev = &pdev->dev;
    strscpy(plat->mdev.model, "My Camera Platform",
            sizeof(plat->mdev.model));

    /* 2. v4l2_device에 media_device 연결 */
    plat->v4l2_dev.mdev = &plat->mdev;
    ret = v4l2_device_register(&pdev->dev, &plat->v4l2_dev);

    /* 3. CSI 리시버 서브디바이스 등록 */
    plat->csi.entity.function = MEDIA_ENT_F_VID_IF_BRIDGE;
    plat->csi_pads[0].flags = MEDIA_PAD_FL_SINK;
    plat->csi_pads[1].flags = MEDIA_PAD_FL_SOURCE;
    media_entity_pads_init(&plat->csi.entity, 2, plat->csi_pads);

    /* 4. DMA 엔진 video_device의 엔터티 설정 */
    plat->vdev.entity.function = MEDIA_ENT_F_IO_V4L;
    plat->vdev_pad.flags = MEDIA_PAD_FL_SINK;
    media_entity_pads_init(&plat->vdev.entity, 1, &plat->vdev_pad);

    /* 5. 내부 링크 생성: CSI source → DMA sink */
    media_create_pad_link(&plat->csi.entity, 1,
                          &plat->vdev.entity, 0,
                          MEDIA_LNK_FL_ENABLED | MEDIA_LNK_FL_IMMUTABLE);

    /* 6. async notifier로 센서 바인딩 대기 */
    v4l2_async_nf_init(&plat->notifier, &plat->v4l2_dev);
    /* ... fwnode에서 센서 추가 ... */

    /* 7. media_device 등록 */
    ret = media_device_register(&plat->mdev);

    return 0;
}

/* async notifier .bound 콜백: 센서 바인딩 시 링크 생성 */
static int my_notifier_bound(struct v4l2_async_notifier *notifier,
                             struct v4l2_subdev *sd,
                             struct v4l2_async_connection *asc)
{
    struct my_platform *plat = container_of(notifier,
        struct my_platform, notifier);

    /* 센서 source pad → CSI sink pad 링크 */
    return media_create_pad_link(&sd->entity, 0,
                                  &plat->csi.entity, 0,
                                  MEDIA_LNK_FL_ENABLED |
                                  MEDIA_LNK_FL_IMMUTABLE);
}

유저스페이스 API와 media-ctl 예제

# 토폴로지 확인
$ media-ctl -d /dev/media0 -p

# 링크 설정: 센서 → CSI 활성화
$ media-ctl -d /dev/media0 -l '"imx219 0-0010":0 -> "csi2-rx":0 [1]'

# 서브디바이스 포맷 설정
$ media-ctl -d /dev/media0 -V '"imx219 0-0010":0 [fmt:SRGGB10_1X10/1920x1080]'
$ media-ctl -d /dev/media0 -V '"csi2-rx":1 [fmt:SRGGB10_1X10/1920x1080]'

완전한 카메라 파이프라인 설정 스크립트 예제:

#!/bin/bash
# Rockchip RK3588 + IMX219 카메라 파이프라인 설정 예

MEDIA_DEV=/dev/media0

# 1. 링크 활성화
media-ctl -d $MEDIA_DEV -l '"imx219 4-0010":0 -> "rkisp1_csi":0 [1]'
media-ctl -d $MEDIA_DEV -l '"rkisp1_csi":1 -> "rkisp1_isp":0 [1]'
media-ctl -d $MEDIA_DEV -l '"rkisp1_isp":2 -> "rkisp1_resizer_mainpath":0 [1]'

# 2. 센서 포맷 설정 (3280x2464 @ 10-bit Bayer)
media-ctl -d $MEDIA_DEV -V '"imx219 4-0010":0 [fmt:SRGGB10_1X10/3280x2464]'

# 3. CSI 리시버 포맷 (패스스루)
media-ctl -d $MEDIA_DEV -V '"rkisp1_csi":1 [fmt:SRGGB10_1X10/3280x2464]'

# 4. ISP 입력 포맷
media-ctl -d $MEDIA_DEV -V '"rkisp1_isp":0 [fmt:SRGGB10_1X10/3280x2464 crop:(0,0)/3280x2464]'

# 5. ISP 출력 포맷 (디모자이크 + 스케일링)
media-ctl -d $MEDIA_DEV -V '"rkisp1_isp":2 [fmt:YUYV8_2X8/3280x2464 crop:(0,0)/3280x2464]'

# 6. 리사이저 출력 (1920x1080으로 다운스케일)
media-ctl -d $MEDIA_DEV -V '"rkisp1_resizer_mainpath":1 [fmt:YUYV8_2X8/1920x1080]'

# 7. 최종 캡처 포맷 설정
v4l2-ctl -d /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=NV12

# 8. 캡처 시작
v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=100 --stream-to=capture.raw

V4L2 M2M (Memory-to-Memory)

M2M(Memory-to-Memory) 프레임워크는 입력 버퍼(OUTPUT 큐)에서 데이터를 읽어 처리 후 출력 버퍼(CAPTURE 큐)에 쓰는 하드웨어 코덱/스케일러를 모델링합니다. 일반 캡처 드라이버와 달리 M2M 디바이스는 두 개의 vb2_queue(OUTPUT + CAPTURE)를 관리합니다.

M2M 프레임워크 구조

struct v4l2_m2m_dev;   /* M2M 디바이스 — v4l2_m2m_init()으로 생성 */
struct v4l2_m2m_ctx;   /* per-open context — OUTPUT/CAPTURE 큐 쌍 */

struct v4l2_m2m_ops {
    void (*device_run)(void *priv);        /* 작업 실행 */
    int  (*job_ready)(void *priv);         /* 실행 가능 여부 */
    void (*job_abort)(void *priv);         /* 작업 취소 */
};

/* 초기화 */
m2m_dev = v4l2_m2m_init(&my_m2m_ops);

/* open 시 context 생성 */
ctx->m2m_ctx = v4l2_m2m_ctx_init(m2m_dev, ctx, my_queue_init);

/* device_run에서: 입력/출력 버퍼 가져오기 */
src = v4l2_m2m_next_src_buf(ctx->m2m_ctx);
dst = v4l2_m2m_next_dst_buf(ctx->m2m_ctx);
/* 하드웨어에 작업 전달 */

/* IRQ 핸들러에서: 완료 알림 */
v4l2_m2m_buf_done(src, VB2_BUF_STATE_DONE);
v4l2_m2m_buf_done(dst, VB2_BUF_STATE_DONE);
v4l2_m2m_job_finish(m2m_dev, ctx->m2m_ctx);

Stateful 코덱

Stateful 코덱(H.264/HEVC/VP9 하드웨어 인코더/디코더)은 내부에 상태 머신을 가집니다:

Stateless 코덱 (Request API)

Stateless 코덱은 프레임 단위로 디코딩 파라미터를 전달합니다. Request API를 사용하여 버퍼와 컨트롤을 원자적으로 묶습니다:

/* Request 생성 */
int req_fd;
ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd);

/* 컨트롤 설정 (H.264 SPS/PPS/Slice 등) */
struct v4l2_ext_controls ctrls = { .request_fd = req_fd, ... };
ioctl(video_fd, VIDIOC_S_EXT_CTRLS, &ctrls);

/* 버퍼 제출 */
buf.request_fd = req_fd;
buf.flags |= V4L2_BUF_FLAG_REQUEST_FD;
ioctl(video_fd, VIDIOC_QBUF, &buf);

/* Request 큐잉 */
ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE, NULL);

Stateless 디코딩 상세 흐름

Stateless 디코더는 호스트(CPU)가 비트스트림 파싱을 수행하고, 프레임별로 디코딩 파라미터(SPS, PPS, 슬라이스 헤더 등)를 하드웨어에 전달합니다. 이 방식은 Request API와 함께 사용됩니다:

/* Stateless H.264 디코딩 전체 흐름 */

/* 1. 코덱 포맷 설정 */
struct v4l2_format out_fmt = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE };
out_fmt.fmt.pix_mp.pixelformat = V4L2_PIX_FMT_H264_SLICE;  /* 슬라이스 단위 입력 */
out_fmt.fmt.pix_mp.width = 1920;
out_fmt.fmt.pix_mp.height = 1080;
ioctl(fd, VIDIOC_S_FMT, &out_fmt);

struct v4l2_format cap_fmt = { .type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE };
cap_fmt.fmt.pix_mp.pixelformat = V4L2_PIX_FMT_NV12;  /* 디코딩 출력 */
ioctl(fd, VIDIOC_S_FMT, &cap_fmt);

/* 2. 버퍼 할당 + STREAMON */
ioctl(fd, VIDIOC_REQBUFS, &out_reqbufs);
ioctl(fd, VIDIOC_REQBUFS, &cap_reqbufs);
ioctl(fd, VIDIOC_STREAMON, &out_type);
ioctl(fd, VIDIOC_STREAMON, &cap_type);

/* 3. 프레임별 디코딩 루프 */
for (frame = 0; frame < total_frames; frame++) {
    /* Request 할당 */
    int req_fd;
    ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd);

    /* SPS 컨트롤 설정 */
    struct v4l2_ctrl_h264_sps sps = { ... };
    struct v4l2_ext_control ctrls[] = {
        { .id = V4L2_CID_STATELESS_H264_SPS, .ptr = &sps, .size = sizeof(sps) },
        { .id = V4L2_CID_STATELESS_H264_PPS, .ptr = &pps, .size = sizeof(pps) },
        { .id = V4L2_CID_STATELESS_H264_SLICE_PARAMS, .ptr = &slice, .size = sizeof(slice) },
        { .id = V4L2_CID_STATELESS_H264_DECODE_PARAMS, .ptr = &decode, .size = sizeof(decode) },
    };
    struct v4l2_ext_controls ext = {
        .count = 4, .controls = ctrls,
        .which = V4L2_CTRL_WHICH_REQUEST_VAL,
        .request_fd = req_fd,
    };
    ioctl(fd, VIDIOC_S_EXT_CTRLS, &ext);

    /* 비트스트림 데이터를 OUTPUT 버퍼에 복사 */
    memcpy(out_buf_ptr, slice_data, slice_size);

    /* OUTPUT 버퍼 제출 (Request에 연결) */
    struct v4l2_buffer out_buf = {
        .type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE,
        .request_fd = req_fd,
        .flags = V4L2_BUF_FLAG_REQUEST_FD,
    };
    ioctl(fd, VIDIOC_QBUF, &out_buf);

    /* CAPTURE 버퍼 제출 */
    ioctl(fd, VIDIOC_QBUF, &cap_buf);

    /* Request 큐잉 → 하드웨어 디코딩 시작 */
    ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE, NULL);

    /* 결과 대기 + 수거 */
    ioctl(fd, VIDIOC_DQBUF, &out_buf);  /* OUTPUT 반환 */
    ioctl(fd, VIDIOC_DQBUF, &cap_buf);  /* 디코딩된 프레임 */

    /* Request 재사용 */
    ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT, NULL);
}

Stateful vs Stateless 코덱 비교

주요 stateless 코덱 드라이버:

주요 stateful 코덱 드라이버:

카메라 서브시스템

임베디드 카메라는 여러 하드웨어 블록이 파이프라인으로 연결됩니다. V4L2 서브디바이스와 Media Controller를 조합하여 이 파이프라인을 모델링합니다.

카메라 파이프라인 구조

CSI-2 / MIPI 인터페이스

MIPI CSI-2(Camera Serial Interface 2)는 임베디드 카메라의 표준 인터페이스입니다. 고속 직렬 링크를 통해 센서 데이터를 SoC에 전달합니다:

CSI-2 패킷 구조:

가상 채널(Virtual Channel)을 사용한 멀티카메라 구성:

/* 드라이버에서 CSI-2 파라미터 확인 */
struct v4l2_fwnode_endpoint ep = {
    .bus_type = V4L2_MBUS_CSI2_DPHY,
};
v4l2_fwnode_endpoint_alloc_parse(fwnode, &ep);

dev_info(dev, "CSI-2: %d data lanes, %llu Hz link freq\n",
         ep.bus.mipi_csi2.num_data_lanes,
         ep.link_frequencies[0]);

/* 필요한 대역폭 계산 예 */
/* 3840x2160 @ 30fps, 10-bit RAW, 4 lanes */
/* = 3840 * 2160 * 30 * 10 = 2,488,320,000 bps ≈ 2.49 Gbps */
/* 4 lanes: 2.49 / 4 = 622 Mbps/lane → link_freq = 311 MHz */
/* (DDR: link_freq = bit_rate / 2) */

ISP 파이프라인 블록

ISP(Image Signal Processor)는 RAW Bayer 데이터를 처리하여 최종 이미지를 생성합니다. 각 블록은 순서대로 실행됩니다:

libcamera 아키텍처

복잡한 카메라 파이프라인(ISP 포함)에서는 V4L2만으로는 부족합니다. libcamera는 V4L2/Media Controller 위에서 파이프라인 구성, 3A 알고리즘, 버퍼 관리를 통합하는 유저스페이스 프레임워크입니다:

주요 ISP/카메라 플랫폼 드라이버:

전체 카메라 파이프라인 상세 흐름

임베디드 카메라 시스템에서 한 프레임이 센서에서 유저스페이스까지 전달되는 과정을 단계별로 살펴봅니다:

카메라 전원 시퀀스(Power Sequence)

카메라 센서는 엄격한 전원 투입 순서를 요구합니다. 잘못된 순서는 센서 손상이나 I2C 통신 실패를 유발합니다:

/* 전형적인 카메라 센서 전원 시퀀스 (예: IMX219) */
static int my_sensor_power_on(struct device *dev)
{
    struct my_sensor *sensor = dev_get_drvdata(dev);
    int ret;

    /* 1. 아날로그 전원 (AVDD) — 일반적으로 2.8V */
    ret = regulator_enable(sensor->avdd);
    if (ret)
        return ret;

    /* 2. 디지털 전원 (DVDD) — 일반적으로 1.2V */
    ret = regulator_enable(sensor->dvdd);
    if (ret)
        goto err_avdd;

    /* 3. I/O 전원 (DOVDD) — 일반적으로 1.8V */
    ret = regulator_enable(sensor->dovdd);
    if (ret)
        goto err_dvdd;

    /* 4. 클럭 활성화 (XCLK/MCLK) */
    ret = clk_prepare_enable(sensor->xclk);
    if (ret)
        goto err_dovdd;

    /* 5. 리셋 해제 (XCLR pin active high) */
    gpiod_set_value_cansleep(sensor->reset_gpio, 0);

    /* 6. 안정화 대기 — 데이터시트 참조 (보통 1~10ms) */
    usleep_range(6000, 10000);

    return 0;

err_dovdd:
    regulator_disable(sensor->dovdd);
err_dvdd:
    regulator_disable(sensor->dvdd);
err_avdd:
    regulator_disable(sensor->avdd);
    return ret;
}

/* 전원 off — 역순 */
static int my_sensor_power_off(struct device *dev)
{
    struct my_sensor *sensor = dev_get_drvdata(dev);

    gpiod_set_value_cansleep(sensor->reset_gpio, 1);
    clk_disable_unprepare(sensor->xclk);
    regulator_disable(sensor->dovdd);
    regulator_disable(sensor->dvdd);
    regulator_disable(sensor->avdd);

    return 0;
}

static const struct dev_pm_ops my_sensor_pm_ops = {
    SET_RUNTIME_PM_OPS(my_sensor_power_off,
                        my_sensor_power_on, NULL)
};

센서 모드(Mode) 테이블 패턴

카메라 센서는 여러 해상도/프레임레이트 모드를 지원합니다. 각 모드는 레지스터(Register) 테이블로 정의됩니다:

/* 센서 레지스터 설정 */
struct sensor_reg {
    u16 addr;
    u8  val;
};

/* 모드 정의 */
struct sensor_mode {
    u32 width;
    u32 height;
    u32 code;           /* MEDIA_BUS_FMT_* */
    struct v4l2_fract interval;  /* 프레임 간격(Interval) */
    const struct sensor_reg *reg_list;
    u32 reg_list_size;
    /* 노출/게인 범위 (모드별로 다를 수 있음) */
    u32 exposure_max;
    u32 vblank_def;     /* 수직 블랭킹 기본값 */
    u64 link_freq;      /* MIPI 링크 주파수 */
    u32 pixel_rate;     /* 픽셀 클럭 */
};

/* 모드 테이블 */
static const struct sensor_mode supported_modes[] = {
    {   /* Mode 0: 3840x2160 @ 30fps */
        .width      = 3840,
        .height     = 2160,
        .code       = MEDIA_BUS_FMT_SRGGB10_1X10,
        .interval   = { .numerator = 1, .denominator = 30 },
        .reg_list   = mode_3840x2160_regs,
        .reg_list_size = ARRAY_SIZE(mode_3840x2160_regs),
        .link_freq  = 600000000ULL,
        .pixel_rate = 240000000,
    },
    {   /* Mode 1: 1920x1080 @ 60fps */
        .width      = 1920,
        .height     = 1080,
        .code       = MEDIA_BUS_FMT_SRGGB10_1X10,
        .interval   = { .numerator = 1, .denominator = 60 },
        .reg_list   = mode_1920x1080_regs,
        .reg_list_size = ARRAY_SIZE(mode_1920x1080_regs),
        .link_freq  = 300000000ULL,
        .pixel_rate = 120000000,
    },
    {   /* Mode 2: 640x480 @ 120fps (슬로우 모션) */
        .width      = 640,
        .height     = 480,
        .code       = MEDIA_BUS_FMT_SRGGB10_1X10,
        .interval   = { .numerator = 1, .denominator = 120 },
        .reg_list   = mode_640x480_regs,
        .reg_list_size = ARRAY_SIZE(mode_640x480_regs),
        .link_freq  = 150000000ULL,
        .pixel_rate = 60000000,
    },
};

센서 드라이버 패턴과 async 등록

카메라 파이프라인에서 센서(I2C)와 CSI-2 리시버(platform)는 서로 다른 버스에 위치합니다. async 프레임워크가 서브디바이스 간 바인딩을 처리합니다:

/* CSI-2 리시버 (platform driver) — notifier 등록 */
struct v4l2_async_notifier notifier;

v4l2_async_nf_init(¬ifier, &v4l2_dev);
asd = v4l2_async_nf_add_fwnode_remote(¬ifier,
    of_fwnode_handle(ep_node), sizeof(*asd));
notifier.ops = &my_notifier_ops;  /* .bound, .complete */
v4l2_async_nf_register(¬ifier);

/* 센서 (I2C driver) — 비동기 등록 */
v4l2_async_register_subdev(&sensor->sd);
/* → notifier의 .bound 콜백 → 링크 생성 */

UVC (USB Video Class) 드라이버

UVC는 USB 비디오 디바이스(웹캠 등)의 표준 프로토콜입니다. Linux의 uvcvideo 드라이버는 UVC 1.0~1.5를 지원하며, 별도 드라이버 설치 없이 대부분의 USB 카메라를 사용할 수 있습니다.

UVC 아키텍처 (Terminal/Unit 토폴로지)

UVC 디바이스는 Terminal과 Unit의 연결 그래프로 구성됩니다:

UVC 토폴로지 예시

일반적인 USB 웹캠의 UVC 내부 토폴로지:

커널 uvcvideo 드라이버

# 커널 설정
CONFIG_USB_VIDEO_CLASS=m

# 디버그 레벨 설정
$ echo 0xffff > /sys/module/uvcvideo/parameters/trace

# UVC 디바이스 정보 확인
$ lsusb -d 046d:0825 -v | grep -A5 VideoControl

# UVC 디바이스 스트리밍 인터페이스 정보
$ v4l2-ctl -d /dev/video0 --all
$ v4l2-ctl -d /dev/video0 --list-formats-ext

# UVC 카메라 일반적 포맷/해상도
$ v4l2-ctl -d /dev/video0 --list-formats-ext
# [0]: 'YUYV' (YUYV 4:2:2)
#   Size: 640x480, 1280x720, 1920x1080
#   Interval: 1/30, 1/15
# [1]: 'MJPG' (Motion-JPEG)
#   Size: 640x480, 1280x720, 1920x1080, 3840x2160
#   Interval: 1/30, 1/60

Extension Unit 접근

/* UVC Extension Unit 직접 접근 */
#include <linux/uvcvideo.h>

/* Extension Unit 컨트롤 조회 */
struct uvc_xu_control_query xquery = {
    .unit     = 3,           /* Extension Unit ID */
    .selector = 1,           /* 컨트롤 셀렉터 */
    .query    = UVC_GET_CUR,  /* GET/SET */
    .size     = 4,
    .data     = buf,
};
ioctl(fd, UVCIOC_CTRL_QUERY, &xquery);

/* Extension Unit 컨트롤 설정 */
xquery.query = UVC_SET_CUR;
uint8_t value[] = { 0x01, 0x00, 0x00, 0x00 };
xquery.data = value;
ioctl(fd, UVCIOC_CTRL_QUERY, &xquery);

/* UVC quirks — 비표준 카메라 대응 */
/* uvcvideo 드라이버의 quirks 모듈 파라미터 */
/* 또는 커널 소스의 uvc_ids[] 테이블에 추가 */
$ modprobe uvcvideo quirks=0x80   /* UVC_QUIRK_FORCE_Y8 등 */

UVC Gadget (디바이스 측)

Linux의 USB Gadget 프레임워크를 사용하면 SBC(Single Board Computer)를 USB 카메라로 동작시킬 수 있습니다:

# UVC Gadget 설정 (ConfigFS 기반)
$ mkdir -p /sys/kernel/config/usb_gadget/uvc
$ cd /sys/kernel/config/usb_gadget/uvc

# USB 디스크립터 설정
$ echo 0x1d6b > idVendor     # Linux Foundation
$ echo 0x0104 > idProduct    # Multifunction Composite Gadget

# UVC 기능 추가
$ mkdir -p functions/uvc.usb0
$ mkdir -p functions/uvc.usb0/streaming/uncompressed/u/1080p
$ echo 1920 > functions/uvc.usb0/streaming/uncompressed/u/1080p/wWidth
$ echo 1080 > functions/uvc.usb0/streaming/uncompressed/u/1080p/wHeight
$ echo 333333 > functions/uvc.usb0/streaming/uncompressed/u/1080p/dwDefaultFrameInterval

# uvc-gadget 도구로 V4L2 소스 → USB 출력
$ uvc-gadget -d /dev/video0 -u /dev/video1

Device Tree 바인딩

임베디드 카메라 시스템에서 센서, CSI-2 리시버, ISP의 연결은 Device Tree로 기술합니다.

센서 DT 바인딩 예제

/* IMX219 센서 DT 바인딩 */
&i2c1 {
    imx219: sensor@10 {
        compatible = "sony,imx219";
        reg = <0x10>;
        clocks = <&clk_24mhz>;
        clock-names = "xclk";

        /* 전원 */
        VANA-supply  = <®_2v8>;
        VDIG-supply  = <®_1v8>;
        VDDL-supply  = <®_1v2>;

        /* GPIO 리셋 */
        reset-gpios = <&gpio1 5 GPIO_ACTIVE_LOW>;

        /* CSI-2 포트 */
        port {
            imx219_out: endpoint {
                remote-endpoint = <&csi_in>;
                data-lanes = <1 2>;    /* 2 데이터 레인 */
                clock-lanes = <0>;
                link-frequencies = /bits/ 64 <456000000>;
            };
        };
    };
};

CSI-2 리시버 바인딩 예제

/* CSI-2 리시버 DT 바인딩 */
csi2: csi@fe800000 {
    compatible = "rockchip,rk3588-mipi-csi2";
    reg = <0x0 0xfe800000 0x0 0x10000>;
    clocks = <&cru SCLK_CSI2>;
    clock-names = "pclk";

    ports {
        #address-cells = <1>;
        #size-cells = <0>;

        /* sink: 센서 연결 */
        port@0 {
            reg = <0>;
            csi_in: endpoint {
                remote-endpoint = <&imx219_out>;
                data-lanes = <1 2>;
            };
        };

        /* source: ISP 연결 */
        port@1 {
            reg = <1>;
            csi_out: endpoint {
                remote-endpoint = <&isp_in>;
            };
        };
    };
};

멀티 카메라 DT 바인딩

두 개 이상의 카메라 센서를 연결하는 경우 각 CSI-2 포트를 별도로 기술합니다:

/* 듀얼 카메라 설정: IMX219 + OV5640 */
&i2c1 {
    imx219: sensor@10 {
        compatible = "sony,imx219";
        reg = <0x10>;
        port {
            imx219_out: endpoint {
                remote-endpoint = <&csi0_in>;
                data-lanes = <1 2>;
            };
        };
    };
};

&i2c2 {
    ov5640: sensor@3c {
        compatible = "ovti,ov5640";
        reg = <0x3c>;
        port {
            ov5640_out: endpoint {
                remote-endpoint = <&csi1_in>;
                data-lanes = <1 2>;
            };
        };
    };
};

/* CSI-2 리시버 0 */
&csi0 {
    ports {
        port@0 {
            csi0_in: endpoint {
                remote-endpoint = <&imx219_out>;
                data-lanes = <1 2>;
            };
        };
    };
};

/* CSI-2 리시버 1 */
&csi1 {
    ports {
        port@0 {
            csi1_in: endpoint {
                remote-endpoint = <&ov5640_out>;
                data-lanes = <1 2>;
            };
        };
    };
};

플래시 LED DT 바인딩

/* 카메라 플래시 LED 바인딩 */
flash_led: led-controller@63 {
    compatible = "ti,lm3646";
    reg = <0x63>;
    #address-cells = <1>;
    #size-cells = <0>;

    led@0 {
        reg = <0>;
        function = LED_FUNCTION_FLASH;
        color = <LED_COLOR_ID_WHITE>;
        led-max-microamp = <250000>;
        flash-max-microamp = <1000000>;
        flash-max-timeout-us = <1000000>;
    };
};

/* 센서에서 플래시 참조 */
&imx219 {
    flash-leds = <&flash_led 0>;
};

V4L2 fwnode 파싱 API

/* 드라이버에서 DT endpoint 파싱 */
struct v4l2_fwnode_endpoint ep = {
    .bus_type = V4L2_MBUS_CSI2_DPHY,
};
struct fwnode_handle *fwnode;

fwnode = fwnode_graph_get_endpoint_by_id(dev_fwnode(dev), 0, 0, 0);
v4l2_fwnode_endpoint_alloc_parse(fwnode, &ep);

/* 파싱 결과 */
ep.bus.mipi_csi2.num_data_lanes;    /* 레인 수 */
ep.bus.mipi_csi2.data_lanes[0];     /* 레인 매핑 */
ep.link_frequencies[0];             /* 링크 주파수 */
fwnode_handle_put(fwnode);

유저스페이스 도구

v4l2-ctl

v4l2-ctl은 V4L2 디바이스의 범용 CLI 도구입니다 (v4l-utils 패키지):

# 디바이스 정보 확인
$ v4l2-ctl -d /dev/video0 --all

# 지원 포맷 열거
$ v4l2-ctl -d /dev/video0 --list-formats-ext

# 포맷/해상도 설정
$ v4l2-ctl -d /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=YUYV

# 프레임 캡처 (10프레임을 파일로)
$ v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=10 --stream-to=capture.raw

# 컨트롤 조회/설정
$ v4l2-ctl -d /dev/video0 --list-ctrls
$ v4l2-ctl -d /dev/video0 --set-ctrl=brightness=180,contrast=200

# DMABUF 내보내기 캡처
$ v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=1 --stream-to=frame.raw --stream-dmabuf

media-ctl

# 토폴로지 텍스트 출력
$ media-ctl -d /dev/media0 -p

# 토폴로지 DOT 그래프 생성
$ media-ctl -d /dev/media0 --print-dot | dot -Tpng -o topology.png

# 링크 활성화
$ media-ctl -l '"sensor":0 -> "csi-rx":0 [1]'

# 서브디바이스 포맷 설정
$ media-ctl -V '"sensor":0 [fmt:SGRBG10_1X10/1920x1080 field:none]'

v4l2-compliance (적합성 테스트)

# 전체 적합성 테스트 실행
$ v4l2-compliance -d /dev/video0

# 스트리밍 테스트 포함
$ v4l2-compliance -d /dev/video0 -s

# Media Controller 테스트
$ v4l2-compliance -m /dev/media0

# 서브디바이스 테스트
$ v4l2-compliance -d /dev/v4l-subdev0 -e

# 상세 출력 모드
$ v4l2-compliance -d /dev/video0 -v -s

# 결과 해석
# Total for device /dev/video0: 95, Succeeded: 93, Failed: 2, Warnings: 0

주요 v4l2-compliance 테스트 카테고리:

v4l2-ctl 고급 사용법

# 지원 해상도와 프레임 레이트 열거
$ v4l2-ctl -d /dev/video0 --list-framesizes=MJPG
# Size: Discrete 640x480
# Size: Discrete 1280x720
# Size: Discrete 1920x1080

$ v4l2-ctl -d /dev/video0 --list-frameintervals=width=1920,height=1080,pixelformat=YUYV
# Interval: Discrete 0.033s (30.000 fps)

# 프레임 레이트 설정
$ v4l2-ctl -d /dev/video0 --set-parm=60

# DMA-BUF 모드 캡처
$ v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=1 \
    --export-device=/dev/video1 --stream-dmabuf

# Selection (크롭) 설정
$ v4l2-ctl -d /dev/video0 --set-selection=target=crop,left=100,top=100,width=640,height=480

# 연속 캡처 + 프레임 레이트 측정
$ v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=300 --verbose 2>&1 | tail -5
# 300 frames captured, average fps: 29.97

# 로그 상태 덤프 (dmesg에 출력)
$ v4l2-ctl -d /dev/video0 --log-status

# EDID 관련 (HDMI 캡처 카드)
$ v4l2-ctl -d /dev/video0 --get-edid
$ v4l2-ctl -d /dev/video0 --set-edid=file=edid.bin

libcamera / GStreamer / FFmpeg 연동

# libcamera — 복잡한 카메라 파이프라인 추상화
$ cam --list              # 카메라 열거
$ cam -c1 --capture=10    # 10프레임 캡처
$ cam -c1 --capture=10 --file  # 파일로 저장

# GStreamer — V4L2 소스 파이프라인
$ gst-launch-1.0 v4l2src device=/dev/video0 ! \
    video/x-raw,width=1920,height=1080 ! videoconvert ! autovideosink

# GStreamer — V4L2 M2M 하드웨어 디코딩
$ gst-launch-1.0 filesrc location=video.mp4 ! qtdemux ! h264parse ! \
    v4l2slh264dec ! videoconvert ! autovideosink

# GStreamer — V4L2 하드웨어 인코딩 + 스트리밍
$ gst-launch-1.0 v4l2src device=/dev/video0 ! \
    video/x-raw,width=1920,height=1080,framerate=30/1 ! \
    v4l2h264enc extra-controls="controls,video_bitrate=4000000" ! \
    h264parse ! mpegtsmux ! udpsink host=192.168.1.100 port=5000

# GStreamer — libcamerasrc 사용 (ISP 파이프라인 자동 구성)
$ gst-launch-1.0 libcamerasrc ! \
    video/x-raw,width=1920,height=1080 ! videoconvert ! autovideosink

# FFmpeg — V4L2 캡처 + 소프트웨어 인코딩
$ ffmpeg -f v4l2 -video_size 1920x1080 -i /dev/video0 -c:v libx264 output.mp4

# FFmpeg — V4L2 M2M 하드웨어 인코더 (stateful 코덱)
$ ffmpeg -f v4l2 -i /dev/video0 -c:v h264_v4l2m2m -b:v 4M output.mp4

# FFmpeg — V4L2 M2M 하드웨어 디코딩
$ ffmpeg -hwaccel v4l2m2m -i input.mp4 -f rawvideo output.yuv

GStreamer V4L2 요소(Element) 확인

# V4L2 관련 GStreamer 요소 목록
$ gst-inspect-1.0 | grep v4l2
v4l2:  v4l2src: Video (video4linux2) Source
v4l2:  v4l2sink: Video (video4linux2) Sink
v4l2:  v4l2h264dec: V4L2 H.264 Decoder
v4l2:  v4l2h264enc: V4L2 H.264 Encoder
v4l2:  v4l2slh264dec: V4L2 Stateless H.264 Decoder
v4l2:  v4l2h265dec: V4L2 H.265 Decoder
...

# V4L2 소스 속성 확인
$ gst-inspect-1.0 v4l2src
# Properties:
#   device: /dev/video0 (기본값)
#   io-mode: mmap/userptr/dmabuf/dmabuf-import
#   extra-controls: V4L2 컨트롤 설정

Python에서 V4L2 사용

# v4l2-python3 또는 PyV4L2Camera 사용 예
import subprocess
import struct
import fcntl

# ioctl 래퍼를 통한 직접 접근
VIDIOC_QUERYCAP = 0x80685600

with open('/dev/video0', 'rb') as f:
    # QUERYCAP 호출
    buf = bytearray(104)
    fcntl.ioctl(f, VIDIOC_QUERYCAP, buf)
    driver = buf[0:16].decode('utf-8').strip('\x00')
    card = buf[16:48].decode('utf-8').strip('\x00')
    print(f"Driver: {driver}, Card: {card}")

# OpenCV로 V4L2 캡처
import cv2
cap = cv2.VideoCapture(0, cv2.CAP_V4L2)
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1920)
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 1080)
cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc('M','J','P','G'))
ret, frame = cap.read()
cap.release()

디버깅과 프로파일링(Profiling)

커널 디버그 메시지

/* 드라이버 내 디버그 출력 */
v4l2_dbg(1, debug, &mydev->v4l2_dev, "format: %dx%d\\n", w, h);
v4l2_info(&mydev->v4l2_dev, "device registered\\n");
v4l2_err(&mydev->v4l2_dev, "failed to start streaming\\n");
v4l2_warn(&mydev->v4l2_dev, "format adjusted\\n");

/* 모듈 파라미터로 디버그 레벨 제어 */
static int debug;
module_param(debug, int, 0644);
MODULE_PARM_DESC(debug, "debug level (0=off, 1=info, 2=verbose)");

/* 서브디바이스 디버그 */
v4l2_subdev_dbg(1, debug, sd, "setting format\\n");

/* 런타임에 디버그 활성화 */
$ echo 2 > /sys/module/<driver>/parameters/debug

ftrace를 이용한 V4L2 ioctl 추적

V4L2는 ftrace tracepoint를 제공하여 ioctl 호출을 상세히 추적할 수 있습니다:

# V4L2 tracepoint 확인
$ ls /sys/kernel/debug/tracing/events/v4l2/
v4l2_dqbuf  v4l2_qbuf  vb2_v4l2_buf_done  vb2_v4l2_buf_queue  ...

# 모든 V4L2 tracepoint 활성화
$ echo 1 > /sys/kernel/debug/tracing/events/v4l2/enable

# 특정 이벤트만 추적 (버퍼 QBUF/DQBUF)
$ echo 1 > /sys/kernel/debug/tracing/events/v4l2/v4l2_qbuf/enable
$ echo 1 > /sys/kernel/debug/tracing/events/v4l2/v4l2_dqbuf/enable

# 추적 시작 + 캡처 실행
$ echo 1 > /sys/kernel/debug/tracing/tracing_on
$ v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=10

# 추적 결과 확인
$ cat /sys/kernel/debug/tracing/trace
# v4l2-ctl-1234: v4l2_qbuf: minor=0 index=0 type=1 bytesused=0 flags=0x2000
# IRQ-56:       vb2_v4l2_buf_done: minor=0 index=0 type=1 bytesused=460800
# v4l2-ctl-1234: v4l2_dqbuf: minor=0 index=0 type=1 bytesused=460800 flags=0x2001

# 추적 중지
$ echo 0 > /sys/kernel/debug/tracing/tracing_on

perf를 이용한 성능 분석

# V4L2 tracepoint 기반 성능 분석
$ perf trace -e v4l2:* v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=100

# 프레임 지연 시간 측정 (QBUF → DQBUF 간격)
$ perf trace -e v4l2:v4l2_qbuf,v4l2:v4l2_dqbuf --duration 5 -p $(pidof my_app)

# DMA 관련 시스템 콜 성능 분석
$ perf stat -e 'syscalls:sys_enter_ioctl' -p $(pidof my_app) sleep 5

# IRQ 처리 시간 분석
$ perf record -g -e irq:irq_handler_entry,irq:irq_handler_exit sleep 5
$ perf report

debugfs 엔트리

많은 V4L2 드라이버가 debugfs를 통해 내부 상태를 노출합니다:

# vb2 큐 상태 확인 (커널 6.x)
$ cat /sys/kernel/debug/video0/vb2_queue
# type: 1 (VIDEO_CAPTURE)
# io_modes: 5 (MMAP|DMABUF)
# min_queued_buffers: 1
# queued_count: 3
# owned_by_drv_count: 2
# streaming: 1

# UVC 디버그 상세 활성화
$ echo 0xffff > /sys/module/uvcvideo/parameters/trace
$ dmesg | grep uvcvideo

# Media Controller 토폴로지 덤프
$ media-ctl -d /dev/media0 -p

# rkisp1 ISP 통계 확인
$ cat /sys/kernel/debug/rkisp1/input_status

자주 발생하는 문제와 해결

디버깅 도구 요약

성능 문제 진단 체크리스트

Request API 상세

Request API는 V4L2의 원자적 파라미터 적용 메커니즘입니다. 하나의 Request에 버퍼와 컨트롤을 묶어서 하드웨어에 동시 적용할 수 있습니다. 주로 stateless 코덱과 복잡한 카메라 파이프라인에서 사용됩니다.

Request 수명주기

드라이버 측 Request 구현

/* Request API 지원 드라이버 설정 */
static const struct media_device_ops my_media_ops = {
    .req_alloc    = vb2_request_alloc,      /* vb2 제공 헬퍼 */
    .req_validate = my_request_validate,   /* 커스텀 검증 */
    .req_queue    = vb2_m2m_request_queue, /* M2M 헬퍼 */
};

/* Request 검증: 필수 컨트롤이 모두 설정되었는지 확인 */
static int my_request_validate(struct media_request *req)
{
    struct media_request_object *obj;
    int has_sps = 0, has_pps = 0;

    list_for_each_entry(obj, &req->objects, list) {
        /* 컨트롤 객체 검사 */
        if (obj->ops == &v4l2_ctrl_request_ops) {
            /* 필수 H.264 파라미터 존재 확인 */
        }
    }

    return vb2_request_validate(req);
}

/* device_run에서 Request의 컨트롤 적용 */
static void my_device_run(void *priv)
{
    struct my_ctx *ctx = priv;
    struct vb2_v4l2_buffer *src, *dst;

    src = v4l2_m2m_next_src_buf(ctx->m2m_ctx);
    dst = v4l2_m2m_next_dst_buf(ctx->m2m_ctx);

    /* Request의 컨트롤 값을 하드웨어에 적용 */
    v4l2_ctrl_request_setup(src->vb2_buf.req_obj.req,
                            &ctx->ctrl_handler);

    /* 하드웨어에 작업 전달 */
    my_hw_start(ctx, src, dst);
}

/* IRQ 완료 시 Request 정리 */
static void my_irq_done(struct my_ctx *ctx)
{
    struct vb2_v4l2_buffer *src, *dst;

    src = v4l2_m2m_src_buf_remove(ctx->m2m_ctx);
    dst = v4l2_m2m_dst_buf_remove(ctx->m2m_ctx);

    /* Request 컨트롤 정리 */
    v4l2_ctrl_request_complete(src->vb2_buf.req_obj.req,
                               &ctx->ctrl_handler);

    v4l2_m2m_buf_done(src, VB2_BUF_STATE_DONE);
    v4l2_m2m_buf_done(dst, VB2_BUF_STATE_DONE);
    v4l2_m2m_job_finish(ctx->m2m_dev, ctx->m2m_ctx);
}

주요 Kconfig 옵션

V4L2 드라이버 개발 베스트 프랙티스(Best Practices)

업스트림 제출 체크리스트

Linux 커널 미디어 서브시스템에 드라이버를 제출할 때 필수적으로 확인해야 할 항목:

잠금(Lock)킹(Locking) 패턴

V4L2 드라이버의 올바른 잠금킹 전략:

/* 1. video_device.lock — ioctl 직렬화 */
/*    video_device에 mutex를 설정하면 V4L2 코어가 모든 ioctl을 직렬화 */
cam->vdev.lock = &cam->mutex;

/* 2. vb2_queue.lock — 버퍼 ioctl 직렬화 */
/*    video_device.lock과 같은 mutex를 사용하는 것이 일반적 */
cam->queue.lock = &cam->mutex;

/* 3. spinlock — IRQ 핸들러와 공유 데이터 보호 */
/*    buf_list 등 IRQ 컨텍스트에서 접근하는 데이터 */
spin_lock_irqsave(&cam->slock, flags);
list_add_tail(&buf->list, &cam->buf_list);
spin_unlock_irqrestore(&cam->slock, flags);

/* 4. v4l2_ctrl_handler — 컨트롤 프레임워크 내부 락 */
/*    v4l2_ctrl_handler_setup()은 lock 내부에서 호출 금지 */
/*    s_ctrl 콜백은 handler->lock 하에 호출됨 */

/* 5. 데드락 방지: wait_prepare/wait_finish */
/*    vb2가 DQBUF에서 대기할 때 mutex를 해제하는 헬퍼 */
static const struct vb2_ops my_vb2_ops = {
    .wait_prepare = vb2_ops_wait_prepare,  /* queue->lock 해제 */
    .wait_finish  = vb2_ops_wait_finish,   /* queue->lock 획득 */
    ...
};

흔한 실수와 방지책

테스트 전략

# 1. 기본 적합성 테스트
$ v4l2-compliance -d /dev/video0 -v
$ v4l2-compliance -d /dev/video0 -s    # 스트리밍 포함

# 2. Media Controller 테스트
$ v4l2-compliance -m /dev/media0

# 3. 스트레스 테스트 (장시간 캡처)
$ v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=10000

# 4. 다양한 해상도/포맷 테스트
$ for fmt in YUYV NV12 MJPG; do
    v4l2-ctl -d /dev/video0 --set-fmt-video=pixelformat=$fmt
    v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=10
  done

# 5. KASAN/UBSAN 활성화 빌드로 메모리 오류 검출
# CONFIG_KASAN=y, CONFIG_UBSAN=y

# 6. lockdep 활성화로 데드락 검출
# CONFIG_PROVE_LOCKING=y

# 7. vivid 가상 드라이버로 참조 구현 비교
$ modprobe vivid
$ v4l2-compliance -d /dev/video0   # 모든 테스트 통과해야 함

CI/자동화 테스트

V4L2 드라이버 개발에 활용할 수 있는 자동화 테스트 환경:

#!/bin/bash
# V4L2 드라이버 자동 테스트 스크립트

set -e
DEVICE=${1:-/dev/video0}
MEDIA=${2:-/dev/media0}

echo "=== V4L2 드라이버 자동 테스트 ==="

# 1. 적합성 테스트
echo "[1/5] v4l2-compliance 실행..."
v4l2-compliance -d $DEVICE -s 2>&1 | tee compliance.log
FAILED=$(grep "Failed:" compliance.log | awk '{print $2}')
if [ "$FAILED" != "0" ]; then
    echo "경고: $FAILED 개 테스트 실패"
fi

# 2. 지원 포맷 확인
echo "[2/5] 포맷 열거..."
v4l2-ctl -d $DEVICE --list-formats-ext

# 3. 각 포맷으로 10프레임 캡처 테스트
echo "[3/5] 포맷별 캡처 테스트..."
for FMT in $(v4l2-ctl -d $DEVICE --list-formats | grep "'" | awk -F"'" '{print $2}'); do
    echo "  테스트: $FMT"
    v4l2-ctl -d $DEVICE --set-fmt-video=pixelformat=$FMT \
        --stream-mmap --stream-count=10 2>/dev/null || echo "  $FMT 실패"
done

# 4. 컨트롤 테스트
echo "[4/5] 컨트롤 테스트..."
v4l2-ctl -d $DEVICE --list-ctrls

# 5. Media Controller 테스트 (있는 경우)
if [ -e "$MEDIA" ]; then
    echo "[5/5] Media Controller 테스트..."
    v4l2-compliance -m $MEDIA 2>&1 | tee media-compliance.log
    media-ctl -d $MEDIA -p
fi

echo "=== 테스트 완료 ==="

커널 버전 호환성 참고

외부 참고 자료

V4L2 API 빠른 참조

커널 API 요약

유저스페이스 ioctl 빠른 참조

서브디바이스 ioctl 빠른 참조

Media Controller ioctl 빠른 참조

최신 동향 (2025-2026)

커널 6.10~6.18 사이의 V4L2 서브시스템은 (1) Intel IPU 메인라인화, (2) AV1 stateless 디코더 성숙, (3) libcamera 기반 SoftISP 확산, (4) Rust 기반 코덱 재작성의 네 축으로 요약됩니다. 각 항목은 out-of-tree 스택이 mainline으로 수렴하고, 유저스페이스 표준(libcamera, GStreamer)이 V4L2 위에 단일화되는 추세를 반영합니다.

Intel IPU6/IPU7 mainline — 노트북 웹캠의 전환점

과거 Intel Tiger Lake 이후 노트북(MIPI CSI-2 내장 웹캠)은 out-of-tree ipu6-drivers, 독점 icamerasrc(GStreamer 플러그인), 바이너리 IPA 튜닝 파일에 의존해야 했습니다. 이는 보안 업데이트/커널 업그레이드마다 트리를 재빌드해야 하는 운영 부담을 야기했습니다. 2025년 커널 6.10 이후 상황이 변했습니다:

AV1 Stateless 디코더 안정화

AV1은 H.264/HEVC보다 훨씬 복잡한 신택스(OBU, Tile Group, Film Grain)를 가지므로, 커뮤니티는 V4L2 Control로 파라미터를 정의하는 Stateless 모델을 채택했습니다. Collabora가 주도한 Rockchip RK3588 rkvdec-av1 드라이버는 1년에 걸친 v10까지의 리뷰 끝에 커널 6.5에 병합되었고, 이후 지속적으로 안정화되고 있습니다:

/* include/uapi/linux/v4l2-controls.h (커널 6.5+) */
#define V4L2_CID_STATELESS_AV1_SEQUENCE         (V4L2_CID_CODEC_STATELESS_BASE + 500)
#define V4L2_CID_STATELESS_AV1_FRAME            (V4L2_CID_CODEC_STATELESS_BASE + 501)
#define V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY (V4L2_CID_CODEC_STATELESS_BASE + 502)
#define V4L2_CID_STATELESS_AV1_FILM_GRAIN       (V4L2_CID_CODEC_STATELESS_BASE + 505)

/* 대응 하드웨어 */
 *  - Rockchip RK3588 (rkvdec-av1, 커널 6.5+, 최대 4K@60 10-bit)
 *  - MediaTek MT8195 (mtk-vcodec AV1, 커널 6.5+)
 *  - Rockchip RK3566/3568 rkvdec2 (커널 6.15~ 준비 중)
 *  - Qualcomm Venus AV1 (커널 6.14+, 일부 SM8550/8650)

유저스페이스에서는 GStreamer 1.28(v4l2av1dec, v4l2slav1dec), FFmpeg 7.1+의 --enable-v4l2-request 빌드, Chromium의 V4L2StatelessVideoDecoderBackend가 이 하드웨어를 활용합니다.

libcamera — V4L2 위의 사실상 표준 카메라 API

libcamera는 V4L2 Raw + Media Controller 그래프를 내부에서 조율하여 애플리케이션에 단일 카메라 API를 제공합니다. 2025년 릴리스 현황:

Rust V4L2 — 메모리 안전성 도입

커널 6.18 사이클에서 VP9 stateless 디코더 코어 로직을 Rust로 재작성하는 RFC가 제출되었습니다. V4L2 서브시스템 최초의 Rust 코드이며, 목표는:

• 메모리 안전성 — 디코더 상태 머신은 악의적 비트스트림에 노출되므로, Rust의 소유권(Ownership) 모델로 use-after-free/OOB를 구조적으로 차단합니다.
• 테스트 용이성 — Rust의 단위 테스트(#[test])로 비트스트림 파서를 커널 밖에서도 검증합니다.
• 점진 도입 — C로 구현된 H/W 인터페이스 레이어는 유지하고, 파서/상태 머신만 Rust 트레이트(Trait)로 추상화하여 기존 hantro, rkvdec 드라이버가 공유합니다.

이 작업이 병합되면 향후 AV1 Film Grain 합성과 HEVC RExt(Range Extension) 구현도 Rust로 작성될 가능성이 높습니다. Android의 Cuttlefish 에뮬레이터가 초기 검증 타겟입니다.

도구 체인 정비 요약

참고 링크

관련 문서

이 주제와 관련된 다른 문서를 더 깊이 이해하고 싶다면 다음을 참고하세요.

• 디바이스 드라이버 — 디바이스 드라이버 모델과 probe/remove 수명주기
• DMA — DMA 엔진, DMA-BUF, 제로카피 버퍼 공유
• I2C / SPI / GPIO — I2C 센서 드라이버, SPI/GPIO 버스 프레임워크
• 인터럽트(Interrupt) 처리 — IRQ 핸들링, threaded IRQ
• 전원 관리 — 런타임 PM, 시스템 suspend/resume
• IOMMU — DMA 주소 변환(Address Translation), scatter-gather 매핑
• Device Tree — DT 바인딩, 센서/CSI 포트 기술
• 디버깅 — ftrace, perf, debugfs 기반 드라이버 디버깅
• PCI/PCIe — PCIe 캡처 카드 드라이버