1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 2<HTML 3><HEAD 4><TITLE 5>Common API Elements</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9REL="HOME" 10TITLE="Video for Linux Two API Specification" 11HREF="book1.htm"><LINK 12REL="PREVIOUS" 13TITLE="Introduction" 14HREF="f163.htm"><LINK 15REL="NEXT" 16TITLE="Querying Capabilities" 17HREF="x282.htm"></HEAD 18><BODY 19CLASS="CHAPTER" 20BGCOLOR="#FFFFFF" 21TEXT="#000000" 22LINK="#0000FF" 23VLINK="#840084" 24ALINK="#0000FF" 25><DIV 26CLASS="NAVHEADER" 27><TABLE 28SUMMARY="Header navigation table" 29WIDTH="100%" 30BORDER="0" 31CELLPADDING="0" 32CELLSPACING="0" 33><TR 34><TH 35COLSPAN="3" 36ALIGN="center" 37>Video for Linux Two API Specification: Revision 0.24</TH 38></TR 39><TR 40><TD 41WIDTH="10%" 42ALIGN="left" 43VALIGN="bottom" 44><A 45HREF="f163.htm" 46ACCESSKEY="P" 47>Prev</A 48></TD 49><TD 50WIDTH="80%" 51ALIGN="center" 52VALIGN="bottom" 53></TD 54><TD 55WIDTH="10%" 56ALIGN="right" 57VALIGN="bottom" 58><A 59HREF="x282.htm" 60ACCESSKEY="N" 61>Next</A 62></TD 63></TR 64></TABLE 65><HR 66ALIGN="LEFT" 67WIDTH="100%"></DIV 68><DIV 69CLASS="CHAPTER" 70><H1 71><A 72NAME="COMMON" 73></A 74>Chapter 1. Common API Elements</H1 75><DIV 76CLASS="TOC" 77><DL 78><DT 79><B 80>Table of Contents</B 81></DT 82><DT 83>1.1. <A 84HREF="c174.htm#OPEN" 85>Opening and Closing Devices</A 86></DT 87><DT 88>1.2. <A 89HREF="x282.htm" 90>Querying Capabilities</A 91></DT 92><DT 93>1.3. <A 94HREF="x294.htm" 95>Application Priority</A 96></DT 97><DT 98>1.4. <A 99HREF="x309.htm" 100>Video Inputs and Outputs</A 101></DT 102><DT 103>1.5. <A 104HREF="x341.htm" 105>Audio Inputs and Outputs</A 106></DT 107><DT 108>1.6. <A 109HREF="x394.htm" 110>Tuners and Modulators</A 111></DT 112><DT 113>1.7. <A 114HREF="x448.htm" 115>Video Standards</A 116></DT 117><DT 118>1.8. <A 119HREF="x542.htm" 120>User Controls</A 121></DT 122><DT 123>1.9. <A 124HREF="x802.htm" 125>Extended Controls</A 126></DT 127><DT 128>1.10. <A 129HREF="x1859.htm" 130>Data Formats</A 131></DT 132><DT 133>1.11. <A 134HREF="x1904.htm" 135>Image Cropping, Insertion and Scaling</A 136></DT 137><DT 138>1.12. <A 139HREF="x2009.htm" 140>Streaming Parameters</A 141></DT 142></DL 143></DIV 144><P 145>Programming a V4L2 device consists of these 146steps:</P 147><P 148></P 149><UL 150><LI 151><P 152>Opening the device</P 153></LI 154><LI 155><P 156>Changing device properties, selecting a video and audio 157input, video standard, picture brightness a. o.</P 158></LI 159><LI 160><P 161>Negotiating a data format</P 162></LI 163><LI 164><P 165>Negotiating an input/output method</P 166></LI 167><LI 168><P 169>The actual input/output loop</P 170></LI 171><LI 172><P 173>Closing the device</P 174></LI 175></UL 176><P 177>In practice most steps are optional and can be executed out of 178order. It depends on the V4L2 device type, you can read about the 179details in <A 180HREF="c6488.htm" 181>Chapter 4</A 182>. In this chapter we will discuss 183the basic concepts applicable to all devices.</P 184><DIV 185CLASS="SECTION" 186><H1 187CLASS="SECTION" 188><A 189NAME="OPEN" 190>1.1. Opening and Closing Devices</A 191></H1 192><DIV 193CLASS="SECTION" 194><H2 195CLASS="SECTION" 196><A 197NAME="AEN194" 198>1.1.1. Device Naming</A 199></H2 200><P 201>V4L2 drivers are implemented as kernel modules, loaded 202manually by the system administrator or automatically when a device is 203first opened. The driver modules plug into the "videodev" kernel 204module. It provides helper functions and a common application 205interface specified in this document.</P 206><P 207>Each driver thus loaded registers one or more device nodes 208with major number 81 and a minor number between 0 and 255. Assigning 209minor numbers to V4L2 devices is entirely up to the system administrator, 210this is primarily intended to solve conflicts between devices.<A 211NAME="AEN198" 212HREF="c174.htm#FTN.AEN198" 213><SPAN 214CLASS="footnote" 215>[1]</SPAN 216></A 217> The module options to select minor numbers are named 218after the device special file with a "_nr" suffix. For example "video_nr" 219for <TT 220CLASS="FILENAME" 221>/dev/video</TT 222> video capture devices. The number is 223an offset to the base minor number associated with the device type. 224<A 225NAME="AEN201" 226HREF="c174.htm#FTN.AEN201" 227><SPAN 228CLASS="footnote" 229>[2]</SPAN 230></A 231> When the driver supports multiple devices of the same 232type more than one minor number can be assigned, separated by commas: 233<DIV 234CLASS="INFORMALEXAMPLE" 235><P 236></P 237><A 238NAME="AEN203" 239></A 240><PRE 241CLASS="SCREEN" 242>> insmod mydriver.o video_nr=0,1 radio_nr=0,1</PRE 243><P 244></P 245></DIV 246></P 247><P 248>In <TT 249CLASS="FILENAME" 250>/etc/modules.conf</TT 251> this may be 252written as: <DIV 253CLASS="INFORMALEXAMPLE" 254><P 255></P 256><A 257NAME="AEN207" 258></A 259><PRE 260CLASS="SCREEN" 261>alias char-major-81-0 mydriver 262alias char-major-81-1 mydriver 263alias char-major-81-64 mydriver <A 264NAME="ALIAS" 265><IMG 266SRC="../images/callouts/1.gif" 267HSPACE="0" 268VSPACE="0" 269BORDER="0" 270ALT="(1)"></A 271> 272options mydriver video_nr=0,1 radio_nr=0,1 <A 273NAME="OPTIONS" 274><IMG 275SRC="../images/callouts/2.gif" 276HSPACE="0" 277VSPACE="0" 278BORDER="0" 279ALT="(2)"></A 280> 281 </PRE 282><DIV 283CLASS="CALLOUTLIST" 284><DL 285COMPACT="COMPACT" 286><DT 287><A 288HREF="c174.htm#ALIAS" 289><IMG 290SRC="../images/callouts/1.gif" 291HSPACE="0" 292VSPACE="0" 293BORDER="0" 294ALT="(1)"></A 295></DT 296><DD 297>When an application attempts to open a device 298special file with major number 81 and minor number 0, 1, or 64, load 299"mydriver" (and the "videodev" module it depends upon).</DD 300><DT 301><A 302HREF="c174.htm#OPTIONS" 303><IMG 304SRC="../images/callouts/2.gif" 305HSPACE="0" 306VSPACE="0" 307BORDER="0" 308ALT="(2)"></A 309></DT 310><DD 311>Register the first two video capture devices with 312minor number 0 and 1 (base number is 0), the first two radio device 313with minor number 64 and 65 (base 64).</DD 314></DL 315></DIV 316><P 317></P 318></DIV 319> When no minor number is given as module 320option the driver supplies a default. <A 321HREF="c6488.htm" 322>Chapter 4</A 323> 324recommends the base minor numbers to be used for the various device 325types. Obviously minor numbers must be unique. When the number is 326already in use the <SPAN 327CLASS="emphasis" 328><I 329CLASS="EMPHASIS" 330>offending device</I 331></SPAN 332> will not be 333registered. </P 334><P 335>By convention system administrators create various 336character device special files with these major and minor numbers in 337the <TT 338CLASS="FILENAME" 339>/dev</TT 340> directory. The names recomended for the 341different V4L2 device types are listed in <A 342HREF="c6488.htm" 343>Chapter 4</A 344>.</P 345><P 346>The creation of character special files (with 347<SPAN 348CLASS="APPLICATION" 349>mknod</SPAN 350>) is a privileged operation and 351devices cannot be opened by major and minor number. That means 352applications cannot <SPAN 353CLASS="emphasis" 354><I 355CLASS="EMPHASIS" 356>reliable</I 357></SPAN 358> scan for loaded or 359installed drivers. The user must enter a device name, or the 360application can try the conventional device names.</P 361><P 362>Under the device filesystem (devfs) the minor number 363options are ignored. V4L2 drivers (or by proxy the "videodev" module) 364automatically create the required device files in the 365<TT 366CLASS="FILENAME" 367>/dev/v4l</TT 368> directory using the conventional device 369names above.</P 370></DIV 371><DIV 372CLASS="SECTION" 373><H2 374CLASS="SECTION" 375><A 376NAME="RELATED" 377>1.1.2. Related Devices</A 378></H2 379><P 380>Devices can support several related functions. For example 381video capturing, video overlay and VBI capturing are related because 382these functions share, amongst other, the same video input and tuner 383frequency. V4L and earlier versions of V4L2 used the same device name 384and minor number for video capturing and overlay, but different ones 385for VBI. Experience showed this approach has several problems<A 386NAME="AEN229" 387HREF="c174.htm#FTN.AEN229" 388><SPAN 389CLASS="footnote" 390>[3]</SPAN 391></A 392>, and to make things worse the V4L videodev module 393used to prohibit multiple opens of a device.</P 394><P 395>As a remedy the present version of the V4L2 API relaxed the 396concept of device types with specific names and minor numbers. For 397compatibility with old applications drivers must still register different 398minor numbers to assign a default function to the device. But if related 399functions are supported by the driver they must be available under all 400registered minor numbers. The desired function can be selected after 401opening the device as described in <A 402HREF="c6488.htm" 403>Chapter 4</A 404>.</P 405><P 406>Imagine a driver supporting video capturing, video 407overlay, raw VBI capturing, and FM radio reception. It registers three 408devices with minor number 0, 64 and 224 (this numbering scheme is 409inherited from the V4L API). Regardless if 410<TT 411CLASS="FILENAME" 412>/dev/video</TT 413> (81, 0) or 414<TT 415CLASS="FILENAME" 416>/dev/vbi</TT 417> (81, 224) is opened the application can 418select any one of the video capturing, overlay or VBI capturing 419functions. Without programming (e. g. reading from the device 420with <SPAN 421CLASS="APPLICATION" 422>dd</SPAN 423> or <SPAN 424CLASS="APPLICATION" 425>cat</SPAN 426>) 427<TT 428CLASS="FILENAME" 429>/dev/video</TT 430> captures video images, while 431<TT 432CLASS="FILENAME" 433>/dev/vbi</TT 434> captures raw VBI data. 435<TT 436CLASS="FILENAME" 437>/dev/radio</TT 438> (81, 64) is invariable a radio device, 439unrelated to the video functions. Being unrelated does not imply the 440devices can be used at the same time, however. The <A 441HREF="r14090.htm" 442><CODE 443CLASS="FUNCTION" 444>open()</CODE 445></A 446> 447function may very well return an <SPAN 448CLASS="ERRORCODE" 449>EBUSY</SPAN 450> error code.</P 451><P 452>Besides video input or output the hardware may also 453support audio sampling or playback. If so, these functions are 454implemented as OSS or ALSA PCM devices and eventually OSS or ALSA 455audio mixer. The V4L2 API makes no provisions yet to find these 456related devices. If you have an idea please write to the Video4Linux 457mailing list: <A 458HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" 459TARGET="_top" 460>https://listman.redhat.com/mailman/listinfo/video4linux-list</A 461>.</P 462></DIV 463><DIV 464CLASS="SECTION" 465><H2 466CLASS="SECTION" 467><A 468NAME="AEN249" 469>1.1.3. Multiple Opens</A 470></H2 471><P 472>In general, V4L2 devices can be opened more than once. 473When this is supported by the driver, users can for example start a 474"panel" application to change controls like brightness or audio 475volume, while another application captures video and audio. In other words, panel 476applications are comparable to an OSS or ALSA audio mixer application. 477When a device supports multiple functions like capturing and overlay 478<SPAN 479CLASS="emphasis" 480><I 481CLASS="EMPHASIS" 482>simultaneously</I 483></SPAN 484>, multiple opens allow concurrent 485use of the device by forked processes or specialized applications.</P 486><P 487>Multiple opens are optional, although drivers should 488permit at least concurrent accesses without data exchange, i. e. panel 489applications. This implies <A 490HREF="r14090.htm" 491><CODE 492CLASS="FUNCTION" 493>open()</CODE 494></A 495> can return an <SPAN 496CLASS="ERRORCODE" 497>EBUSY</SPAN 498> error code when the 499device is already in use, as well as <A 500HREF="r7667.htm" 501><CODE 502CLASS="FUNCTION" 503>ioctl()</CODE 504></A 505> functions initiating 506data exchange (namely the <A 507HREF="r10944.htm" 508><CODE 509CLASS="CONSTANT" 510>VIDIOC_S_FMT</CODE 511></A 512> ioctl), and the <A 513HREF="r14264.htm" 514><CODE 515CLASS="FUNCTION" 516>read()</CODE 517></A 518> 519and <A 520HREF="r14496.htm" 521><CODE 522CLASS="FUNCTION" 523>write()</CODE 524></A 525> functions.</P 526><P 527>Mere opening a V4L2 device does not grant exclusive 528access.<A 529NAME="AEN266" 530HREF="c174.htm#FTN.AEN266" 531><SPAN 532CLASS="footnote" 533>[4]</SPAN 534></A 535> Initiating data exchange however assigns the right 536to read or write the requested type of data, and to change related 537properties, to this file descriptor. Applications can request 538additional access privileges using the priority mechanism described in 539<A 540HREF="x294.htm" 541>Section 1.3</A 542>.</P 543></DIV 544><DIV 545CLASS="SECTION" 546><H2 547CLASS="SECTION" 548><A 549NAME="AEN270" 550>1.1.4. Shared Data Streams</A 551></H2 552><P 553>V4L2 drivers should not support multiple applications 554reading or writing the same data stream on a device by copying 555buffers, time multiplexing or similar means. This is better handled by 556a proxy application in user space. When the driver supports stream 557sharing anyway it must be implemented transparently. The V4L2 API does 558not specify how conflicts are solved. </P 559></DIV 560><DIV 561CLASS="SECTION" 562><H2 563CLASS="SECTION" 564><A 565NAME="AEN273" 566>1.1.5. Functions</A 567></H2 568><P 569>To open and close V4L2 devices applications use the 570<A 571HREF="r14090.htm" 572><CODE 573CLASS="FUNCTION" 574>open()</CODE 575></A 576> and <A 577HREF="r7626.htm" 578><CODE 579CLASS="FUNCTION" 580>close()</CODE 581></A 582> function, respectively. Devices are 583programmed using the <A 584HREF="r7667.htm" 585><CODE 586CLASS="FUNCTION" 587>ioctl()</CODE 588></A 589> function as explained in the 590following sections.</P 591></DIV 592></DIV 593></DIV 594><H3 595CLASS="FOOTNOTES" 596>Notes</H3 597><TABLE 598BORDER="0" 599CLASS="FOOTNOTES" 600WIDTH="100%" 601><TR 602><TD 603ALIGN="LEFT" 604VALIGN="TOP" 605WIDTH="5%" 606><A 607NAME="FTN.AEN198" 608HREF="c174.htm#AEN198" 609><SPAN 610CLASS="footnote" 611>[1]</SPAN 612></A 613></TD 614><TD 615ALIGN="LEFT" 616VALIGN="TOP" 617WIDTH="95%" 618><P 619>Access permissions are associated with character 620device special files, hence we must ensure device numbers cannot 621change with the module load order. To this end minor numbers are no 622longer automatically assigned by the "videodev" module as in V4L but 623requested by the driver. The defaults will suffice for most people 624unless two drivers compete for the same minor numbers.</P 625></TD 626></TR 627><TR 628><TD 629ALIGN="LEFT" 630VALIGN="TOP" 631WIDTH="5%" 632><A 633NAME="FTN.AEN201" 634HREF="c174.htm#AEN201" 635><SPAN 636CLASS="footnote" 637>[2]</SPAN 638></A 639></TD 640><TD 641ALIGN="LEFT" 642VALIGN="TOP" 643WIDTH="95%" 644><P 645>In earlier versions of the V4L2 API the module options 646where named after the device special file with a "unit_" prefix, expressing 647the minor number itself, not an offset. Rationale for this change is unknown. 648Lastly the naming and semantics are just a convention among driver writers, 649the point to note is that minor numbers are not supposed to be hardcoded 650into drivers.</P 651></TD 652></TR 653><TR 654><TD 655ALIGN="LEFT" 656VALIGN="TOP" 657WIDTH="5%" 658><A 659NAME="FTN.AEN229" 660HREF="c174.htm#AEN229" 661><SPAN 662CLASS="footnote" 663>[3]</SPAN 664></A 665></TD 666><TD 667ALIGN="LEFT" 668VALIGN="TOP" 669WIDTH="95%" 670><P 671>Given a device file name one cannot reliable find 672related devices. For once names are arbitrary and in a system with 673multiple devices, where only some support VBI capturing, a 674<TT 675CLASS="FILENAME" 676>/dev/video2</TT 677> is not necessarily related to 678<TT 679CLASS="FILENAME" 680>/dev/vbi2</TT 681>. The V4L 682<CODE 683CLASS="CONSTANT" 684>VIDIOCGUNIT</CODE 685> ioctl would require a search for a 686device file with a particular major and minor number.</P 687></TD 688></TR 689><TR 690><TD 691ALIGN="LEFT" 692VALIGN="TOP" 693WIDTH="5%" 694><A 695NAME="FTN.AEN266" 696HREF="c174.htm#AEN266" 697><SPAN 698CLASS="footnote" 699>[4]</SPAN 700></A 701></TD 702><TD 703ALIGN="LEFT" 704VALIGN="TOP" 705WIDTH="95%" 706><P 707>Drivers could recognize the 708<CODE 709CLASS="CONSTANT" 710>O_EXCL</CODE 711> open flag. Presently this is not required, 712so applications cannot know if it really works.</P 713></TD 714></TR 715></TABLE 716><DIV 717CLASS="NAVFOOTER" 718><HR 719ALIGN="LEFT" 720WIDTH="100%"><TABLE 721SUMMARY="Footer navigation table" 722WIDTH="100%" 723BORDER="0" 724CELLPADDING="0" 725CELLSPACING="0" 726><TR 727><TD 728WIDTH="33%" 729ALIGN="left" 730VALIGN="top" 731><A 732HREF="f163.htm" 733ACCESSKEY="P" 734>Prev</A 735></TD 736><TD 737WIDTH="34%" 738ALIGN="center" 739VALIGN="top" 740><A 741HREF="book1.htm" 742ACCESSKEY="H" 743>Home</A 744></TD 745><TD 746WIDTH="33%" 747ALIGN="right" 748VALIGN="top" 749><A 750HREF="x282.htm" 751ACCESSKEY="N" 752>Next</A 753></TD 754></TR 755><TR 756><TD 757WIDTH="33%" 758ALIGN="left" 759VALIGN="top" 760>Introduction</TD 761><TD 762WIDTH="34%" 763ALIGN="center" 764VALIGN="top" 765> </TD 766><TD 767WIDTH="33%" 768ALIGN="right" 769VALIGN="top" 770>Querying Capabilities</TD 771></TR 772></TABLE 773></DIV 774></BODY 775></HTML 776> 777
