Based on kernel version 2.6.25. Page generated on 2008-04-18 21:22 EST.
1 <?xml version="1.0" encoding="UTF-8"?> 2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5 <book id="V4LGuide"> 6 <bookinfo> 7 <title>Video4Linux Programming</title> 8 9 <authorgroup> 10 <author> 11 <firstname>Alan</firstname> 12 <surname>Cox</surname> 13 <affiliation> 14 <address> 15 <email>alan[AT]redhat[DOT]com</email> 16 </address> 17 </affiliation> 18 </author> 19 </authorgroup> 20 21 <copyright> 22 <year>2000</year> 23 <holder>Alan Cox</holder> 24 </copyright> 25 26 <legalnotice> 27 <para> 28 This documentation is free software; you can redistribute 29 it and/or modify it under the terms of the GNU General Public 30 License as published by the Free Software Foundation; either 31 version 2 of the License, or (at your option) any later 32 version. 33 </para> 34 35 <para> 36 This program is distributed in the hope that it will be 37 useful, but WITHOUT ANY WARRANTY; without even the implied 38 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 39 See the GNU General Public License for more details. 40 </para> 41 42 <para> 43 You should have received a copy of the GNU General Public 44 License along with this program; if not, write to the Free 45 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 46 MA 02111-1307 USA 47 </para> 48 49 <para> 50 For more details see the file COPYING in the source 51 distribution of Linux. 52 </para> 53 </legalnotice> 54 </bookinfo> 55 56 <toc></toc> 57 58 <chapter id="intro"> 59 <title>Introduction</title> 60 <para> 61 Parts of this document first appeared in Linux Magazine under a 62 ninety day exclusivity. 63 </para> 64 <para> 65 Video4Linux is intended to provide a common programming interface 66 for the many TV and capture cards now on the market, as well as 67 parallel port and USB video cameras. Radio, teletext decoders and 68 vertical blanking data interfaces are also provided. 69 </para> 70 </chapter> 71 <chapter id="radio"> 72 <title>Radio Devices</title> 73 <para> 74 There are a wide variety of radio interfaces available for PC's, and these 75 are generally very simple to program. The biggest problem with supporting 76 such devices is normally extracting documentation from the vendor. 77 </para> 78 <para> 79 The radio interface supports a simple set of control ioctls standardised 80 across all radio and tv interfaces. It does not support read or write, which 81 are used for video streams. The reason radio cards do not allow you to read 82 the audio stream into an application is that without exception they provide 83 a connection on to a soundcard. Soundcards can be used to read the radio 84 data just fine. 85 </para> 86 <sect1 id="registerradio"> 87 <title>Registering Radio Devices</title> 88 <para> 89 The Video4linux core provides an interface for registering devices. The 90 first step in writing our radio card driver is to register it. 91 </para> 92 <programlisting> 93 94 95 static struct video_device my_radio 96 { 97 "My radio", 98 VID_TYPE_TUNER, 99 radio_open. 100 radio_close, 101 NULL, /* no read */ 102 NULL, /* no write */ 103 NULL, /* no poll */ 104 radio_ioctl, 105 NULL, /* no special init function */ 106 NULL /* no private data */ 107 }; 108 109 110 </programlisting> 111 <para> 112 This declares our video4linux device driver interface. The VID_TYPE_ value 113 defines what kind of an interface we are, and defines basic capabilities. 114 </para> 115 <para> 116 The only defined value relevant for a radio card is VID_TYPE_TUNER which 117 indicates that the device can be tuned. Clearly our radio is going to have some 118 way to change channel so it is tuneable. 119 </para> 120 <para> 121 We declare an open and close routine, but we do not need read or write, 122 which are used to read and write video data to or from the card itself. As 123 we have no read or write there is no poll function. 124 </para> 125 <para> 126 The private initialise function is run when the device is registered. In 127 this driver we've already done all the work needed. The final pointer is a 128 private data pointer that can be used by the device driver to attach and 129 retrieve private data structures. We set this field "priv" to NULL for 130 the moment. 131 </para> 132 <para> 133 Having the structure defined is all very well but we now need to register it 134 with the kernel. 135 </para> 136 <programlisting> 137 138 139 static int io = 0x320; 140 141 int __init myradio_init(struct video_init *v) 142 { 143 if(!request_region(io, MY_IO_SIZE, "myradio")) 144 { 145 printk(KERN_ERR 146 "myradio: port 0x%03X is in use.\n", io); 147 return -EBUSY; 148 } 149 150 if(video_device_register(&my_radio, VFL_TYPE_RADIO)==-1) { 151 release_region(io, MY_IO_SIZE); 152 return -EINVAL; 153 } 154 return 0; 155 } 156 157 </programlisting> 158 <para> 159 The first stage of the initialisation, as is normally the case, is to check 160 that the I/O space we are about to fiddle with doesn't belong to some other 161 driver. If it is we leave well alone. If the user gives the address of the 162 wrong device then we will spot this. These policies will generally avoid 163 crashing the machine. 164 </para> 165 <para> 166 Now we ask the Video4Linux layer to register the device for us. We hand it 167 our carefully designed video_device structure and also tell it which group 168 of devices we want it registered with. In this case VFL_TYPE_RADIO. 169 </para> 170 <para> 171 The types available are 172 </para> 173 <table frame="all" id="Device_Types"><title>Device Types</title> 174 <tgroup cols="3" align="left"> 175 <tbody> 176 <row> 177 <entry>VFL_TYPE_RADIO</entry><entry>/dev/radio{n}</entry><entry> 178 179 Radio devices are assigned in this block. As with all of these 180 selections the actual number assignment is done by the video layer 181 accordijng to what is free.</entry> 182 </row><row> 183 <entry>VFL_TYPE_GRABBER</entry><entry>/dev/video{n}</entry><entry> 184 Video capture devices and also -- counter-intuitively for the name -- 185 hardware video playback devices such as MPEG2 cards.</entry> 186 </row><row> 187 <entry>VFL_TYPE_VBI</entry><entry>/dev/vbi{n}</entry><entry> 188 The VBI devices capture the hidden lines on a television picture 189 that carry further information like closed caption data, teletext 190 (primarily in Europe) and now Intercast and the ATVEC internet 191 television encodings.</entry> 192 </row><row> 193 <entry>VFL_TYPE_VTX</entry><entry>/dev/vtx[n}</entry><entry> 194 VTX is 'Videotext' also known as 'Teletext'. This is a system for 195 sending numbered, 40x25, mostly textual page images over the hidden 196 lines. Unlike the /dev/vbi interfaces, this is for 'smart' decoder 197 chips. (The use of the word smart here has to be taken in context, 198 the smartest teletext chips are fairly dumb pieces of technology). 199 </entry> 200 </row> 201 </tbody> 202 </tgroup> 203 </table> 204 <para> 205 We are most definitely a radio. 206 </para> 207 <para> 208 Finally we allocate our I/O space so that nobody treads on us and return 0 209 to signify general happiness with the state of the universe. 210 </para> 211 </sect1> 212 <sect1 id="openradio"> 213 <title>Opening And Closing The Radio</title> 214 215 <para> 216 The functions we declared in our video_device are mostly very simple. 217 Firstly we can drop in what is basically standard code for open and close. 218 </para> 219 <programlisting> 220 221 222 static int users = 0; 223 224 static int radio_open(struct video_device *dev, int flags) 225 { 226 if(users) 227 return -EBUSY; 228 users++; 229 return 0; 230 } 231 232 </programlisting> 233 <para> 234 At open time we need to do nothing but check if someone else is also using 235 the radio card. If nobody is using it we make a note that we are using it, 236 then we ensure that nobody unloads our driver on us. 237 </para> 238 <programlisting> 239 240 241 static int radio_close(struct video_device *dev) 242 { 243 users--; 244 } 245 246 </programlisting> 247 <para> 248 At close time we simply need to reduce the user count and allow the module 249 to become unloadable. 250 </para> 251 <para> 252 If you are sharp you will have noticed neither the open nor the close 253 routines attempt to reset or change the radio settings. This is intentional. 254 It allows an application to set up the radio and exit. It avoids a user 255 having to leave an application running all the time just to listen to the 256 radio. 257 </para> 258 </sect1> 259 <sect1 id="ioctlradio"> 260 <title>The Ioctl Interface</title> 261 <para> 262 This leaves the ioctl routine, without which the driver will not be 263 terribly useful to anyone. 264 </para> 265 <programlisting> 266 267 268 static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg) 269 { 270 switch(cmd) 271 { 272 case VIDIOCGCAP: 273 { 274 struct video_capability v; 275 v.type = VID_TYPE_TUNER; 276 v.channels = 1; 277 v.audios = 1; 278 v.maxwidth = 0; 279 v.minwidth = 0; 280 v.maxheight = 0; 281 v.minheight = 0; 282 strcpy(v.name, "My Radio"); 283 if(copy_to_user(arg, &v, sizeof(v))) 284 return -EFAULT; 285 return 0; 286 } 287 288 </programlisting> 289 <para> 290 VIDIOCGCAP is the first ioctl all video4linux devices must support. It 291 allows the applications to find out what sort of a card they have found and 292 to figure out what they want to do about it. The fields in the structure are 293 </para> 294 <table frame="all" id="video_capability_fields"><title>struct video_capability fields</title> 295 <tgroup cols="2" align="left"> 296 <tbody> 297 <row> 298 <entry>name</entry><entry>The device text name. This is intended for the user.</entry> 299 </row><row> 300 <entry>channels</entry><entry>The number of different channels you can tune on 301 this card. It could even by zero for a card that has 302 no tuning capability. For our simple FM radio it is 1. 303 An AM/FM radio would report 2.</entry> 304 </row><row> 305 <entry>audios</entry><entry>The number of audio inputs on this device. For our 306 radio there is only one audio input.</entry> 307 </row><row> 308 <entry>minwidth,minheight</entry><entry>The smallest size the card is capable of capturing 309 images in. We set these to zero. Radios do not 310 capture pictures</entry> 311 </row><row> 312 <entry>maxwidth,maxheight</entry><entry>The largest image size the card is capable of 313 capturing. For our radio we report 0. 314 </entry> 315 </row><row> 316 <entry>type</entry><entry>This reports the capabilities of the device, and 317 matches the field we filled in in the struct 318 video_device when registering.</entry> 319 </row> 320 </tbody> 321 </tgroup> 322 </table> 323 <para> 324 Having filled in the fields, we use copy_to_user to copy the structure into 325 the users buffer. If the copy fails we return an EFAULT to the application 326 so that it knows it tried to feed us garbage. 327 </para> 328 <para> 329 The next pair of ioctl operations select which tuner is to be used and let 330 the application find the tuner properties. We have only a single FM band 331 tuner in our example device. 332 </para> 333 <programlisting> 334 335 336 case VIDIOCGTUNER: 337 { 338 struct video_tuner v; 339 if(copy_from_user(&v, arg, sizeof(v))!=0) 340 return -EFAULT; 341 if(v.tuner) 342 return -EINVAL; 343 v.rangelow=(87*16000); 344 v.rangehigh=(108*16000); 345 v.flags = VIDEO_TUNER_LOW; 346 v.mode = VIDEO_MODE_AUTO; 347 v.signal = 0xFFFF; 348 strcpy(v.name, "FM"); 349 if(copy_to_user(&v, arg, sizeof(v))!=0) 350 return -EFAULT; 351 return 0; 352 } 353 354 </programlisting> 355 <para> 356 The VIDIOCGTUNER ioctl allows applications to query a tuner. The application 357 sets the tuner field to the tuner number it wishes to query. The query does 358 not change the tuner that is being used, it merely enquires about the tuner 359 in question. 360 </para> 361 <para> 362 We have exactly one tuner so after copying the user buffer to our temporary 363 structure we complain if they asked for a tuner other than tuner 0. 364 </para> 365 <para> 366 The video_tuner structure has the following fields 367 </para> 368 <table frame="all" id="video_tuner_fields"><title>struct video_tuner fields</title> 369 <tgroup cols="2" align="left"> 370 <tbody> 371 <row> 372 <entry>int tuner</entry><entry>The number of the tuner in question</entry> 373 </row><row> 374 <entry>char name[32]</entry><entry>A text description of this tuner. "FM" will do fine. 375 This is intended for the application.</entry> 376 </row><row> 377 <entry>u32 flags</entry> 378 <entry>Tuner capability flags</entry> 379 </row> 380 <row> 381 <entry>u16 mode</entry><entry>The current reception mode</entry> 382 383 </row><row> 384 <entry>u16 signal</entry><entry>The signal strength scaled between 0 and 65535. If 385 a device cannot tell the signal strength it should 386 report 65535. Many simple cards contain only a 387 signal/no signal bit. Such cards will report either 388 0 or 65535.</entry> 389 390 </row><row> 391 <entry>u32 rangelow, rangehigh</entry><entry> 392 The range of frequencies supported by the radio 393 or TV. It is scaled according to the VIDEO_TUNER_LOW 394 flag.</entry> 395 396 </row> 397 </tbody> 398 </tgroup> 399 </table> 400 401 <table frame="all" id="video_tuner_flags"><title>struct video_tuner flags</title> 402 <tgroup cols="2" align="left"> 403 <tbody> 404 <row> 405 <entry>VIDEO_TUNER_PAL</entry><entry>A PAL TV tuner</entry> 406 </row><row> 407 <entry>VIDEO_TUNER_NTSC</entry><entry>An NTSC (US) TV tuner</entry> 408 </row><row> 409 <entry>VIDEO_TUNER_SECAM</entry><entry>A SECAM (French) TV tuner</entry> 410 </row><row> 411 <entry>VIDEO_TUNER_LOW</entry><entry> 412 The tuner frequency is scaled in 1/16th of a KHz 413 steps. If not it is in 1/16th of a MHz steps 414 </entry> 415 </row><row> 416 <entry>VIDEO_TUNER_NORM</entry><entry>The tuner can set its format</entry> 417 </row><row> 418 <entry>VIDEO_TUNER_STEREO_ON</entry><entry>The tuner is currently receiving a stereo signal</entry> 419 </row> 420 </tbody> 421 </tgroup> 422 </table> 423 424 <table frame="all" id="video_tuner_modes"><title>struct video_tuner modes</title> 425 <tgroup cols="2" align="left"> 426 <tbody> 427 <row> 428 <entry>VIDEO_MODE_PAL</entry><entry>PAL Format</entry> 429 </row><row> 430 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC Format (USA)</entry> 431 </row><row> 432 <entry>VIDEO_MODE_SECAM</entry><entry>French Format</entry> 433 </row><row> 434 <entry>VIDEO_MODE_AUTO</entry><entry>A device that does not need to do 435 TV format switching</entry> 436 </row> 437 </tbody> 438 </tgroup> 439 </table> 440 <para> 441 The settings for the radio card are thus fairly simple. We report that we 442 are a tuner called "FM" for FM radio. In order to get the best tuning 443 resolution we report VIDEO_TUNER_LOW and select tuning to 1/16th of KHz. Its 444 unlikely our card can do that resolution but it is a fair bet the card can 445 do better than 1/16th of a MHz. VIDEO_TUNER_LOW is appropriate to almost all 446 radio usage. 447 </para> 448 <para> 449 We report that the tuner automatically handles deciding what format it is 450 receiving - true enough as it only handles FM radio. Our example card is 451 also incapable of detecting stereo or signal strengths so it reports a 452 strength of 0xFFFF (maximum) and no stereo detected. 453 </para> 454 <para> 455 To finish off we set the range that can be tuned to be 87-108Mhz, the normal 456 FM broadcast radio range. It is important to find out what the card is 457 actually capable of tuning. It is easy enough to simply use the FM broadcast 458 range. Unfortunately if you do this you will discover the FM broadcast 459 ranges in the USA, Europe and Japan are all subtly different and some users 460 cannot receive all the stations they wish. 461 </para> 462 <para> 463 The application also needs to be able to set the tuner it wishes to use. In 464 our case, with a single tuner this is rather simple to arrange. 465 </para> 466 <programlisting> 467 468 case VIDIOCSTUNER: 469 { 470 struct video_tuner v; 471 if(copy_from_user(&v, arg, sizeof(v))) 472 return -EFAULT; 473 if(v.tuner != 0) 474 return -EINVAL; 475 return 0; 476 } 477 478 </programlisting> 479 <para> 480 We copy the user supplied structure into kernel memory so we can examine it. 481 If the user has selected a tuner other than zero we reject the request. If 482 they wanted tuner 0 then, surprisingly enough, that is the current tuner already. 483 </para> 484 <para> 485 The next two ioctls we need to provide are to get and set the frequency of 486 the radio. These both use an unsigned long argument which is the frequency. 487 The scale of the frequency depends on the VIDEO_TUNER_LOW flag as I 488 mentioned earlier on. Since we have VIDEO_TUNER_LOW set this will be in 489 1/16ths of a KHz. 490 </para> 491 <programlisting> 492 493 static unsigned long current_freq; 494 495 496 497 case VIDIOCGFREQ: 498 if(copy_to_user(arg, &current_freq, 499 sizeof(unsigned long)) 500 return -EFAULT; 501 return 0; 502 503 </programlisting> 504 <para> 505 Querying the frequency in our case is relatively simple. Our radio card is 506 too dumb to let us query the signal strength so we remember our setting if 507 we know it. All we have to do is copy it to the user. 508 </para> 509 <programlisting> 510 511 512 case VIDIOCSFREQ: 513 { 514 u32 freq; 515 if(copy_from_user(arg, &freq, 516 sizeof(unsigned long))!=0) 517 return -EFAULT; 518 if(hardware_set_freq(freq)<0) 519 return -EINVAL; 520 current_freq = freq; 521 return 0; 522 } 523 524 </programlisting> 525 <para> 526 Setting the frequency is a little more complex. We begin by copying the 527 desired frequency into kernel space. Next we call a hardware specific routine 528 to set the radio up. This might be as simple as some scaling and a few 529 writes to an I/O port. For most radio cards it turns out a good deal more 530 complicated and may involve programming things like a phase locked loop on 531 the card. This is what documentation is for. 532 </para> 533 <para> 534 The final set of operations we need to provide for our radio are the 535 volume controls. Not all radio cards can even do volume control. After all 536 there is a perfectly good volume control on the sound card. We will assume 537 our radio card has a simple 4 step volume control. 538 </para> 539 <para> 540 There are two ioctls with audio we need to support 541 </para> 542 <programlisting> 543 544 static int current_volume=0; 545 546 case VIDIOCGAUDIO: 547 { 548 struct video_audio v; 549 if(copy_from_user(&v, arg, sizeof(v))) 550 return -EFAULT; 551 if(v.audio != 0) 552 return -EINVAL; 553 v.volume = 16384*current_volume; 554 v.step = 16384; 555 strcpy(v.name, "Radio"); 556 v.mode = VIDEO_SOUND_MONO; 557 v.balance = 0; 558 v.base = 0; 559 v.treble = 0; 560 561 if(copy_to_user(arg. &v, sizeof(v))) 562 return -EFAULT; 563 return 0; 564 } 565 566 </programlisting> 567 <para> 568 Much like the tuner we start by copying the user structure into kernel 569 space. Again we check if the user has asked for a valid audio input. We have 570 only input 0 and we punt if they ask for another input. 571 </para> 572 <para> 573 Then we fill in the video_audio structure. This has the following format 574 </para> 575 <table frame="all" id="video_audio_fields"><title>struct video_audio fields</title> 576 <tgroup cols="2" align="left"> 577 <tbody> 578 <row> 579 <entry>audio</entry><entry>The input the user wishes to query</entry> 580 </row><row> 581 <entry>volume</entry><entry>The volume setting on a scale of 0-65535</entry> 582 </row><row> 583 <entry>base</entry><entry>The base level on a scale of 0-65535</entry> 584 </row><row> 585 <entry>treble</entry><entry>The treble level on a scale of 0-65535</entry> 586 </row><row> 587 <entry>flags</entry><entry>The features this audio device supports 588 </entry> 589 </row><row> 590 <entry>name</entry><entry>A text name to display to the user. We picked 591 "Radio" as it explains things quite nicely.</entry> 592 </row><row> 593 <entry>mode</entry><entry>The current reception mode for the audio 594 595 We report MONO because our card is too stupid to know if it is in 596 mono or stereo. 597 </entry> 598 </row><row> 599 <entry>balance</entry><entry>The stereo balance on a scale of 0-65535, 32768 is 600 middle.</entry> 601 </row><row> 602 <entry>step</entry><entry>The step by which the volume control jumps. This is 603 used to help make it easy for applications to set 604 slider behaviour.</entry> 605 </row> 606 </tbody> 607 </tgroup> 608 </table> 609 610 <table frame="all" id="video_audio_flags"><title>struct video_audio flags</title> 611 <tgroup cols="2" align="left"> 612 <tbody> 613 <row> 614 <entry>VIDEO_AUDIO_MUTE</entry><entry>The audio is currently muted. We 615 could fake this in our driver but we 616 choose not to bother.</entry> 617 </row><row> 618 <entry>VIDEO_AUDIO_MUTABLE</entry><entry>The input has a mute option</entry> 619 </row><row> 620 <entry>VIDEO_AUDIO_TREBLE</entry><entry>The input has a treble control</entry> 621 </row><row> 622 <entry>VIDEO_AUDIO_BASS</entry><entry>The input has a base control</entry> 623 </row> 624 </tbody> 625 </tgroup> 626 </table> 627 628 <table frame="all" id="video_audio_modes"><title>struct video_audio modes</title> 629 <tgroup cols="2" align="left"> 630 <tbody> 631 <row> 632 <entry>VIDEO_SOUND_MONO</entry><entry>Mono sound</entry> 633 </row><row> 634 <entry>VIDEO_SOUND_STEREO</entry><entry>Stereo sound</entry> 635 </row><row> 636 <entry>VIDEO_SOUND_LANG1</entry><entry>Alternative language 1 (TV specific)</entry> 637 </row><row> 638 <entry>VIDEO_SOUND_LANG2</entry><entry>Alternative language 2 (TV specific)</entry> 639 </row> 640 </tbody> 641 </tgroup> 642 </table> 643 <para> 644 Having filled in the structure we copy it back to user space. 645 </para> 646 <para> 647 The VIDIOCSAUDIO ioctl allows the user to set the audio parameters in the 648 video_audio structure. The driver does its best to honour the request. 649 </para> 650 <programlisting> 651 652 case VIDIOCSAUDIO: 653 { 654 struct video_audio v; 655 if(copy_from_user(&v, arg, sizeof(v))) 656 return -EFAULT; 657 if(v.audio) 658 return -EINVAL; 659 current_volume = v/16384; 660 hardware_set_volume(current_volume); 661 return 0; 662 } 663 664 </programlisting> 665 <para> 666 In our case there is very little that the user can set. The volume is 667 basically the limit. Note that we could pretend to have a mute feature 668 by rewriting this to 669 </para> 670 <programlisting> 671 672 case VIDIOCSAUDIO: 673 { 674 struct video_audio v; 675 if(copy_from_user(&v, arg, sizeof(v))) 676 return -EFAULT; 677 if(v.audio) 678 return -EINVAL; 679 current_volume = v/16384; 680 if(v.flags&VIDEO_AUDIO_MUTE) 681 hardware_set_volume(0); 682 else 683 hardware_set_volume(current_volume); 684 current_muted = v.flags & 685 VIDEO_AUDIO_MUTE; 686 return 0; 687 } 688 689 </programlisting> 690 <para> 691 This with the corresponding changes to the VIDIOCGAUDIO code to report the 692 state of the mute flag we save and to report the card has a mute function, 693 will allow applications to use a mute facility with this card. It is 694 questionable whether this is a good idea however. User applications can already 695 fake this themselves and kernel space is precious. 696 </para> 697 <para> 698 We now have a working radio ioctl handler. So we just wrap up the function 699 </para> 700 <programlisting> 701 702 703 } 704 return -ENOIOCTLCMD; 705 } 706 707 </programlisting> 708 <para> 709 and pass the Video4Linux layer back an error so that it knows we did not 710 understand the request we got passed. 711 </para> 712 </sect1> 713 <sect1 id="modradio"> 714 <title>Module Wrapper</title> 715 <para> 716 Finally we add in the usual module wrapping and the driver is done. 717 </para> 718 <programlisting> 719 720 #ifndef MODULE 721 722 static int io = 0x300; 723 724 #else 725 726 static int io = -1; 727 728 #endif 729 730 MODULE_AUTHOR("Alan Cox"); 731 MODULE_DESCRIPTION("A driver for an imaginary radio card."); 732 module_param(io, int, 0444); 733 MODULE_PARM_DESC(io, "I/O address of the card."); 734 735 static int __init init(void) 736 { 737 if(io==-1) 738 { 739 printk(KERN_ERR 740 "You must set an I/O address with io=0x???\n"); 741 return -EINVAL; 742 } 743 return myradio_init(NULL); 744 } 745 746 static void __exit cleanup(void) 747 { 748 video_unregister_device(&my_radio); 749 release_region(io, MY_IO_SIZE); 750 } 751 752 module_init(init); 753 module_exit(cleanup); 754 755 </programlisting> 756 <para> 757 In this example we set the IO base by default if the driver is compiled into 758 the kernel: you can still set it using "my_radio.irq" if this file is called <filename>my_radio.c</filename>. For the module we require the 759 user sets the parameter. We set io to a nonsense port (-1) so that we can 760 tell if the user supplied an io parameter or not. 761 </para> 762 <para> 763 We use MODULE_ defines to give an author for the card driver and a 764 description. We also use them to declare that io is an integer and it is the 765 address of the card, and can be read by anyone from sysfs. 766 </para> 767 <para> 768 The clean-up routine unregisters the video_device we registered, and frees 769 up the I/O space. Note that the unregister takes the actual video_device 770 structure as its argument. Unlike the file operations structure which can be 771 shared by all instances of a device a video_device structure as an actual 772 instance of the device. If you are registering multiple radio devices you 773 need to fill in one structure per device (most likely by setting up a 774 template and copying it to each of the actual device structures). 775 </para> 776 </sect1> 777 </chapter> 778 <chapter id="Video_Capture_Devices"> 779 <title>Video Capture Devices</title> 780 <sect1 id="introvid"> 781 <title>Video Capture Device Types</title> 782 <para> 783 The video capture devices share the same interfaces as radio devices. In 784 order to explain the video capture interface I will use the example of a 785 camera that has no tuners or audio input. This keeps the example relatively 786 clean. To get both combine the two driver examples. 787 </para> 788 <para> 789 Video capture devices divide into four categories. A little technology 790 backgrounder. Full motion video even at television resolution (which is 791 actually fairly low) is pretty resource-intensive. You are continually 792 passing megabytes of data every second from the capture card to the display. 793 several alternative approaches have emerged because copying this through the 794 processor and the user program is a particularly bad idea . 795 </para> 796 <para> 797 The first is to add the television image onto the video output directly. 798 This is also how some 3D cards work. These basic cards can generally drop the 799 video into any chosen rectangle of the display. Cards like this, which 800 include most mpeg1 cards that used the feature connector, aren't very 801 friendly in a windowing environment. They don't understand windows or 802 clipping. The video window is always on the top of the display. 803 </para> 804 <para> 805 Chroma keying is a technique used by cards to get around this. It is an old 806 television mixing trick where you mark all the areas you wish to replace 807 with a single clear colour that isn't used in the image - TV people use an 808 incredibly bright blue while computing people often use a particularly 809 virulent purple. Bright blue occurs on the desktop. Anyone with virulent 810 purple windows has another problem besides their TV overlay. 811 </para> 812 <para> 813 The third approach is to copy the data from the capture card to the video 814 card, but to do it directly across the PCI bus. This relieves the processor 815 from doing the work but does require some smartness on the part of the video 816 capture chip, as well as a suitable video card. Programming this kind of 817 card and more so debugging it can be extremely tricky. There are some quite 818 complicated interactions with the display and you may also have to cope with 819 various chipset bugs that show up when PCI cards start talking to each 820 other. 821 </para> 822 <para> 823 To keep our example fairly simple we will assume a card that supports 824 overlaying a flat rectangular image onto the frame buffer output, and which 825 can also capture stuff into processor memory. 826 </para> 827 </sect1> 828 <sect1 id="regvid"> 829 <title>Registering Video Capture Devices</title> 830 <para> 831 This time we need to add more functions for our camera device. 832 </para> 833 <programlisting> 834 static struct video_device my_camera 835 { 836 "My Camera", 837 VID_TYPE_OVERLAY|VID_TYPE_SCALES|\ 838 VID_TYPE_CAPTURE|VID_TYPE_CHROMAKEY, 839 camera_open. 840 camera_close, 841 camera_read, /* no read */ 842 NULL, /* no write */ 843 camera_poll, /* no poll */ 844 camera_ioctl, 845 NULL, /* no special init function */ 846 NULL /* no private data */ 847 }; 848 </programlisting> 849 <para> 850 We need a read() function which is used for capturing data from 851 the card, and we need a poll function so that a driver can wait for the next 852 frame to be captured. 853 </para> 854 <para> 855 We use the extra video capability flags that did not apply to the 856 radio interface. The video related flags are 857 </para> 858 <table frame="all" id="Capture_Capabilities"><title>Capture Capabilities</title> 859 <tgroup cols="2" align="left"> 860 <tbody> 861 <row> 862 <entry>VID_TYPE_CAPTURE</entry><entry>We support image capture</entry> 863 </row><row> 864 <entry>VID_TYPE_TELETEXT</entry><entry>A teletext capture device (vbi{n])</entry> 865 </row><row> 866 <entry>VID_TYPE_OVERLAY</entry><entry>The image can be directly overlaid onto the 867 frame buffer</entry> 868 </row><row> 869 <entry>VID_TYPE_CHROMAKEY</entry><entry>Chromakey can be used to select which parts 870 of the image to display</entry> 871 </row><row> 872 <entry>VID_TYPE_CLIPPING</entry><entry>It is possible to give the board a list of 873 rectangles to draw around. </entry> 874 </row><row> 875 <entry>VID_TYPE_FRAMERAM</entry><entry>The video capture goes into the video memory 876 and actually changes it. Applications need 877 to know this so they can clean up after the 878 card</entry> 879 </row><row> 880 <entry>VID_TYPE_SCALES</entry><entry>The image can be scaled to various sizes, 881 rather than being a single fixed size.</entry> 882 </row><row> 883 <entry>VID_TYPE_MONOCHROME</entry><entry>The capture will be monochrome. This isn't a 884 complete answer to the question since a mono 885 camera on a colour capture card will still 886 produce mono output.</entry> 887 </row><row> 888 <entry>VID_TYPE_SUBCAPTURE</entry><entry>The card allows only part of its field of 889 view to be captured. This enables 890 applications to avoid copying all of a large 891 image into memory when only some section is 892 relevant.</entry> 893 </row> 894 </tbody> 895 </tgroup> 896 </table> 897 <para> 898 We set VID_TYPE_CAPTURE so that we are seen as a capture card, 899 VID_TYPE_CHROMAKEY so the application knows it is time to draw in virulent 900 purple, and VID_TYPE_SCALES because we can be resized. 901 </para> 902 <para> 903 Our setup is fairly similar. This time we also want an interrupt line 904 for the 'frame captured' signal. Not all cards have this so some of them 905 cannot handle poll(). 906 </para> 907 <programlisting> 908 909 910 static int io = 0x320; 911 static int irq = 11; 912 913 int __init mycamera_init(struct video_init *v) 914 { 915 if(!request_region(io, MY_IO_SIZE, "mycamera")) 916 { 917 printk(KERN_ERR 918 "mycamera: port 0x%03X is in use.\n", io); 919 return -EBUSY; 920 } 921 922 if(video_device_register(&my_camera, 923 VFL_TYPE_GRABBER)==-1) { 924 release_region(io, MY_IO_SIZE); 925 return -EINVAL; 926 } 927 return 0; 928 } 929 930 </programlisting> 931 <para> 932 This is little changed from the needs of the radio card. We specify 933 VFL_TYPE_GRABBER this time as we want to be allocated a /dev/video name. 934 </para> 935 </sect1> 936 <sect1 id="opvid"> 937 <title>Opening And Closing The Capture Device</title> 938 <programlisting> 939 940 941 static int users = 0; 942 943 static int camera_open(struct video_device *dev, int flags) 944 { 945 if(users) 946 return -EBUSY; 947 if(request_irq(irq, camera_irq, 0, "camera", dev)<0) 948 return -EBUSY; 949 users++; 950 return 0; 951 } 952 953 954 static int camera_close(struct video_device *dev) 955 { 956 users--; 957 free_irq(irq, dev); 958 } 959 </programlisting> 960 <para> 961 The open and close routines are also quite similar. The only real change is 962 that we now request an interrupt for the camera device interrupt line. If we 963 cannot get the interrupt we report EBUSY to the application and give up. 964 </para> 965 </sect1> 966 <sect1 id="irqvid"> 967 <title>Interrupt Handling</title> 968 <para> 969 Our example handler is for an ISA bus device. If it was PCI you would be 970 able to share the interrupt and would have set IRQF_SHARED to indicate a 971 shared IRQ. We pass the device pointer as the interrupt routine argument. We 972 don't need to since we only support one card but doing this will make it 973 easier to upgrade the driver for multiple devices in the future. 974 </para> 975 <para> 976 Our interrupt routine needs to do little if we assume the card can simply 977 queue one frame to be read after it captures it. 978 </para> 979 <programlisting> 980 981 982 static struct wait_queue *capture_wait; 983 static int capture_ready = 0; 984 985 static void camera_irq(int irq, void *dev_id, 986 struct pt_regs *regs) 987 { 988 capture_ready=1; 989 wake_up_interruptible(&capture_wait); 990 } 991 </programlisting> 992 <para> 993 The interrupt handler is nice and simple for this card as we are assuming 994 the card is buffering the frame for us. This means we have little to do but 995 wake up anybody interested. We also set a capture_ready flag, as we may 996 capture a frame before an application needs it. In this case we need to know 997 that a frame is ready. If we had to collect the frame on the interrupt life 998 would be more complex. 999 </para> 1000 <para> 1001 The two new routines we need to supply are camera_read which returns a 1002 frame, and camera_poll which waits for a frame to become ready. 1003 </para> 1004 <programlisting> 1005 1006 1007 static int camera_poll(struct video_device *dev, 1008 struct file *file, struct poll_table *wait) 1009 { 1010 poll_wait(file, &capture_wait, wait); 1011 if(capture_read) 1012 return POLLIN|POLLRDNORM; 1013 return 0; 1014 } 1015 1016 </programlisting> 1017 <para> 1018 Our wait queue for polling is the capture_wait queue. This will cause the 1019 task to be woken up by our camera_irq routine. We check capture_read to see 1020 if there is an image present and if so report that it is readable. 1021 </para> 1022 </sect1> 1023 <sect1 id="rdvid"> 1024 <title>Reading The Video Image</title> 1025 <programlisting> 1026 1027 1028 static long camera_read(struct video_device *dev, char *buf, 1029 unsigned long count) 1030 { 1031 struct wait_queue wait = { current, NULL }; 1032 u8 *ptr; 1033 int len; 1034 int i; 1035 1036 add_wait_queue(&capture_wait, &wait); 1037 1038 while(!capture_ready) 1039 { 1040 if(file->flags&O_NDELAY) 1041 { 1042 remove_wait_queue(&capture_wait, &wait); 1043 current->state = TASK_RUNNING; 1044 return -EWOULDBLOCK; 1045 } 1046 if(signal_pending(current)) 1047 { 1048 remove_wait_queue(&capture_wait, &wait); 1049 current->state = TASK_RUNNING; 1050 return -ERESTARTSYS; 1051 } 1052 schedule(); 1053 current->state = TASK_INTERRUPTIBLE; 1054 } 1055 remove_wait_queue(&capture_wait, &wait); 1056 current->state = TASK_RUNNING; 1057 1058 </programlisting> 1059 <para> 1060 The first thing we have to do is to ensure that the application waits until 1061 the next frame is ready. The code here is almost identical to the mouse code 1062 we used earlier in this chapter. It is one of the common building blocks of 1063 Linux device driver code and probably one which you will find occurs in any 1064 drivers you write. 1065 </para> 1066 <para> 1067 We wait for a frame to be ready, or for a signal to interrupt our waiting. If a 1068 signal occurs we need to return from the system call so that the signal can 1069 be sent to the application itself. We also check to see if the user actually 1070 wanted to avoid waiting - ie if they are using non-blocking I/O and have other things 1071 to get on with. 1072 </para> 1073 <para> 1074 Next we copy the data from the card to the user application. This is rarely 1075 as easy as our example makes out. We will add capture_w, and capture_h here 1076 to hold the width and height of the captured image. We assume the card only 1077 supports 24bit RGB for now. 1078 </para> 1079 <programlisting> 1080 1081 1082 1083 capture_ready = 0; 1084 1085 ptr=(u8 *)buf; 1086 len = capture_w * 3 * capture_h; /* 24bit RGB */ 1087 1088 if(len>count) 1089 len=count; /* Doesn't all fit */ 1090 1091 for(i=0; i<len; i++) 1092 { 1093 put_user(inb(io+IMAGE_DATA), ptr); 1094 ptr++; 1095 } 1096 1097 hardware_restart_capture(); 1098 1099 return i; 1100 } 1101 1102 </programlisting> 1103 <para> 1104 For a real hardware device you would try to avoid the loop with put_user(). 1105 Each call to put_user() has a time overhead checking whether the accesses to user 1106 space are allowed. It would be better to read a line into a temporary buffer 1107 then copy this to user space in one go. 1108 </para> 1109 <para> 1110 Having captured the image and put it into user space we can kick the card to 1111 get the next frame acquired. 1112 </para> 1113 </sect1> 1114 <sect1 id="iocvid"> 1115 <title>Video Ioctl Handling</title> 1116 <para> 1117 As with the radio driver the major control interface is via the ioctl() 1118 function. Video capture devices support the same tuner calls as a radio 1119 device and also support additional calls to control how the video functions 1120 are handled. In this simple example the card has no tuners to avoid making 1121 the code complex. 1122 </para> 1123 <programlisting> 1124 1125 1126 1127 static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) 1128 { 1129 switch(cmd) 1130 { 1131 case VIDIOCGCAP: 1132 { 1133 struct video_capability v; 1134 v.type = VID_TYPE_CAPTURE|\ 1135 VID_TYPE_CHROMAKEY|\ 1136 VID_TYPE_SCALES|\ 1137 VID_TYPE_OVERLAY; 1138 v.channels = 1; 1139 v.audios = 0; 1140 v.maxwidth = 640; 1141 v.minwidth = 16; 1142 v.maxheight = 480; 1143 v.minheight = 16; 1144 strcpy(v.name, "My Camera"); 1145 if(copy_to_user(arg, &v, sizeof(v))) 1146 return -EFAULT; 1147 return 0; 1148 } 1149 1150 1151 </programlisting> 1152 <para> 1153 The first ioctl we must support and which all video capture and radio 1154 devices are required to support is VIDIOCGCAP. This behaves exactly the same 1155 as with a radio device. This time, however, we report the extra capabilities 1156 we outlined earlier on when defining our video_dev structure. 1157 </para> 1158 <para> 1159 We now set the video flags saying that we support overlay, capture, 1160 scaling and chromakey. We also report size limits - our smallest image is 1161 16x16 pixels, our largest is 640x480. 1162 </para> 1163 <para> 1164 To keep things simple we report no audio and no tuning capabilities at all. 1165 </para> 1166 <programlisting> 1167 1168 case VIDIOCGCHAN: 1169 { 1170 struct video_channel v; 1171 if(copy_from_user(&v, arg, sizeof(v))) 1172 return -EFAULT; 1173 if(v.channel != 0) 1174 return -EINVAL; 1175 v.flags = 0; 1176 v.tuners = 0; 1177 v.type = VIDEO_TYPE_CAMERA; 1178 v.norm = VIDEO_MODE_AUTO; 1179 strcpy(v.name, "Camera Input");break; 1180 if(copy_to_user(&v, arg, sizeof(v))) 1181 return -EFAULT; 1182 return 0; 1183 } 1184 1185 1186 </programlisting> 1187 <para> 1188 This follows what is very much the standard way an ioctl handler looks 1189 in Linux. We copy the data into a kernel space variable and we check that the 1190 request is valid (in this case that the input is 0). Finally we copy the 1191 camera info back to the user. 1192 </para> 1193 <para> 1194 The VIDIOCGCHAN ioctl allows a user to ask about video channels (that is 1195 inputs to the video card). Our example card has a single camera input. The 1196 fields in the structure are 1197 </para> 1198 <table frame="all" id="video_channel_fields"><title>struct video_channel fields</title> 1199 <tgroup cols="2" align="left"> 1200 <tbody> 1201 <row> 1202 1203 <entry>channel</entry><entry>The channel number we are selecting</entry> 1204 </row><row> 1205 <entry>name</entry><entry>The name for this channel. This is intended 1206 to describe the port to the user. 1207 Appropriate names are therefore things like 1208 "Camera" "SCART input"</entry> 1209 </row><row> 1210 <entry>flags</entry><entry>Channel properties</entry> 1211 </row><row> 1212 <entry>type</entry><entry>Input type</entry> 1213 </row><row> 1214 <entry>norm</entry><entry>The current television encoding being used 1215 if relevant for this channel. 1216 </entry> 1217 </row> 1218 </tbody> 1219 </tgroup> 1220 </table> 1221 <table frame="all" id="video_channel_flags"><title>struct video_channel flags</title> 1222 <tgroup cols="2" align="left"> 1223 <tbody> 1224 <row> 1225 <entry>VIDEO_VC_TUNER</entry><entry>Channel has a tuner.</entry> 1226 </row><row> 1227 <entry>VIDEO_VC_AUDIO</entry><entry>Channel has audio.</entry> 1228 </row> 1229 </tbody> 1230 </tgroup> 1231 </table> 1232 <table frame="all" id="video_channel_types"><title>struct video_channel types</title> 1233 <tgroup cols="2" align="left"> 1234 <tbody> 1235 <row> 1236 <entry>VIDEO_TYPE_TV</entry><entry>Television input.</entry> 1237 </row><row> 1238 <entry>VIDEO_TYPE_CAMERA</entry><entry>Fixed camera input.</entry> 1239 </row><row> 1240 <entry>0</entry><entry>Type is unknown.</entry> 1241 </row> 1242 </tbody> 1243 </tgroup> 1244 </table> 1245 <table frame="all" id="video_channel_norms"><title>struct video_channel norms</title> 1246 <tgroup cols="2" align="left"> 1247 <tbody> 1248 <row> 1249 <entry>VIDEO_MODE_PAL</entry><entry>PAL encoded Television</entry> 1250 </row><row> 1251 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC (US) encoded Television</entry> 1252 </row><row> 1253 <entry>VIDEO_MODE_SECAM</entry><entry>SECAM (French) Television </entry> 1254 </row><row> 1255 <entry>VIDEO_MODE_AUTO</entry><entry>Automatic switching, or format does not 1256 matter</entry> 1257 </row> 1258 </tbody> 1259 </tgroup> 1260 </table> 1261 <para> 1262 The corresponding VIDIOCSCHAN ioctl allows a user to change channel and to 1263 request the norm is changed - for example to switch between a PAL or an NTSC 1264 format camera. 1265 </para> 1266 <programlisting> 1267 1268 1269 case VIDIOCSCHAN: 1270 { 1271 struct video_channel v; 1272 if(copy_from_user(&v, arg, sizeof(v))) 1273 return -EFAULT; 1274 if(v.channel != 0) 1275 return -EINVAL; 1276 if(v.norm != VIDEO_MODE_AUTO) 1277 return -EINVAL; 1278 return 0; 1279 } 1280 1281 1282 </programlisting> 1283 <para> 1284 The implementation of this call in our driver is remarkably easy. Because we 1285 are assuming fixed format hardware we need only check that the user has not 1286 tried to change anything. 1287 </para> 1288 <para> 1289 The user also needs to be able to configure and adjust the picture they are 1290 seeing. This is much like adjusting a television set. A user application 1291 also needs to know the palette being used so that it knows how to