UserGuideOmap35xCaptureDriver PSP 03.00.00.04

Introduction

The camera ISP is a key component for imaging and video applications such as video preview, video record, and still-image capture with or without digital zooming.
The camera ISP provides the system interface and the processing capability to connect RAW image-sensor modules and video decoders to the OMAP35x device.
The capture module consists of the following interfaces:

• One S-video SD input in BT.656 format.
• One Composite SD input in BT.656 format.

Both these video inputs are connected to one TVP5146 decoder and the application can select between these two inputs using standard V4L2 interface.

NOTE: Only one input can be captured or selected at any given point of time.

The following figure shows the basic block diagram of capture interface.

Capture Driver Component Overview

The following figure shows the physical connection and inputs for TVP5146 decoder.

Capture Physical Input Interface

The V4L2 Capture driver model is used for capture module. The V4L2 driver model is widely used across many platforms in the Linux community. V4L2 provides good streaming support and support for many buffer formats. It also has its own buffer management mechanism that can be used.

References

• OMAP35x Camera Interface Subsystem (ISP) TRM

Author: Texas Instruments, Inc. Literature Number: SPRUFA2

• OMAP35x Memory Management Units (MMUs)TRM

Author: Texas Instruments, Inc. Literature Number: SPRUFF5

• Video for Linux Two API Specification

Author: Michael H Schimek Version: 0.23

Acronyms & Definitions

Capture Driver: Acronyms

Acronym	Definition
MMDC	Mass Market Daughter Card/Customer Daughter Card
3A	Auto White Balance, Auto Focus, Auto Exposure
API	Application Programming Interface
CCDC	Input interface block of ISP
DMA	Direct Memory Access
I/O	Input & Output
IOCTL	Input & Output Control
MMU	Memory Management Unit
V4L2	Video for Linux specification version 2
YUV	Luminance + 2 Chrominance Difference Signals (Y, Cr, Cb) Color Encoding

Features 

The ISP Capture Driver provides the following features:

• Supports one software channel of capture and a corresponding device node (/dev/video0) is created.
• Supports single I/O instance and multiple control instances.
• Supports buffer access mechanism through memory mapping and user pointers.
• Supports dynamic switching among input interfaces with some necessary restrictions wherever applicable.
• Supports NTSC and PAL standard on Composite and S-Video interfaces.
• Supports 8-bit BT.656 capture in UYVY and YUYV interleaved formats.
• Supports standard V4L2 IOCTLs to get/set various control parameters like brightness, contrast, saturation, hue and auto gain control.
• TVP5146 (TVP514x) decoder driver module can be used statically or dynamically (insmod and rmmod supported).
• In USERPTR mode of operation both malloc'd and IO mapped buffers are supported.
• The camera ISP driver supports both static into kernel and modular build.

Architecture 

System Diagram

Following block diagram shows basic architecture of the ISP Capture Driver.

Capture Driver Basic Architecture

The system architecture diagram illustrates the software components that are relevant to the Camera Driver. Some components are outside the scope of this design document. The following is a brief description of each component in the figure.

Camera Applications:
Camera applications refer to any application that accesses the device node that is served by the Camera Driver. These applications are not in the scope of this design. They are here to present the environment in which the Camera Driver is used.
V4L2 Subsystem:
The Linux V4L2 subsystem is used as an infrastructure to support the operation of the Camera Driver. Camera applications mainly use the V4L2 API to access the Camera Driver functionality. A Linux 2.6 V4L2 implementation is used in order to support the standard features that are defined in the V4L2 specification.
Video Buffer Library:
This library comes with V4L2. It provides helper functions to cleanly manage the video buffers through a video buffer queue object.
Camera Driver:
The Camera Driver allows capturing video through an external decoder. It is a V4L2-compliant driver with addition of an OMAP35x ISP hardware feature. This driver conforms to the Linux driver model for power management. The camera driver is registered to the V4L2 layer as a master device driver. Any slave decoder driver added to the V4L2 layer will be attached to this driver through the new V4L2 master-slave interface layer. The current implementation supports only one slave device.
Decoder Driver:
The Camera Driver is designed to be OMAP35x dependent, but platform and board independent. It is the decoder driver that manages the board connectivity. A decoder driver must implement the new V4L2 master-slave interface. It should register to the V4L2 layer as a slave device. Changing a decoder requires implementation of a new decoder driver; it does not require changing the Camera Driver. Each decoder driver exports a set of IOCTLs to the master device through function pointers.
ISP Library:
The ISP library exports APIs to configure ISP module and clocks to the sensor/decoder. It is the central interrupt handler where callback routines for ISP interrupts are handled. This also manages the video buffers.
CCDC library:
CCDC is a HW block in Camera ISP which acts as a data input port. It receives data from the sensor/decoder through parallel or serial interface. The CCDC library exports API to configure CCDC module. It is configured by the ISP driver based on the sensor/decoder attached and desired output from the camera driver.
MMU library:
MMU is a HW block in Camera ISP that handles the translation from virtual into physical addresses. The camera subsystem issues virtual addresses to the ISP MMU and the ISP MMU translates these virtual addresses into physical addresses to access the actual memory. Using this the camera driver captures video data in fragmented physical memory without moving data. The MMU library exports API to configure MMU module.
Preview library:
Preview is a HW block in Camera ISP which is responsible for image processing and color conversion. It has HW blocks for image processing algorithms. Preview library allows camera driver to configure, enable and disable the individual HW blocks in the preview module. This module will be used only when a RAW sensor is connected to the ISP.
Resizer library:
Resizer is a HW block in Camera ISP which is responsible for image downscaling and upscaling. It has HW filters which resize the input image based on configuration. Resizer library allows camera driver to query and configure the resizer module. Resizer in OMAP35x ISP supports resizing ratios from 1/4 to 4. Resizer also has multipass approach which can be used to overcome this limitation. Current camera driver only supports on the fly mode of operation. In this mode image is taken from sensor and passed to application without any memory to memory operations in ISP and so multipass resizer operations are not supported.
H3A library:
H3A is a HW block in Camera ISP which is responsible for collecting image statistics that can be used by other algorithms. It generates auto focus, auto white balance, auto exposure and histogram statistics. H3A library allows user space algorithms to configure and request these statistics through custom IOCTLs.

Software Design Interfaces

Opening and Closing of driver

The device can be opened using open call from the application, with the device name and mode of operation as parameters. Application should open the driver in blocking mode. In this mode, DQBUF IOCTL will not return until an empty frame is available.

/* Open a video capture logical channel in blocking mode */
fd = open("/dev/video0", O_RDWR);
if (fd == -1) {
    perror("failed to open Capture device\n");
    return -1;
}
/* closing of channel */
close (fd);

Buffer Management

ISP Capture driver can work with physically non-contiguous buffers. It uses the ISP MMU to capture data to buffers scattered to a set of page frames. Hence, in user pointer mode the application can allocate buffers in user space, which need not be physically contiguous, and pass this directly to driver for capture operation. The only restriction for the user buffer is that, the buffer should be aligned to 32 bytes boundary.
The driver supports both memory usage modes:

1. Memory map buffer mode
2. User Pointer mode

In Memory map buffer mode, application can request memory from the driver by calling VIDIOC_REQBUFS IOCTL. In user buffer mode, application needs to allocate memory using some other mechanism in user space like malloc or memalign. In driver buffer mode, maximum number of buffers is limited to VIDEO_MAX_FRAME (defined in driver header files) and is limited by the available memory in the kernel.
The main steps that the application must perform for buffer allocation are:

1. Allocating Memory
2. Getting Physical Address
3. Mapping Kernel Space Address to User Space

Allocating Memory
This IOCTL is used to allocate memory for frame buffers. This is the necessary IOCTL for streaming IO. It has to be called for both driver buffer mode and user buffer mode. Using this IOCTL, driver will know whether driver buffer mode or user buffer mode will be used.
Ioctl: VIDIOC_REQBUFS
It takes a pointer to instance of v4l2_requestbuffers structure as an argument. User should specify buffer type as V4L2_BUF_TYPE_VIDEO_CAPTURE, number of buffers, and memory type V4L2_MEMORY_MMAP, V4L2_MEMORY_USERPTR at the time of buffer allocation.
Constraint: This IOCTL can be called only once from the application. This IOCTL is necessary IOCTL.

Example:

/* structure to store buffer request parameters */
struct v4l2_requestbuffers reqbuf;
reqbuf.count = numbuffers;
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
reqbuf.memory = V4L2_MEMORY_MMAP;
ret = ioctl(fd, VIDIOC_REQBUFS, &reqbuf);
if (ret < 0) {
    printf("cannot allocate memory\n");
    close(fd);
    return -1;
}
printf("Number of buffers allocated = %d\n", reqbuf.count);

Getting Physical Address
This IOCTL is used to query buffer information like buffer size and buffer physical address. This physical address is used in mmapping the buffers. This IOCTL is necessary for driver buffer mode as it provides the physical address of buffers, which are used to mmap system call the buffers.
Ioctl: VIDIOC_QUERYBUF
It takes a pointer to instance of v4l2_buffer structure as an argument. User has to specify buffer type as V4L2_BUF_TYPE_VIDEO_CAPTURE, buffer index, and memory type (V4L2_MEMORY_MMAP) at the time of querying.
Example:

/* allocate buffer by VIDIOC_REQBUFS */
/* structure to query the physical address of allocated buffer */
struct v4l2_buffer buffer;
buffer.index = 0; /* buffer index for quering -0 */
buffer.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buffer.memory = V4L2_MEMORY_MMAP;
if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < -1) {
    printf("buffer query error.\n");
    close(fd);
    exit(-1);
}
The buffer.m.offset will contain the physical address returned from driver.

Mapping Kernel Space Address to User Space
Mapping the kernel buffer to the user space can be done via mmap. This is only required for MMAP buffer mode. User can pass buffer size and physical address of buffer for getting the user space address.
Example:

/* allocate buffer by VIDIOC_REQBUFS */
/* query the buffer using VIDIOC_QUERYBUF */
/* addr hold the user space address */
int addr;
addr = mmap(NULL, buffer.size,PROT_READ | PROT_WRITE, MAP_SHARED, fd, buffer.m.offset);
/* buffer.m.offset is same as returned from VIDIOC_QUERYBUF */

Query Capabilities

This IOCTL is used to verify kernel devices compatibility with V4L2 specification and to obtain information about individual hardware capabilities. In this case, it will return capabilities provided by ISP capture driver and current decoder driver.
Ioctl: VIDIOC_QUERYCAP
Capabilities can be video capture V4L2_CAP_VIDEO_CAPTURE and streaming V4L2_CAP_STREAMING. It takes pointer to v4l2_capability structure as an argument. Capabilities can be accessed by capabilities field in the v4l2_capability structure.
Example:

struct v4l2_capability capability;
ret = ioctl(fd, VIDIOC_QUERYCAP, &capability);
if (ret < 0) {
    printf("Cannot do QUERYCAP\n");
    return -1;
}
if (capability.capabilities & V4L2_CAP_VIDEO_CAPTURE) {
    printf("Capture capability is supported\n");
}
if (capability.capabilities & V4L2_CAP_STREAMING) {
    printf("Streaming is supported\n");
}

Input Enumeration

This IOCTL is used to enumerate the information of available inputs (analog interface). It includes information like name of input type and supported standards for that input type.
Ioctl: VIDIOC_ENUMINPUT
It takes pointer to v4l2_input structure. Application provides the index number for which it requires the information, in index member of v4l2_input structure. Index with value zero indicates first input type of the decoder. It returns combination of the standards supported on this input in the std member of v4l2_input structure.
Example:

struct v4l2_input input;
i = 0;
while(1) {
	input.index = i;
	ret = ioctl(fd, VIDIOC_ENUMINPUT, &input);
	if (ret < 0)
	break;
	printf("name = %s\n", input.name);
	i++;
}

Set Input

This IOCTL is used to set input type (analog interface type).
Ioctl: VIDIOC_S_INPUT
This IOCTL takes pointer to integer containing index of the input which has to be set. Application will provide the index number as an argument.
0 - Composite input, 1 - S-Video input.
Example:

int index = 1; /*To set S-Video input*/
struct v4l2_input input;
ret = ioctl(fd, VIDIOC_S_INPUT, &index);
if (ret < 0) {
    perror("VIDIOC_S_INPUT\n");
    close(fd);
    return -1;
}
input.index = index;
ret = ioctl(fd, VIDIOC_ENUMINPUT, &input);
if (ret < 0) {
    perror("VIDIOC_ENUMINPUT\n");
    close(fd);
    return -1;
}
printf("name of the input = %s\n",input.name);

Get Input

This IOCTL is used to get the current input type (analog interface type).
Ioctl: VIDIOC_G_INPUT
This IOCTL takes pointer to integer using which the detected inputs will be returned. It will return the software managed input detected during open system call. Application will provide the index number as an output argument.
Example:

int input;
struct v4l2_input input;
ret = ioctl(fd, VIDIOC_G_INPUT, &input);
if (ret < 0) {
    perror("VIDIOC_G_INPUT\n");
    close(fd);
    return -1;
}
input.index = index;
ret = ioctl(fd, VIDIOC_ENUMINPUT, &input);
if (ret < 0) {
    perror("VIDIOC_ENUMINPUT\n");
    close(fd);
    return -1;
}
printf("name of the input = %s\n", input.name);

Standard Enumeration

This IOCTL is used to enumerate the information regarding video standards. This IOCTL is used to enumerate all the standards supported by the registered decoder.
Ioctl: VIDIOC_ENUMSTD
This IOCTL takes a pointer to v4l2_standard structure. Application provides the index of the standard to be enumerated in the index member of this structure. It provides information like standard name, standard ID defined at V4L2 header files (few new standards are included in the respective decoder header files, which were not available in standard V4L2 header files), and numerator and denominator values for frame period and frame lines. It takes index as an argument as a part of v4l2_standard structure.
Index with value zero provides information for the first standard among all the standards of all the registered decoders. If the index value exceeds the number of supported standards, it returns an error.
Example:

struct v4l2_standard standard;
i = 0;
while(1) {
	standard.index = i;
	ret = ioctl(fd, VIDIOC_ENUMSTD, &standard);
	if (ret < 0)
		break;
	printf("name = %s\n", std.name);
	printf("framelines = %d\n", std.framelines);
	printf("numerator = %d\n",
	std.frameperiod.numerator);
	printf("denominator = %d\n",
	std.frameperiod.denominator);
	i++;
}

Standard Detection

This IOCTL is used to detect the current video standard set in the current decoder.
Ioctl: VIDIOC_QUERYSTD
It takes a pointer to v4l2_std_id instance as an output argument. Driver will call the current decoder's function internally (which has been initialized) to detect the current standard set in hardware. Support of this IOCTL depends on decoder device, whether it can detect a standard or not.
Note: This IOCTL should be called by the application so that the camera driver can configure ISP properly with the detected decoder standard. Standard IDs are defined in the V4L2 header files
Example:

v4l2_std_id std;
struct v4l2_standard standard;
ret = ioctl(fd, VIDIOC_QUERYSTD, &std);
if (ret < 0) {
	perror("VIDIOC_QUERYSTD\n");
	close(fd);
	return -1;
}
while(1) {
	standard.index = i;
	ret = ioctl(fd, VIDIOC_ENUMSTD, &standard);
	if (ret < 0)
		break;
	if (standard.std & std) {
		printf("%s standard detected\n", standard.name);
		break;
	}
	i++;
}

Set Standard

This IOCTL is used to set the standard in the decoder.
Ioctl: VIDIOC_S_STD
It takes a pointer to v4l2_std_id instance as an input argument. If the standard is not supported by the decoder, the driver will return an error Standard IDs are defined in the V4L2 header files (few new standards are included in respective decoder header files, which were not available in standard V4L2 header files).

Note: Application need not call this IOCTL as the decoder can auto detect the current standard. This is required only when the application needs to set a particular standard. In this case, the decoder driver auto detect function is disabled. Auto detect can be enabled again only by closing and re-opening the driver.
Example:

v4l2_std_id std = V4L2_STD_NTSC;
ret = ioctl(fd, VIDIOC_S_STD, &std);
if (ret < 0) {
	perror("S_STD\n");
	close(fd);
	return -1;
}
while(1) {
	standard.index = i;
	ret = ioctl(fd, VIDIOC_ENUMSTD, &standard);
	if (ret < 0)
		break;
	if (standard.std & std) {
		printf("%s standard is selected\n");
		break;
	}
	i++;
}

Get Standard

This IOCTL is used to get the current standard in the current decoder.
Ioctl: VIDIOC_G_STD
It takes a pointer to v4l2_std_id instance as an output argument. Standard IDs are defined in the V4L2 header files
Example:

v4l2_std_id std;
ret = ioctl(fd, VIDIOC_G_STD, &std);
if (ret < 0) {
	perror("G_STD\n");
	close(fd);
	return -1;
}
while(1) {
	standard.index = i;
	ret = ioctl(fd, VIDIOC_ENUMSTD, &standard);
	if (ret < 0)
		break;
	if (standard.std & std) {
		printf("%s standard is selected\n");
		break;
	}
	i++;
}

'Format Enumeration

This IOCTL is used to enumerate the information of pixel formats. The driver supports only two pixel form at -8-bit UYVY interleaved and 8-bit YUYV interleaved.
Ioctl: VIDIOC_ENUM_FMT
It takes a pointer to instance of v4l2_fmtdesc structure as an output parameter. Application must provide the buffer type in the type argument of v4l2_fmtdesc structure as V4L2_BUF_TYPE_VIDEO_CAPTURE and index member of this structure as zero.
Example:

struct v4l2_fmtdesc fmt;
i = 0;
while(1) {
	fmt.index = i;
	ret = ioctl(fd, VIDIOC_ENUM_FMT, &fmt);
	if (ret < 0)
		break;
	printf("description = %s\n",fmt.description);
	if (fmt.type == V4L2_BUF_TYPE_VIDEO_CAPTURE)
		printf("Video capture type\n");
	if (fmt.pixelformat == V4L2_PIX_FMT_YUYV)
		printf("V4L2_PIX_FMT_YUYV\n");
	i++;
}

Set Format

This IOCTL is used to set the format parameters. The format parameters are line offset, storage format, pixel format, and so on. This IOCTL is one of the necessary IOCTL. If it is not set, it uses the following default values:

• Default storage format - V4L2_FIELD_INTERLACED

This IOCTL expects proper width and height members of the v4l2_format structure from application as per the standard selected. Please note that, V4L2_FIELD_INTERLACED is the only storage format supported.
The application can decide the buffer pixel format using pixelformat member of this IOCTL. The current driver supports - 8-bit UYVY interleaved and 8-bit YUYV interleaved formats.
The desired pitch of the buffer can be set by using the bytesperline member. The pitch should be at least one line size in bytes. When changing the pitch, the application should also modify the sizeimage member accordingly - sizeimage should be at least pitch * image height.
The driver allocates buffer of size sizeimage member of the v4l2_format structure passed through this IOCTL for both mmap buffer and user pointer mode. Driver validates the provided buffer size along with the other members and uses this buffer size for calculating offsets for storing video data.
This IOCTL is a necessary IOCTL for the user buffer mode because driver will know the buffer size for user buffer mode. If it not called for the user buffer mode, driver assumes the default buffer size and calculates offsets accordingly.
Ioctl: VIDIOC_S_FMT
It will take pointer to instance of v4l2_format structure as an input parameter. If the type member is V4L2_BUF_TYPE_VIDEO_CAPTURE, it checks pixel format, pitch value, and image size. It returns an error, if the parameters are invalid.
Example:

struct v4l2_format fmt;
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_UYVY;
/* for  NTSC standard */
fmt.fmt.pix.width = 720;
fmt.fmt.pix.height = 480;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
ret = ioctl(fd, VIDIOC_S_FMT, &fmt);
if (ret < 0) {
	perror("VIDIOC_S_FMT\n");
	close(fd);
	return -1;
}

Get Format

This IOCTL is used to get the current format parameters.
Ioctl: VIDIOC_G_FMT
It takes a pointer to instance of v4l2_format structure as an input parameter. Driver provides format parameters in the structure pointer passed as an argument. v4l2_format structure contains parameters like pixel format, image size, bytes per line, and field type. For type V4L2_BUF_TYPE_VIDEO_CAPTURE, the v4l2_pix_format structure of fmt union is filled.
Example:

struct v4l2_format fmt;
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
ret = ioctl(fd, VIDIOC_G_FMT, &fmt);
if (ret < 0) {
	perror("VIDIOC_G_FMT\n");
	close(fd);
	return -1;
}
if (fmt.fmt.pix.pixelformat == V4L2_PIX_FMT_YUYV)
	printf("8-bit UYVY pixel format\n");
printf("Size of the buffer = %d\n", fmt.fmt.pix.sizeimage);
printf("Line offset = %d\n", fmt.fmt.pix.bytesperline);
if (fmt.fmt.pix.field == V4L2_FIELD_INTERLACED)
	printf("Storate format is interlaced frame format");

Try Format

This IOCTL is used to validate the format parameters provided by the application. It checks parameters and returns the correct parameter, if any parameter is incorrect. It returns error only if the parameters passed are ambiguous.
Ioctl: VIDIOC_TRY_FMT
It takes a pointer to instance of v4l2_format structure as an input/output parameter If the type member is V4L2_BUF_TYPE_VIDEO_CAPTURE, it checks pixel format, pitch value, and image size. It returns errors to the application, if the parameters are invalid.
Example:

struct v4l2_format fmt;
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_UYVY;
fmt.fmt.pix.sizeimage = size;
fmt.fmt.pix.bytesperline = pitch;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
ret = ioctl(fd, VIDIOC_TRY_FMT, &fmt);
if (ret < 0) {
	perror("VIDIOC_TRY_FMT\n");
	close(fd);
	return -1;
}

Query Control

This IOCTL is used to get the information of controls that is, brightness, contrast, and so on supported by the current decoder.
Ioctl: VIDIOC_QUERYCTRL
This IOCTL takes a pointer to the instance of v4l2_queryctrl structure as the argument and returns the control information in the same pointer. Application provides the control ID in the v4l2_queryctrl id member in this structure. This control ID is defined in V4L2 header file, for which information is needed. If the control command specified by Id is not supported in current decoder, driver will return an error.
Example:

struct v4l2_queryctrl ctrl;
ctrl.id = V4L2_CID_CONTRAST;
ret = ioctl(fd, VIDIOC_QUERYCTRL, &ctrl);
if (ret < 0) {
	perror("VIDIOC_QUERYCTRL \n");
	close(fd);
	return -1;
}
printf("name = %s\n", ctrl.name);
printf("min = %d max = %d step = %d default = %d\n",
ctrl.minimum, ctrl.maximum, ctrl.step, ctrl.default_value);

Set Control

This IOCTL is used to set the value for a particular control in current decoder. To set the control value, this IOCTL can also be called when streaming is on.
Ioctl: VIDIOC_S_CTRL
It takes a pointer to instance of v4l2_control structure as an input parameter. Application provides control ID and control values in the v4l2_control id and value member in this structure. If the control command specified by Id is not supported in the current decoder and if value of the control is out of range, driver returns an error. Otherwise, it sets the control in the registers.
Example:

struct v4l2_control ctrl;
ctrl.id = V4L2_CID_CONTRAST;
ctrl.value = 100;
ret = ioctl(fd, VIDIOC_S_CTRL, &ctrl);
if (ret < 0) {
	perror("VIDIOC_S_CTRL\n");
	close(fd);
	return -1;
}

Get Control

This IOCTL is used to get the value for a particular control in the current decoder.
Ioctl: VIDIOC_G_CTRL
It takes a pointer to instance of v4l2_control structure as an output parameter. Application provides the control ID of id member in this structure. If the control command specified by Id is not supported in the current decoder, driver returns an error. Otherwise, it returns the value of the control in the value member of the v4l2_control structure.
Example:

struct v4l2_control ctrl;
ctrl.id = V4L2_CID_CONTRAST;
ret = ioctl(fd, VIDIOC_G_CTRL, &ctrl);
if (ret < 0) {
	perror("VIDIOC_G_CTRL\n");
	close(fd);
	return -1;
}
printf("value = %x\n", ctrl.value);

Queue Buffer

This IOCTL is used to enqueue the buffer in buffer queue. This IOCTL will enqueue an empty buffer in the driver buffer queue. This IOCTL is one of necessary IOCTL for streaming IO. If no buffer is enqueued before starting streaming, driver returns an error as there is no buffer available. So at least one buffer must be enqueued before starting streaming. This IOCTL is also used to enqueue empty buffers after streaming is started.
Ioctl: VIDIOC_QBUF
This IOCTL takes a pointer to instance of v4l2_buffer structure as an argument. Application has to specify the buffer type (V4L2_BUF_TYPE_VIDEO_CAPTURE), buffer index, and memory type V4L2_MEMORY_MMAP or V4L2_MEMORY_USERPTR at the time of queuing. For the user pointer buffer exchange mechanism, application also has to provide buffer pointer in the m.userptr member of v4l2_buffer structure.
Driver will enqueue buffer in the driver's incoming queue. It will take pointer to instance of v4l2_ buffer structure as an input parameter.
Example:

struct v4l2_buffer buf;
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.type = V4L2_MEMORY_MMAP;
buf.index = 0;
ret = ioctl(fd, VIDIOC_QBUF, &buf);
if (ret < 0) {
	perror("VIDIOC_QBUF\n");
	close(fd);
	return -1;
}

Dequeue Buffer

This IOCTL is used to dequeue the buffer in the buffer queue. This IOCTL will dequeue the captured buffer from buffer queue of the driver. This IOCTL is one of necessary IOCTL for the streaming IO. This IOCTL can be used only after streaming is started. This IOCTL will block until an empty buffer is available.
Note: The application can dequeue all buffers from the driver - the driver will not hold the last buffer to itself. In this case, the driver will disable the capture operation and the capture operation resumes when a buffer is queued to the driver again.
Ioctl: VIDIOC_DQBUF
It takes a pointer to instance of v4l2_buffer structure as an output parameter. Application has to specify the buffer type V4L2_BUF_TYPE_VIDEO_CAPTURE and memory type V4L2_MEMORY_MMAP or V4L2_MEMORY_USERPTR at the time of dequeueing.
If this IOCTL is called with the file descriptor, with which VIDIOC_REQBUF is not performed, driver will return an error. Driver will enqueue buffer, if the buffer queue is not empty.
Example:

struct v4l2_buffer buf;
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.type = V4L2_MEMORY_MMAP;
ret = ioctl(fd, VIDIOC_DQBUF, &buf);
if (ret < 0) {
	perror("VIDIOC_DQBUF\n");
	close(fd);
	return -1;
}

Stream On

This IOCTL is used to start video capture functionality.
Ioctl: VIDIOC_STREAMON
If streaming is already started, this IOCTL call returns an error.
Example:

v4l2_buf_type buftype = V4L2_BUF_TYPE_VIDEO_CAPTURE;
ret = ioctl(fd, VIDIOC_STREAMON, &buftype);
if (ret < 0) {
	perror("VIDIOC_STREAMON \n");
	close(fd);
	return -1;
}

Stream Off

This IOCTL is used to stop video capture functionality.
Ioctl: VIDIOC_STREAMOFF
If streaming is not started, this IOCTL call returns an error.
Example:

v4l2_buf_type buftype = V4L2_BUF_TYPE_VIDEO_CAPTURE;
ret = ioctl(fd, VIDIOC_STREAMOFF, &buftype);
if (ret < 0) {
	perror("VIDIOC_STREAMOFF \n");
	close(fd);
	return -1;
}

Driver Configuration 

Configuration Steps

To enable capture driver support in the kernel, start Linux Kernel Configuration tool.

$ make menuconfig  ARCH=arm

• Select Device Drivers from the main menu.

...
...
Kernel Features  --->
Boot options  --->
CPU Power Management  --->
Floating point emulation  --->
Userspace binary formats  --->
Power management options  --->
[*] Networking support  --->
Device Drivers  --->
...
...

• Select Multimedia support from the menu.

...
...
Sonics Silicon Backplane  --->
Multifunction device drivers  --->
[*] Voltage and Current Regulator Support  --->
<*> Multimedia support  --->
Graphics support  --->
<*> Sound card support  --->
[*] HID Devices  --->
[*] USB support  --->
...
...

• Select Video For Linux from the menu.

...
...
*** Multimedia core support ***
<*>   Video For Linux
[*]     Enable Video For Linux API 1 (DEPRECATED)
< >   DVB for Linux
...
...

• Select Video capture adapters from the same menu. Press <ENTER> to enter the corresponding sub-menu.

...
...
[ ]   Customize analog and hybrid tuner modules to build  --->
[*]   Video capture adapters  --->
[ ]   Radio Adapters  --->
[ ]   DAB adapters
...
...

• Select OMAP3 Camera Support from the menu.

...
...
< >   SAA5249 Teletext processor
<*>   OMAP 3 Camera support
< >   OMAP ISP Previewer
<*>   OMAP ISP Resizer
...
...

• De-Select Autoselect pertinent encoders/decoders and other helper chips from the same menu option. After De-selecting this

option, new option Encoders/decoders and other helper chips will drop down.

...
--- Video capture adapters
[ ]   Enable advanced debug functionality
[ ]   Enable old-style fixed minor ranges for video devices
[ ]   Autoselect pertinent encoders/decoders and other helper chips
Encoders/decoders and other helper chips  --->
< >   Virtual Video Driver
< >   CPiA Video For Linux

• Go inside option Encoders/decoders and other helper chips.

...
--- Video capture adapters
[ ]   Enable advanced debug functionality
[ ]   Enable old-style fixed minor ranges for video devices
[ ]   Autoselect pertinent encoders/decoders and other helper chips
        Encoders/decoders and other helper chips --->
< >   Virtual Video Driver
< >   CPiA Video For Linux

• Select TVP514x Video decoder driver from the menu.

...
...
< > Philips SAA7171/3/4 audio/video decoders
< > Philips SAA7191 video decoder
<*> Texas Instruments TVP514x video decoder
< > Texas Instruments TVP5150 video decoder
...
...

Installation

NOTE: Please note that the software detects and configures the peripherals dynamically/run-time depending on EVM revision. In case of OMAP3EVM-1 (<Rev-E) it configures the peripherals on MMDC and in case of OMAP3EVM-2 (>=Rev-E) it configures On-board peripherals.

Driver built statically

If the OMAP35x Camera driver and TVP514x driver are built statically into the kernel, it is activated during boot-up. There is no special procedure to install the driver.

Driver built as loadable module

The OMAP35x Camera driver and OMAP35x daughter card (applicable for OMAP3EVM-1 (<Rev-E)) driver cannot be build as a loadable module. both the TVP514x driver and Capture master driver can be build as a module.
If the driver has been configured to be a loadable module, then the driver is built as a module with the name tvp514x.ko and omap34xxcam.ko, which will be placed under the directory drivers/media/video in the kernel tree. Copy this driver file on to the target board and issue the following command to insert the driver:

$ insmod omap34xxcam.ko
$ insmod tvp514x.ko

To remove the driver, issue the following command:

$ rmmod omap34xxcam.ko
$ rmmod tvp514x.ko

Sample Applications 

This chapter describes the sample application provided along with the package. The binary and the source for these sample application can are available in the Examples directory of the Release Package folder.

Introduction

Writing a capture application involves the following steps:

• Opening the capture device.
• Set the parameters of the device.
• Allocate and initialize capture buffer
• Receive video data from the device.
• Close the device.

Hardware Setup

Following are the steps required to run the capture sample application:

• If you are using OMAP3EVM-1 (<Rev-E) revision board, connect the OMAP35x daughter card module containing the TVP5146 decoder to the OMAP35x main board. For OMAP3EVM-2 (>=Rev-E), all the peripherals including TVP5146 decoder is present on board.
• Connect a DVD player/camera generating a NTSC video signal to the S-Video or Composite jack of the daughter card or EVM.
• Run the sample application after booting the kernel.

Applications

Following are the list of capture sample application provided with the release:

• MMAP Loopback Application (saMmapLoopback.c):

This sample application using driver allocated buffers to capture videodata from any one of the active inputs and displays the video in the LCD using display driver.

• USERPTR Loopback Application (saUserPtrLoopback.c):

This sample application using User allocated buffers to capture video data from any one of the active inputs and displays the video in the LCD using display driver. The application makes use of V4L2 display driver buffers as a user pointer in capture driver.

NOTE: sauserPtrLoopback application configures the parameters for NTSC, so User will have to change it for PAL.