Video4linux2 Part 4: inputs and outputs

This is the fourth article in the irregular lwn series on writing videodrivers for Linux. Those who have not yet read
The introductory article maywant to start there. This week's episode describes how an application candetermine which inputs and outputs are available on a given adapter andselect between them.

In our cases, a video adapter does not provide a lot of input and outputoptions. A camera controller, for example, may provide the camera andlittle Else. in other cases, however, the situation is more complicated. a TV card might have multiple inputs corresponding
To different connectorson the Board; it cocould even have multiple tuners capable of functioningindependently. sometimes those inputs have different characteristics; somemight be able to tune to a wider range of video standards than others. thesame holds
Outputs.

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 itmust be able to select the one it wishes to operate. to that end, thevideo4linux2 API offers three different
IOCTL ()CILS for dealingwith inputs, and an equivalent three for outputs. drivers shocould implementall three (for each functionality supported by the hardware), even though, for simple hardware, the corresponding code can be quite simple. drivers shocould
Alsoprovide 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 unchangedbetween opens.

 

Video standards

Before we can get into the details of inputs and outputs, however, we musthave a look at video standards. these standards describe how a videosignal is formatted for transmission-resolution, frame rates, etc. thesestandards are usually set by regulatory
Authorities in each country. thereare three major types of video standard used in the world: NTSC (used in NorthAmerica, primarily), Pal (much of Europe, Africa, and Asia), and SECAM (France, Russia, parts of Africa ). there are, however, variations in thestandards
From one country to the next, and some devices are more flexiblethan others in the variants they can work.

The v4l2 layer represents video standards with the typeV4l2_std_id, Which is a 64-bit mask. Each standard variant is thenone bit in the mask. So "standard" NTSC is
V4l2_std_ntsc_m, ValueZero X 1000, But the japan ese variant isV4l2_std_ntsc_m_jp(Zero X 2000). If a device can handle all variants of NTSC, it can Seta standard type
V4l2_std_ntsc, Which has all of the relevantbits set. Similar Sets of BITs exist for the variants of PAL and SECAM. See
Thispage for a complete list.

For user space, v4l2 providesIOCTL ()Command (Vidioc_enumstd) Which allows an application to query whichstandards are implemented by a device. The driver does not need to answerthose queries directly, however; instead, it simply sets
TheTvnormField ofVideo_deviceStructure with all ofthe standards that it supports. The v4l2 layer will then split out thesupported standards for the application.
Vidioc_g_stdCommand, used to query which standard is active at the moment, is alsohandled in the v4l2 layer by returning the value inCurrent_normField of
Video_deviceStructure. thedriver shocould, at startup, initializeCurrent_normTo reflectreality; some applications will get confused if no standard is set, even thoughthey have not set one.

When an application wishes to request a specific standard, it will issueVidioc_s_stdCall, 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 returnzero (or a negative error code). The v4l2 layer will handle settingCurrent_normTo the new value.

The application may want to know what kind of signal the hardware actuallysees on its input. The answer can be found
Vidioc_querystd, Which reaches the driver:

 

    int (*vidioc_querystd) (struct file *file, void *private_data,                            v4l2_std_id *std);

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

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 makelittle sense for camera devices, which are not tied to any specificregulatory regime. but there is no standard
For "I'm a camera and can doalmost anything you want." So the v4l2 layer has a number of cameradrivers which claim to return pal or NTSC data.

 

Inputs

A Video Acquisition application will start by enumerating the available inputswith
Vidioc_enuminputCommand. Within the v4l2 layer, thatcommand 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,FileCorresponds to the open video device, andPrivate_dataIs the private field set by the driver.InputStructure is where the real information is passed; it hasseveral fields of interest:

 

• _ 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 callVidioc_enuminputWith index numbers starting at zero and incrementing from there; once the Driver returns
  EinvalThe application knows that it has exhausted the list. input number zero shocould exist for all input-capable devices.

   

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

   

• _ U32 type: The type of input. There are currently only two:V4l2_input_type_tunerAnd
  V4l2_input_type_camera.

   

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

   

• _ U32 Tuner: If this input is a tuner (TypeIs setV4l2_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.

   

• V4l2_std_id std: Describes which video standard (s) are supported by the device.

   

• _ U32 status: Gives the status of the input.
  Full Set of flags can be found in the v4l2 documentation; in short, each bit set in
  StatusDescribes a problem. These can include no power, no signal, no synchronization lock, or the presence of Macrovision, among other unfortunate events.

   

• _ U32 reserved [4]: Reserved fields. Drivers shoshould set them to zero.

Normally, the driver will set all of the fields above and return zero. IfIndexIs outside the range of supported inputs,
-EinvalShocould be returned instead; there is not much else that can go wrong inthis call.

When the application wants to change the current input, the driver willreceive a call to its
Vidioc_s_input ()Callback:

 

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

TheIndexValue has the same meaning as before-it identifieswhich input is of interest. The driver shocould program the hardware to usethat input and return zero. Other possible return values are-Einval(For a bogus index number) or
-EIO(For hardwaretrouble). Drivers shocould implement this callback even if they only Supporta 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* IndexTo the index number of the currentlyactive input.

 

Outputs

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

 

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

The fields ofV4l2_outputStructure are:

 

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

   

• _ U8 name [32]: The name of the output.

   

• _ U32 type: The type of the output. The supported output types are
  V4l2_output_type_modulatorFor an analog TV modulator,V4l2_output_type_analogFor basic analog video output, and
  V4l2_output_type_analogvgaoverlayFor analog VGA overlay devices.

   

• _ U32 audioset: The set of audio outputs which can operate with this video output.

   

• _ U32 Modulator: The index of the modulator associated with this device (for those of Type
  V4l2_output_type_modulator).

   

• V4l2_std_id std: The video standards supported by this output.

   

• _ 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 outputcallbacks defined, even if there is only one possible output.

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