V4l2 Part 4: Input and Output

Video4linux2 Part 4: inputs and outputs

V4l2 Part 4: Input and Output

This is the fourth article in the irregular lwn series on writing video drivers for Linux. those who have not yet read the introductory article may want to start there. this week's episode describes how an application can determine which inputs and outputs are available on a given adapter and select between them.

This is the fourth article in the Linux video driver series. If you have not read the introduction, you can take a look. This week, we will talk about how the application determines which input and output are available on the given adapter and select them.

 

In our cases, a video adapter does not provide a lot of input and output options. A camera controller, for example, may provide the camera and little else. in other cases, however, the situation is more complicated. a TV card might have multiple inputs corresponding to different connectors on the Board; it cocould even have multiple tuners capable of functioning independently. sometimes those inputs have different characteristics; some might be able to tune to a wider range of video standards than others. the same holds for outputs.

In many cases, a video adapter does not provide many input/output options. For example, a camera controller usually only provides a camera and a bit of other things. However, there are some situations where the situation is relatively complicated. A TV card may have multiple connectors and multiple inputs. Some inputs have different features, and some may overwrite video standards. The same is true for video output.

 

Clearly, for an application to be able to make full use of a video adapter, it must be able to find out about the available inputs and outputs, and it must be able to select the one it wishes to operate. to that end, the video4linux2 API offers three different IOCTL () CILS for dealing with inputs, and an equivalent three for outputs. drivers shocould implement all three (for each functionality supported by the hardware), even though, for simple hardware, the corresponding code can be quite simple. drivers shoshould also provide reasonable defaults on startup. what a driver shocould not do, however, is reset input and output information when an application exits; as with other video parameters, these settings shocould be left unchanged between opens.

Obviously, to allow applications to reuse the video adapter repeatedly, you must find all the available inputs and outputs and select which one to operate. Finally, the v4l2 API provides three different IOCTL () call processing inputs, and three IOCTL () call processing outputs. According to the three functions provided by the hardware, the driver must implement three types of IOCTL (), even if the code may be very simple. The driver should provide a reasonable default value at startup. What drivers should not do is: the input and output configurations are reset when the application exits; these parameters should remain unchanged like other video parameters.

 

Video standards

Video standards

Before we can get into the details of inputs and outputs, however, we must have a look at video standards. these standards describe how a video signal is formatted for transmission-resolution, frame rates, etc. these standards are usually set by regulatory authorities in each country. there are three major types of video standard used in the world: NTSC (used in North America, primarily), Pal (much of Europe, Africa, and Asia), and SECAM (France, russia, parts of Africa ). there are, however, variations in the standards from one country to the next, and some devices are more flexible than others in the variants they can work.

Before going into the input and output details, we must examine the video standards. The video standard describes how video signals are formatted for transmission-resolution, frame rate, and so on. These standards are usually set by the management departments of each country. There are three main video standards in the world: NTSC (mainly used in North America), Pal (most of Europe, Africa, and Asia), and SECAM (France, Russia, and Africa ). However, there are also variants in the standard. One country may be different from the other, and some devices will be more flexible in terms of parameters.

The v4l2 layer represents video standards with the type v4l2_std_id, which is a 64-bit mask. each standard variant is then one bit in the mask. so "standard" NTSC is v4l2_std_ntsc_m, value 0x1000, but the Japanese variant is v4l2_std_ntsc_m_jp (0x2000 ). if a device can handle all variants of NTSC, it can set a standard type of v4l2_std_ntsc, which has all of the relevant Bits Set. similar Sets of BITs exist for the variants of PAL and SECAM. see this page for a complete list.

The v4l2 layer uses the type v4l2_std_id to represent the video standard, which is a 64-bit mask. Each standard variant is a mask. Therefore, the standard NTSC is v4l2_std_ntsc_m with a value of 0x1000, while the Japanese variant of NTSC is v4l2_std_ntsc_m_jp (0x2000 ). If a device can handle all the variants of the NTSC standard, it can set v4l2_std_ntsc, which is the entire Variant set. Similar situations also exist in PAL and SECAM. View the complete list on this page.

For user space, v4l2 provides an IOCTL () Command (vidioc_enumstd) which allows an application to query which standards are implemented by a device. the driver does not need to answer those queries directly, however; instead, it simply sets the tvnorm field of the video_device structure with all of the standards that it supports. the v4l2 layer will then split out the supported standards for the application. the vidioc_g_std command, used to query which standard is active at the moment, is also handled in the v4l2 layer by returning the value in the current_norm field of the video_device structure. the driver shocould, at startup, initialize current_norm to reflect reality; some applications will get confused if no standard is set, even though they have not set one.

For user space, v4l2 provides the ioctl () Command (vidioc_enumstd), allowing applications to query which standards are implemented by devices. The driver does not have to answer these queries directly. It simply sets the tvnorm member in the video_device struct, indicating all the criteria supported by the driver. The v4l2 layer extends it and then delivers it to the application. The vidioc_g_std command is used to query the currently activated standard. Similarly, it is returned through the current_norm member of video_device, which is then processed by the v4l2 layer and handed over to the application. When the driver starts, it should initialize current_norm; otherwise, the application may be confused if no standard is set, even if they have not set this value.

 

When an application wishes to request a specific standard, it will issue a vidioc_s_std call, which is passed through to the driver:

INT (* vidioc_s_std) (struct file * file, void * private_data, v4l2_std_id STD );

The driver shocould program the hardware to use the given standard and return zero (or a negative error code). The v4l2 layer will handle setting current_norm to the new value.

The application needs to request a specific standard. It needs to publish a vidioc_s_std call and pass in the driver through the following function pointer:

INT (* vidioc_s_std) (struct file * file, void * private_data, v4l2_std_id STD );

The driver should enable the hardware to use the given standard and return 0 (or a negative value indicates the error code ). At the v4l2 layer, this value is set to current_norm.

 

The application may want to know what kind of signal the hardware actually sees on its input. The answer can be found with vidioc_querystd, which reaches the driver:

INT (* vidioc_querystd) (struct file * file, void * private_data, v4l2_std_id * STD );

The driver shocould fill in this field in the greatest detail possible. If the hardware does not provide much information, the STD field shocould indicate any of the standards whichMightBe present.

Applications may want to know what standards the hardware will actually output. You can use the vidioc_querystd method to obtain the answer. The driver has a function pointer:

INT (* vidioc_querystd) (struct file * file, void * private_data, v4l2_std_id * STD );

The driver should try to fill in this variable STD. If the hardware does not provide information, the STD variable should be able to indicate any possible standard.

 

There is one more point worth noting here: All video devices must support (or at least claim to support) at least one standard. video standards make little sense for camera devices, which are not tied to any specific regulatory regime. but there is no standard for "I'm a camera and can do almost anything you want. "So the v4l2 layer has a number of camera drivers which claim to return pal or NTSC data.

Another point, though not worth mentioning: All video devices must support one standard, or at least claim to support one standard. Video standards do not make sense for camera devices. They do not bind any special political system. But there is no saying: I am a camera, and I can do anything you want. Therefore, on the v4l2 layer, some camera drivers claim to return pal or NTSC data.

 

Inputs

A Video Acquisition application will start by enumerating the available inputs with the vidioc_enuminput command. Within the v4l2 layer, that command will be turned into a call to the driver's corresponding callback:

INT (* vidioc_enum_input) (struct file * file, void * private_data, struct v4l2_input * input );

In this call, file corresponds to the open video device, and private_data is the private field set by the driver. the input structure is where the real information is passed; it has several fields of interest:

1. _ u32 index: the index number of the input the application is interested in; this is the only field which will be set by user space. drivers shoshould assign index numbers to inputs, starting at zero and going up from there. an application wanting to know about all available inputs will call vidioc_enuminput with index numbers starting at zero and incrementing from there; once the Driver returns einval the application knows that it has exhausted the list. input number zero shoshould exist for all input-capable devices.

2. _ u8 name [32]: The name of the input, as set by the driver. in simple cases, it can simply be "camera" or some such; If the card has multiple inputs, the name used here shocould correspond to what is printed by the connector.

3. _ u32 type: the type of input. There are currently only two: v4l2_input_type_tuner and v4l2_input_type_camera.

4. _ u32 audioset: describes which audio inputs can be associated with this video input. audio inputs are enumerated by index number just like video inputs (we'll get to audio in another installment), but not all combinations of audio and video can be selected. this field is a bitmask with a bit set for each audio input which works with the video input being enumerated. if no audio inputs are supported, or if only a single input can be selected, the driver can simply leave this field as zero.

5. _ u32 Tuner: If this input is a tuner (type is set to v4l2_input_type_tuner), this field will contain an index number corresponding to the tuner device. enumeration and control of Tuners will be covered in a future installment too.

6. v4l2_std_id STD: describes which video standard (s) are supported by the device.

7. _ u32 status: gives the status of the input. the full set of flags can be found in the v4l2 documentation; in short, each bit set in status describes a problem. these can include no power, no signal, no synchronization lock, or the presence of Macrovision, among other unfortunate events.

8. _ u32 reserved [4]: reserved fields. Drivers shoshould set them to zero.

Normally, the driver will set all of the fields above and return zero. if index is outside the range of supported inputs,-einval shoshould be returned instead; there is not much else that can go wrong in this call.

When the application wants to change the current input, the driver will receive a call to its vidioc_s_input () callback:

INT (* vidioc_s_input) (struct file * file, void * private_data, unsigned int index );

The index value has the same meaning as before-it identifies which input is of interest. the driver shocould program the hardware to use that input and return zero. other possible return values are-einval (for a bogus index number) or-EIO (for hardware trouble ). drivers shocould implement this callback even if they only support a single input.

There is also a callback to query which input is currently active:

INT (* vidioc_g_input) (struct file * file, void * private_data, unsigned int * index );

Here, the driver sets * index to the index number of the currently active input.

Outputs

The process for enumerating and selecting outputs is very similar to that for inputs, so the description here will be a little more brief. The callback for output enumeration looks like this:

INT (* vidioc_enumoutput) (struct file * file, void * private_data, struct v4l2_output * output );

The fields of the v4l2_output structure are:

1. _ u32 index: the index value corresponding to the output. This index works the same way as the input index: It starts at zero and goes up from there.

2. _ u8 name [32]: The name of the output.

3. _ u32 type: the type of the output. The supported output types are mandatory for an analog TV modulator, v4l2_output_type_analog for basic analog video output, and outputs for analog VGA overlay devices.

4. _ u32 audioset: the set of audio outputs which can operate with this video output.

5. _ u32 modulator: The index of the modulator associated with this device (for those of Type v4l2_output_type_modulator ).

6. v4l2_std_id STD: the video standards supported by this output.

7. _ u32 reserved [4]: reserved fields, shocould be set to zero.

There are callbacks for getting and setting the current output setting; they mirror the input callbacks:

INT (* vidioc_g_output) (struct file * file, void * private_data, unsigned int * index );
INT (* vidioc_s_output) (struct file * file, void * private_data, unsigned int index );

Any device which supports video output shoshould have all three output callbacks defined, even if there is only one possible output.

With these methods in place, a v4l2 application can determine which inputs and outputs are available on a given device and choose between them. the task of determining just what kind of video data flows through those inputs and outputs is rather more complicated, however. the next installment in this series will be begin to look at video data formats and how to negotiate a format with user space.