UserGuideOmap35xCaptureDriver PSP 04.02.00.07

1. Please note that with this release we have migrated to new Media-controller framework, so the User interface has been changed. Please refer to below UserGuide for complete details about media-controller usage.
2. Also, Please note that Media-controller is not a replacement for standard V4L2 framework, this framework is plug-in to the existing V4L2 framework to allow user to create/enable/disable the link and set/get/enum format for the given link/entity.
3. Since this is new framework which is still under experiment, there could be issues with it. Please refer to Arago for any updates or bug fixes.

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.
• One Camera sensor interface in YUV format

BT656 video inputs are connected to one TVP5146 decoder and sensor is directly interfaced to OMAP35x CCDC. The application must create the link before starting streaming on the streaming device node of the link.

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 for TVP5146 video decoder.

Capture Driver Component Overview

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

Capture Physical Input Interface

The Media-Controller framework has been adopted for OMAP3 ISP capture module. The Media-Controller framework exports hardware topology to the User space application as mesh or network of devices. Then User independently can set/get/enum formats at each entity and allows user to set/get/enumerate the link in current topology.

Since Media-controller is just a plug-in to the existing V4L2 framework, the V4L2 Capture driver model is still being used for streaming and all standard V4L2 interfaces. 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

• Media-Controller Framework

<Linux Kernel>/Documentation/video4linux/

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
MC	Media-Controller
YUV	Luminance + 2 Chrominance Difference Signals (Y, Cr, Cb) Color Encoding

Features 

The ISP Capture Driver provides the following features:

• Supports multi software channel of capture and a corresponding device node (/dev/videoX) is created.
• Supports multi sub-device nodes and corresponding sub device node (/dev/v4l2-subdevX) 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.

Media-Controller interface

OMAP3 ISP Camera driver has been migrated to the newly added Media-Controller (now onwards will refer as MC) framework into V4L2 sub-system. Basically MC exposes complex media device topology to the User Spaces a graph pf building blocks called Entities and they are connected to each other through Pads. User now has a capability to activate/deactivate links directly from User Space application.

Architecture

Following block diagram shows basic architecture of the MC on OMAP3 ISP Module -

Media-Controller Framework for OMAP3 ISP (cut down version)

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.

NOTE:Currently only MT9T111/TVP5146 ==> CCDC ==> Memory path has been validated.

The following is a brief description of each component in the figure.

As shown in the above architecture diagram, media topology for OMAP3 ISP is consist of various entities, like CCDC, Previewer, Resizer, external peripherals (TVP5146 & MT9T111), etc... Each entity will have one or more input/output pads depending on functionality.

MT9T111/TVP5146: The MT9T111/TVP5146 Driver is platform and board independent. Driver registers to the MC framework as an sub-device entity and sub-device to V4L2 layer. This is V4L2 compliant driver with addition of MC support. MT9T111 is parallel sensor interface whereas TVP5146 is BT656 interface, both uses 8-bit data bus connected to ISP.

CCDC: 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 driver (not a independent platform driver) registers to MC framework as media entity with various input/output pads. It is configured by the ISP driver based on the sensor/decoder attached and desired output from the camera driver.

CCDC output: This is streaming V4L2 device node, where standard V4L2 application would work.

Resizer: Resizer is HW block in Camera ISP which works in 2 ways, one-shot mode (memory-to-memory) and in on-the-fly mode (ccdc/previewer-->resizer path). Resizer driver (not a independent platform driver) registers to MC framework as a media entity with 2 pads (one input and another output). The image format at the input and output pads may differ and based on that scaling ratio is being configured.

Resizer input/output:These are streaming device nodes, where standard V4L2 application would work.

Previewer:Previewer is HW block in Camera ISP which works in 2 ways, one-shot mode (memory-to-memory) and in on-the-fly mode (ccdc-->previewer path). Previewer driver (not a independent platform driver) registers to MC framework as a media entity with 2 pads (one input and another output). The image format at the input and output pads may differ and based on that scaling ratio is being configured.

Previewer input/output:These are streaming device nodes, where standard V4L2 application would work.

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. Based on underneath hardware and corresponding media topology, there could be multiple media device nodes (/dev/mediaX). In case of OMAP3 ISP, only one media topology is possible and is being exported by /dev/media0.

Example:

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

Enumerate available Media Entities

This IOCTL is used to enumerate the information of available entities (both video-device and subdevice). It includes information like <TBD>.
Ioctl: MEDIA_IOC_ENUM_ENTITIES
It takes pointer to media_entity_desc structure. Application provides the id number for which it requires the information, in id member of media_entity_desc structure. Entities can be enumerated by oring the id with the MEDIA_ENTITY_ID_FLAG_NEXT flag. The driver will return information about the entity with the smallest id strictly larger than the requested one (next entity), or the &EINVAL; if there is none.
Example:

/* Define place holder for entities to enumerate */
struct media_entity_desc entity[20];
int index = 0;
...
...
do {
	memset(&entity[index], 0, sizeof(entity));
	/* Set the id parameter to enumerate */
	entity[index].id = index | MEDIA_ENT_ID_FLAG_NEXT;

	ret = ioctl(media_fd, MEDIA_IOC_ENUM_ENTITIES, &entity[index]);
	if (ret < 0) {
			break;
	}else {
		/*
		 * Application should pick up respective entity and corresponding
		 * device/sub-device nodes for configuration and streaming.
		 */
		if (!strcmp(entity[index].name, "mt9t111 2-003c")) {
			entity_mt9t111 =  entity[index].id;
		}
		else if (!strcmp(entity[index].name, "tvp514x 3-005c")) {
			entity_tvp5146 =  entity[index].id;
		}
                else if (!strcmp(entity[index].name, "OMAP3 ISP CCDC")) {
			entity_ccdc =  entity[index].id;
                }
		printf("[%d]:%s\n", entity[index].id, entity[index].name);
	}
	index++;
}while (ret == 0);

printf("Total number of available entities: %u\n", index);

Enumerate available Links & Pads

This IOCTL is used to enumerate the information of available links with all entities within media topology. It includes information like <TBD>.
Ioctl: MEDIA_IOC_ENUM_LINKS
It takes pointer to media_links_enum structure. Application provides the entity id number for which it requires the information, in entity member of media_links_enum structure which he would have known from MEDIA_IOC_ENUM_ENTITIES. Please make sure that you allocate memory space for pads/links for pads and links member of media_links_enum structure.
Example:

struct media_links_enum links;
int index = 0, i;

/*
 * Details from MEDIA_IOC_ENUM_ENTITIES is being used here
 */
links.pads = malloc(sizeof( struct media_pad_desc) * entity[index].pads);
links.links = malloc(sizeof(struct media_link_desc) * entity[index].links);

for(index = 0; index < num_entities; index++) {

  links.entity = entity[index].id;

  ret = ioctl(media_fd, MEDIA_IOC_ENUM_LINKS, &links);
  if (ret < 0) {
      break;
  } else {
    /* Display pads info */
    if(entity[index].pads)
      printf("pads for entity %d=", entity[index].id);

    for(i = 0;i< entity[index].pads; i++) {
      printf("(%d, %s) ", links.pads->index, (links.pads->flags & MEDIA_PAD_FLAG_INPUT) ? "INPUT" : "OUTPUT");
      links.pads++;
    }
    printf("\n");

    /* Now display link info */
    for(i = 0; i < entity[index].links; i++) {
      printf("[%d:%d]===>[%d:%d]", links.links->source.entity,
                    links.links->source.index, 
                    links.links->sink.entity,
                    links.links->sink.index);
      if(links.links->flags & MEDIA_LINK_FLAG_ENABLED)
        printf("\tACTIVE\n");
      else
        printf("\tINACTIVE \n");
      links.links++;
    }
  }
}

Enable/Setup/Activate Links

This IOCTL is used to setup/enable/activate links with specified entities within media topology.
Ioctl: MEDIA_IOC_SETUP_LINK
It takes pointer to media_link_desc structure. Application provides the all required information which would have been extracted using enumeration of media device while calling this ioctl.
It take source and sink entity id, media pad type and pad index as an input argument.

Example:

/*
 * Details from MEDIA_IOC_ENUM_ENTITIES and MEDIA_IOC_ENUM_LINKS is being used here
 */
struct media_link_desc link;

memset(&link, 0, sizeof(link));

link.flags |=  MEDIA_LINK_FLAG_ENABLED;
link.source.entity = entity_tvp5146;
link.source.index = 0;
link.source.flags = MEDIA_PAD_FLAG_OUTPUT;

link.sink.entity = entity_ccdc;
link.sink.index = 0;
link.sink.flags = MEDIA_PAD_FLAG_INPUT;

ret = ioctl(media_fd, MEDIA_IOC_SETUP_LINK, &link);
if(ret) {
	printf("failed to setup/enable/activate link between tvp5146 and ccdc\n");
	goto cleanup;
}
printf("Link between [tvp5146]===>[ccdc] enabled...\n");

V4L2 Sub-Device Interface

All sub-devices in the media topology will have separate sub-device node (/dev/v4l-subdevX) exported to the

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. Based on underneath hardware and corresponding media topology, there could be multiple sub-device nodes (/dev/v4l-subdevX). In case of OMAP3 ISP, we have in all total 8 sub-devices being exported by /dev/v4l-subdevX.

Example:

/* Open a sub-device 0 in blocking mode */
fd = open("/dev/v4l-subdev0", O_RDWR);
if (fd == -1) {
    perror("failed to open subdev device\n");
    return -1;
}
/* closing of channel */
close (fd);

Set the format at each pad

Before starting streaming on corresponding channel, user must set the format at each pad of every entity of the configured link.

Ioctl: VIDIOC_SUBDEV_S_FMT
It takes pointer to v4l2_subdev_format structure. Application provides the all required information like,

Media bus format type, possible values/options are

  - V4L2_SUBDEV_FORMAT_TRY
  - V4L2_SUBDEV_FORMAT_ACTIVE

Data format code, possible codes options are -

Below example illustrates how user can set the format at pad level -

  - V4L2_MBUS_FMT_UYVY8_2X8
  - V4L2_MBUS_FMT_VYUY8_2X8

NOTE: Please note that currently we are supporting only 2 codes mentioned above but theoretically there various formats supported by driver. Please refer to the file include/linux/v4l2-mediabus.h for all supported media bus formats.

Example:

struct v4l2_subdev_format fmt;

/*
 * Set the required format
 */
memset(&fmt, 0, sizeof(fmt));
fmt.pad = 0;
fmt.which = V4L2_SUBDEV_FORMAT_ACTIVE;
fmt.format.code = V4L2_MBUS_FMT_UYVY8_2X8;
fmt.format.width = <width>;
fmt.format.height = <height>;
fmt.format.colorspace = V4L2_COLORSPACE_SMPTE170M;
fmt.format.field = V4L2_FIELD_INTERLACED;
ret = ioctl(ccdc_fd, VIDIOC_SUBDEV_S_FMT, &fmt);
if(ret) {
    printf("failed to set format on pad %x\n", fmt.pad);
}

Get the format at each pad

This IOCTL is used to get the format set/configured at specified pad of underneath sub-device.
Ioctl: VIDIOC_SUBDEV_G_FMT
It takes pointer to v4l2_subdev_format structure. Application provides pad number and corresponding media type.
It take source and sink entity id, media pad type and pad index as an input argument.

Example:

struct v4l2_subdev_format fmt;

/*
 * Get the format used at pad 0 of underneath sub-device
 */
memset(&fmt, 0, sizeof(fmt));
fmt.pad = 0;
fmt.which = V4L2_SUBDEV_FORMAT_ACTIVE;
ret = ioctl(ccdc_fd, VIDIOC_SUBDEV_G_FMT, &fmt);
if(ret) {
    printf("failed to set format on pad %x\n", fmt.pad);
}

V4L2 Streaming Interface

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 Media Controller API from the menu

...
...
--- Multimedia support
     *** Multimedia core support *** 
[*]   Media Controller API (EXPERIMENTAL)
<*>   Video For Linux
...
...

• Select Video For Linux from the menu.

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

• Select V4L2 sub-device userspace API from the menu.

...
...
*** Multimedia core support ***
[*]   Media Controller API (EXPERIMENTAL)
<*>   Video For Linux
[*]     Enable Video For Linux API 1 (DEPRECATED)
[*]     V4L2 sub-device userspace API (EXPERIMENTAL)
< >   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.

...
...
< >   SR030PC30 VGA camera sensor support
<*>   OMAP 3 Camera support (EXPERIMENTAL)
[ ]     OMAP 3 Camera debug messages
...
...

• 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
...
...

• Select Aptina MT9T111 VGA CMOS IMAGE SENSOR from the menu.

...
...
< > Aptina MT9V113 VGA CMOS IMAGE SENSOR
<*> Aptina MT9T111 VGA CMOS IMAGE SENSOR
< > TCM825x camera sensor support
...
...

The selection between MT9T111 camera sensor and TVP5146 video decoder is done through media-controller interface dynamically.

Installation

NOTE: Please note that with this release older revision of OMAP3EVM (<Rev-E) is not supported.

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

Currently modular build is not supported in this release.

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 media device
• Enumerate/Create/Setup the links
• Opening underneath sub device
• Set the format at each pad underneath link
• 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 (>=Rev-G) revision board, TVP5146 decoder is present on board. If camera sensor module is being used, then please interface it to port J31.
• In care of Analog input, cConnect 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. Please use -h or --help for available command line options.

NOTE: Please note that, the software doesn't support older revision of EVM's (<=Rev D).

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 video data from any one of the active inputs and displays the video in the active display (LCD / DVI / TV) using display driver. Application is ported to media-controller framework and automatically creates, setup the link; configures the format at each pad of the link and start streaming.

• 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 active display (LCD / DVI / TV) using display driver. Application is ported to media-controller framework and automatically creates, setup the link; configures the format at each pad of the link and start streaming.