Automatic merge of rsync://rsync.kernel.org/pub/scm/linux/kernel/git/gregkh/usb-2...
[linux-2.6] / Documentation / DocBook / videobook.tmpl
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@redhat.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         VID_HARDWARE_MYRADIO,
100         radio_open.
101         radio_close,
102         NULL,                /* no read */
103         NULL,                 /* no write */
104         NULL,                /* no poll */
105         radio_ioctl,
106         NULL,                /* no special init function */
107         NULL                /* no private data */
108 };
109
110
111   </programlisting>
112   <para>
113         This declares our video4linux device driver interface. The VID_TYPE_ value
114         defines what kind of an interface we are, and defines basic capabilities.
115   </para>
116   <para>
117         The only defined value relevant for a radio card is VID_TYPE_TUNER which
118         indicates that the device can be tuned. Clearly our radio is going to have some
119         way to change channel so it is tuneable.
120   </para>
121   <para>
122         The VID_HARDWARE_ types are unique to each device. Numbers are assigned by
123         <email>alan@redhat.com</email> when device drivers are going to be released. Until then you
124         can pull a suitably large number out of your hat and use it. 10000 should be
125         safe for a very long time even allowing for the huge number of vendors
126         making new and different radio cards at the moment.
127   </para>
128   <para>
129         We declare an open and close routine, but we do not need read or write,
130         which are used to read and write video data to or from the card itself. As
131         we have no read or write there is no poll function.
132   </para>
133   <para>
134         The private initialise function is run when the device is registered. In
135         this driver we've already done all the work needed. The final pointer is a
136         private data pointer that can be used by the device driver to attach and
137         retrieve private data structures. We set this field "priv" to NULL for
138         the moment.
139   </para>
140   <para>
141         Having the structure defined is all very well but we now need to register it
142         with the kernel. 
143   </para>
144   <programlisting>
145
146
147 static int io = 0x320;
148
149 int __init myradio_init(struct video_init *v)
150 {
151         if(!request_region(io, MY_IO_SIZE, "myradio"))
152         {
153                 printk(KERN_ERR 
154                     "myradio: port 0x%03X is in use.\n", io);
155                 return -EBUSY;
156         }
157
158         if(video_device_register(&amp;my_radio, VFL_TYPE_RADIO)==-1) {
159                 release_region(io, MY_IO_SIZE);
160                 return -EINVAL;
161         }               
162         return 0;
163 }
164
165   </programlisting>
166   <para>
167         The first stage of the initialisation, as is normally the case, is to check 
168         that the I/O space we are about to fiddle with doesn't belong to some other 
169         driver. If it is we leave well alone. If the user gives the address of the 
170         wrong device then we will spot this. These policies will generally avoid 
171         crashing the machine.
172   </para>
173   <para>
174         Now we ask the Video4Linux layer to register the device for us. We hand it
175         our carefully designed video_device structure and also tell it which group
176         of devices we want it registered with. In this case VFL_TYPE_RADIO.
177   </para>
178   <para>
179         The types available are
180   </para>
181    <table frame="all"><title>Device Types</title>
182    <tgroup cols="3" align="left">
183    <tbody>
184    <row>
185         <entry>VFL_TYPE_RADIO</entry><entry>/dev/radio{n}</entry><entry>
186
187         Radio devices are assigned in this block. As with all of these
188         selections the actual number assignment is done by the video layer
189         accordijng to what is free.</entry>
190         </row><row>
191         <entry>VFL_TYPE_GRABBER</entry><entry>/dev/video{n}</entry><entry>
192         Video capture devices and also -- counter-intuitively for the name --
193         hardware video playback devices such as MPEG2 cards.</entry>
194         </row><row>
195         <entry>VFL_TYPE_VBI</entry><entry>/dev/vbi{n}</entry><entry>
196         The VBI devices capture the hidden lines on a television picture
197         that carry further information like closed caption data, teletext
198         (primarily in Europe) and now Intercast and the ATVEC internet
199         television encodings.</entry>
200         </row><row>
201         <entry>VFL_TYPE_VTX</entry><entry>/dev/vtx[n}</entry><entry>
202         VTX is 'Videotext' also known as 'Teletext'. This is a system for
203         sending numbered, 40x25, mostly textual page images over the hidden
204         lines. Unlike the /dev/vbi interfaces, this is for 'smart' decoder 
205         chips. (The use of the word smart here has to be taken in context,
206         the smartest teletext chips are fairly dumb pieces of technology).
207         </entry>
208     </row>
209     </tbody>
210     </tgroup>
211     </table>
212   <para>
213         We are most definitely a radio.
214   </para>
215   <para>
216         Finally we allocate our I/O space so that nobody treads on us and return 0
217         to signify general happiness with the state of the universe.
218   </para>
219   </sect1>
220   <sect1 id="openradio">
221   <title>Opening And Closing The Radio</title>
222
223   <para>
224         The functions we declared in our video_device are mostly very simple.
225         Firstly we can drop in what is basically standard code for open and close. 
226   </para>
227   <programlisting>
228
229
230 static int users = 0;
231
232 static int radio_open(stuct video_device *dev, int flags)
233 {
234         if(users)
235                 return -EBUSY;
236         users++;
237         return 0;
238 }
239
240   </programlisting>
241   <para>
242         At open time we need to do nothing but check if someone else is also using
243         the radio card. If nobody is using it we make a note that we are using it,
244         then we ensure that nobody unloads our driver on us.
245   </para>
246   <programlisting>
247
248
249 static int radio_close(struct video_device *dev)
250 {
251         users--;
252 }
253
254   </programlisting>
255   <para>
256         At close time we simply need to reduce the user count and allow the module
257         to become unloadable.
258   </para>
259   <para>
260         If you are sharp you will have noticed neither the open nor the close
261         routines attempt to reset or change the radio settings. This is intentional.
262         It allows an application to set up the radio and exit. It avoids a user
263         having to leave an application running all the time just to listen to the
264         radio. 
265   </para>
266   </sect1>
267   <sect1 id="ioctlradio">
268   <title>The Ioctl Interface</title>
269   <para>
270         This leaves the ioctl routine, without which the driver will not be
271         terribly useful to anyone.
272   </para>
273   <programlisting>
274
275
276 static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg)
277 {
278         switch(cmd)
279         {
280                 case VIDIOCGCAP:
281                 {
282                         struct video_capability v;
283                         v.type = VID_TYPE_TUNER;
284                         v.channels = 1;
285                         v.audios = 1;
286                         v.maxwidth = 0;
287                         v.minwidth = 0;
288                         v.maxheight = 0;
289                         v.minheight = 0;
290                         strcpy(v.name, "My Radio");
291                         if(copy_to_user(arg, &amp;v, sizeof(v)))
292                                 return -EFAULT;
293                         return 0;
294                 }
295
296   </programlisting>
297   <para>
298         VIDIOCGCAP is the first ioctl all video4linux devices must support. It
299         allows the applications to find out what sort of a card they have found and
300         to figure out what they want to do about it. The fields in the structure are
301   </para>
302    <table frame="all"><title>struct video_capability fields</title>
303    <tgroup cols="2" align="left">
304    <tbody>
305    <row>
306         <entry>name</entry><entry>The device text name. This is intended for the user.</entry>
307         </row><row>
308         <entry>channels</entry><entry>The number of different channels you can tune on
309                         this card. It could even by zero for a card that has
310                         no tuning capability. For our simple FM radio it is 1. 
311                         An AM/FM radio would report 2.</entry>
312         </row><row>
313         <entry>audios</entry><entry>The number of audio inputs on this device. For our
314                         radio there is only one audio input.</entry>
315         </row><row>
316         <entry>minwidth,minheight</entry><entry>The smallest size the card is capable of capturing
317                         images in. We set these to zero. Radios do not
318                         capture pictures</entry>
319         </row><row>
320         <entry>maxwidth,maxheight</entry><entry>The largest image size the card is capable of
321                                       capturing. For our radio we report 0.
322                                 </entry>
323         </row><row>
324         <entry>type</entry><entry>This reports the capabilities of the device, and
325                         matches the field we filled in in the struct
326                         video_device when registering.</entry>
327     </row>
328     </tbody>
329     </tgroup>
330     </table>
331   <para>
332         Having filled in the fields, we use copy_to_user to copy the structure into
333         the users buffer. If the copy fails we return an EFAULT to the application
334         so that it knows it tried to feed us garbage.
335   </para>
336   <para>
337         The next pair of ioctl operations select which tuner is to be used and let
338         the application find the tuner properties. We have only a single FM band
339         tuner in our example device.
340   </para>
341   <programlisting>
342
343
344                 case VIDIOCGTUNER:
345                 {
346                         struct video_tuner v;
347                         if(copy_from_user(&amp;v, arg, sizeof(v))!=0)
348                                 return -EFAULT;
349                         if(v.tuner)
350                                 return -EINVAL;
351                         v.rangelow=(87*16000);
352                         v.rangehigh=(108*16000);
353                         v.flags = VIDEO_TUNER_LOW;
354                         v.mode = VIDEO_MODE_AUTO;
355                         v.signal = 0xFFFF;
356                         strcpy(v.name, "FM");
357                         if(copy_to_user(&amp;v, arg, sizeof(v))!=0)
358                                 return -EFAULT;
359                         return 0;
360                 }
361
362   </programlisting>
363   <para>
364         The VIDIOCGTUNER ioctl allows applications to query a tuner. The application
365         sets the tuner field to the tuner number it wishes to query. The query does
366         not change the tuner that is being used, it merely enquires about the tuner
367         in question.
368   </para>
369   <para>
370         We have exactly one tuner so after copying the user buffer to our temporary
371         structure we complain if they asked for a tuner other than tuner 0. 
372   </para>
373   <para>
374         The video_tuner structure has the following fields
375   </para>
376    <table frame="all"><title>struct video_tuner fields</title>
377    <tgroup cols="2" align="left">
378    <tbody>
379    <row>
380         <entry>int tuner</entry><entry>The number of the tuner in question</entry>
381    </row><row>
382         <entry>char name[32]</entry><entry>A text description of this tuner. "FM" will do fine.
383                         This is intended for the application.</entry>
384    </row><row>
385         <entry>u32 flags</entry>
386         <entry>Tuner capability flags</entry>
387    </row>
388    <row>
389         <entry>u16 mode</entry><entry>The current reception mode</entry>
390
391    </row><row>
392         <entry>u16 signal</entry><entry>The signal strength scaled between 0 and 65535. If
393                         a device cannot tell the signal strength it should
394                         report 65535. Many simple cards contain only a 
395                         signal/no signal bit. Such cards will report either
396                         0 or 65535.</entry>
397
398    </row><row>
399         <entry>u32 rangelow, rangehigh</entry><entry>
400                         The range of frequencies supported by the radio
401                         or TV. It is scaled according to the VIDEO_TUNER_LOW
402                         flag.</entry>
403
404     </row>
405     </tbody>
406     </tgroup>
407     </table>
408
409    <table frame="all"><title>struct video_tuner flags</title>
410    <tgroup cols="2" align="left">
411    <tbody>
412    <row>
413         <entry>VIDEO_TUNER_PAL</entry><entry>A PAL TV tuner</entry>
414         </row><row>
415         <entry>VIDEO_TUNER_NTSC</entry><entry>An NTSC (US) TV tuner</entry>
416         </row><row>
417         <entry>VIDEO_TUNER_SECAM</entry><entry>A SECAM (French) TV tuner</entry>
418         </row><row>
419         <entry>VIDEO_TUNER_LOW</entry><entry>
420              The tuner frequency is scaled in 1/16th of a KHz
421              steps. If not it is in 1/16th of a MHz steps
422         </entry>
423         </row><row>
424         <entry>VIDEO_TUNER_NORM</entry><entry>The tuner can set its format</entry>
425         </row><row>
426         <entry>VIDEO_TUNER_STEREO_ON</entry><entry>The tuner is currently receiving a stereo signal</entry>
427         </row>
428     </tbody>
429     </tgroup>
430     </table>
431
432    <table frame="all"><title>struct video_tuner modes</title>
433    <tgroup cols="2" align="left">
434    <tbody>
435    <row>
436                 <entry>VIDEO_MODE_PAL</entry><entry>PAL Format</entry>
437    </row><row>
438                 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC Format (USA)</entry>
439    </row><row>
440                 <entry>VIDEO_MODE_SECAM</entry><entry>French Format</entry>
441    </row><row>
442                 <entry>VIDEO_MODE_AUTO</entry><entry>A device that does not need to do
443                                         TV format switching</entry>
444    </row>
445     </tbody>
446     </tgroup>
447     </table>
448   <para>
449         The settings for the radio card are thus fairly simple. We report that we
450         are a tuner called "FM" for FM radio. In order to get the best tuning
451         resolution we report VIDEO_TUNER_LOW and select tuning to 1/16th of KHz. Its
452         unlikely our card can do that resolution but it is a fair bet the card can
453         do better than 1/16th of a MHz. VIDEO_TUNER_LOW is appropriate to almost all
454         radio usage.
455   </para>
456   <para>
457         We report that the tuner automatically handles deciding what format it is
458         receiving - true enough as it only handles FM radio. Our example card is
459         also incapable of detecting stereo or signal strengths so it reports a
460         strength of 0xFFFF (maximum) and no stereo detected.
461   </para>
462   <para>
463         To finish off we set the range that can be tuned to be 87-108Mhz, the normal
464         FM broadcast radio range. It is important to find out what the card is
465         actually capable of tuning. It is easy enough to simply use the FM broadcast
466         range. Unfortunately if you do this you will discover the FM broadcast
467         ranges in the USA, Europe and Japan are all subtly different and some users
468         cannot receive all the stations they wish.
469   </para>
470   <para>
471         The application also needs to be able to set the tuner it wishes to use. In
472         our case, with a single tuner this is rather simple to arrange.
473   </para>
474   <programlisting>
475
476                 case VIDIOCSTUNER:
477                 {
478                         struct video_tuner v;
479                         if(copy_from_user(&amp;v, arg, sizeof(v)))
480                                 return -EFAULT;
481                         if(v.tuner != 0)
482                                 return -EINVAL;
483                         return 0;
484                 }
485
486   </programlisting>
487   <para>
488         We copy the user supplied structure into kernel memory so we can examine it. 
489         If the user has selected a tuner other than zero we reject the request. If 
490         they wanted tuner 0 then, surprisingly enough, that is the current tuner already.
491   </para>
492   <para>
493         The next two ioctls we need to provide are to get and set the frequency of
494         the radio. These both use an unsigned long argument which is the frequency.
495         The scale of the frequency depends on the VIDEO_TUNER_LOW flag as I
496         mentioned earlier on. Since we have VIDEO_TUNER_LOW set this will be in
497         1/16ths of a KHz.
498   </para>
499   <programlisting>
500
501 static unsigned long current_freq;
502
503
504
505                 case VIDIOCGFREQ:
506                         if(copy_to_user(arg, &amp;current_freq, 
507                                 sizeof(unsigned long))
508                                 return -EFAULT;
509                         return 0;
510
511   </programlisting>
512   <para>
513         Querying the frequency in our case is relatively simple. Our radio card is
514         too dumb to let us query the signal strength so we remember our setting if 
515         we know it. All we have to do is copy it to the user.
516   </para>
517   <programlisting>
518
519
520                 case VIDIOCSFREQ:
521                 {
522                         u32 freq;
523                         if(copy_from_user(arg, &amp;freq, 
524                                 sizeof(unsigned long))!=0)
525                                 return -EFAULT;
526                         if(hardware_set_freq(freq)&lt;0)
527                                 return -EINVAL;
528                         current_freq = freq;
529                         return 0;
530                 }
531
532   </programlisting>
533   <para>
534         Setting the frequency is a little more complex. We begin by copying the
535         desired frequency into kernel space. Next we call a hardware specific routine
536         to set the radio up. This might be as simple as some scaling and a few
537         writes to an I/O port. For most radio cards it turns out a good deal more
538         complicated and may involve programming things like a phase locked loop on
539         the card. This is what documentation is for. 
540   </para>
541   <para>
542         The final set of operations we need to provide for our radio are the 
543         volume controls. Not all radio cards can even do volume control. After all
544         there is a perfectly good volume control on the sound card. We will assume
545         our radio card has a simple 4 step volume control.
546   </para>
547   <para>
548         There are two ioctls with audio we need to support
549   </para>
550   <programlisting>
551
552 static int current_volume=0;
553
554                 case VIDIOCGAUDIO:
555                 {
556                         struct video_audio v;
557                         if(copy_from_user(&amp;v, arg, sizeof(v)))
558                                 return -EFAULT;
559                         if(v.audio != 0)
560                                 return -EINVAL;
561                         v.volume = 16384*current_volume;
562                         v.step = 16384;
563                         strcpy(v.name, "Radio");
564                         v.mode = VIDEO_SOUND_MONO;
565                         v.balance = 0;
566                         v.base = 0;
567                         v.treble = 0;
568                         
569                         if(copy_to_user(arg. &amp;v, sizeof(v)))
570                                 return -EFAULT;
571                         return 0;
572                 }
573
574   </programlisting>
575   <para>
576         Much like the tuner we start by copying the user structure into kernel
577         space. Again we check if the user has asked for a valid audio input. We have
578         only input 0 and we punt if they ask for another input.
579   </para>
580   <para>
581         Then we fill in the video_audio structure. This has the following format
582   </para>
583    <table frame="all"><title>struct video_audio fields</title>
584    <tgroup cols="2" align="left">
585    <tbody>
586    <row>
587    <entry>audio</entry><entry>The input the user wishes to query</entry>
588    </row><row>
589    <entry>volume</entry><entry>The volume setting on a scale of 0-65535</entry>
590    </row><row>
591    <entry>base</entry><entry>The base level on a scale of 0-65535</entry>
592    </row><row>
593    <entry>treble</entry><entry>The treble level on a scale of 0-65535</entry>
594    </row><row>
595    <entry>flags</entry><entry>The features this audio device supports
596    </entry>
597    </row><row>
598    <entry>name</entry><entry>A text name to display to the user. We picked
599                         "Radio" as it explains things quite nicely.</entry>
600    </row><row>
601    <entry>mode</entry><entry>The current reception mode for the audio
602
603                 We report MONO because our card is too stupid to know if it is in
604                 mono or stereo. 
605    </entry>
606    </row><row>
607    <entry>balance</entry><entry>The stereo balance on a scale of 0-65535, 32768 is
608                         middle.</entry>
609    </row><row>
610    <entry>step</entry><entry>The step by which the volume control jumps. This is
611                         used to help make it easy for applications to set 
612                         slider behaviour.</entry>
613    </row>
614    </tbody>
615    </tgroup>
616    </table>
617
618    <table frame="all"><title>struct video_audio flags</title>
619    <tgroup cols="2" align="left">
620    <tbody>
621    <row>
622                 <entry>VIDEO_AUDIO_MUTE</entry><entry>The audio is currently muted. We
623                                         could fake this in our driver but we
624                                         choose not to bother.</entry>
625    </row><row>
626                 <entry>VIDEO_AUDIO_MUTABLE</entry><entry>The input has a mute option</entry>
627    </row><row>
628                 <entry>VIDEO_AUDIO_TREBLE</entry><entry>The  input has a treble control</entry>
629    </row><row>
630                 <entry>VIDEO_AUDIO_BASS</entry><entry>The input has a base control</entry>
631    </row>
632    </tbody>
633    </tgroup>
634    </table>
635
636    <table frame="all"><title>struct video_audio modes</title>
637    <tgroup cols="2" align="left">
638    <tbody>
639    <row>
640                 <entry>VIDEO_SOUND_MONO</entry><entry>Mono sound</entry>
641    </row><row>
642                 <entry>VIDEO_SOUND_STEREO</entry><entry>Stereo sound</entry>
643    </row><row>
644                 <entry>VIDEO_SOUND_LANG1</entry><entry>Alternative language 1 (TV specific)</entry>
645    </row><row>
646                 <entry>VIDEO_SOUND_LANG2</entry><entry>Alternative language 2 (TV specific)</entry>
647    </row>
648    </tbody>
649    </tgroup>
650    </table>
651   <para>
652         Having filled in the structure we copy it back to user space.
653   </para>
654   <para>
655         The VIDIOCSAUDIO ioctl allows the user to set the audio parameters in the
656         video_audio structure. The driver does its best to honour the request.
657   </para>
658   <programlisting>
659
660                 case VIDIOCSAUDIO:
661                 {
662                         struct video_audio v;
663                         if(copy_from_user(&amp;v, arg, sizeof(v)))
664                                 return -EFAULT;
665                         if(v.audio)
666                                 return -EINVAL;
667                         current_volume = v/16384;
668                         hardware_set_volume(current_volume);
669                         return 0;
670                 }
671
672   </programlisting>
673   <para>
674         In our case there is very little that the user can set. The volume is
675         basically the limit. Note that we could pretend to have a mute feature
676         by rewriting this to 
677   </para>
678   <programlisting>
679
680                 case VIDIOCSAUDIO:
681                 {
682                         struct video_audio v;
683                         if(copy_from_user(&amp;v, arg, sizeof(v)))
684                                 return -EFAULT;
685                         if(v.audio)
686                                 return -EINVAL;
687                         current_volume = v/16384;
688                         if(v.flags&amp;VIDEO_AUDIO_MUTE)
689                                 hardware_set_volume(0);
690                         else
691                                 hardware_set_volume(current_volume);
692                         current_muted = v.flags &amp; 
693                                               VIDEO_AUDIO_MUTE;
694                         return 0;
695                 }
696
697   </programlisting>
698   <para>
699         This with the corresponding changes to the VIDIOCGAUDIO code to report the
700         state of the mute flag we save and to report the card has a mute function,
701         will allow applications to use a mute facility with this card. It is
702         questionable whether this is a good idea however. User applications can already
703         fake this themselves and kernel space is precious.
704   </para>
705   <para>
706         We now have a working radio ioctl handler. So we just wrap up the function
707   </para>
708   <programlisting>
709
710
711         }
712         return -ENOIOCTLCMD;
713 }
714
715   </programlisting>
716   <para>
717         and pass the Video4Linux layer back an error so that it knows we did not
718         understand the request we got passed.
719   </para>
720   </sect1>
721   <sect1 id="modradio">
722   <title>Module Wrapper</title>
723   <para>
724         Finally we add in the usual module wrapping and the driver is done.
725   </para>
726   <programlisting>
727
728 #ifndef MODULE
729
730 static int io = 0x300;
731
732 #else
733
734 static int io = -1;
735
736 #endif
737
738 MODULE_AUTHOR("Alan Cox");
739 MODULE_DESCRIPTION("A driver for an imaginary radio card.");
740 module_param(io, int, 0444);
741 MODULE_PARM_DESC(io, "I/O address of the card.");
742
743 static int __init init(void)
744 {
745         if(io==-1)
746         {
747                 printk(KERN_ERR 
748          "You must set an I/O address with io=0x???\n");
749                 return -EINVAL;
750         }
751         return myradio_init(NULL);
752 }
753
754 static void __exit cleanup(void)
755 {
756         video_unregister_device(&amp;my_radio);
757         release_region(io, MY_IO_SIZE);
758 }
759
760 module_init(init);
761 module_exit(cleanup);
762
763   </programlisting>
764   <para>
765         In this example we set the IO base by default if the driver is compiled into
766         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
767         user sets the parameter. We set io to a nonsense port (-1) so that we can
768         tell if the user supplied an io parameter or not.
769   </para>
770   <para>
771         We use MODULE_ defines to give an author for the card driver and a
772         description. We also use them to declare that io is an integer and it is the
773         address of the card, and can be read by anyone from sysfs.
774   </para>
775   <para>
776         The clean-up routine unregisters the video_device we registered, and frees
777         up the I/O space. Note that the unregister takes the actual video_device
778         structure as its argument. Unlike the file operations structure which can be
779         shared by all instances of a device a video_device structure as an actual
780         instance of the device. If you are registering multiple radio devices you
781         need to fill in one structure per device (most likely by setting up a
782         template and copying it to each of the actual device structures).
783   </para>
784   </sect1>
785   </chapter>
786   <chapter>
787         <title>Video Capture Devices</title>
788   <sect1 id="introvid">
789   <title>Video Capture Device Types</title>
790   <para>
791         The video capture devices share the same interfaces as radio devices. In
792         order to explain the video capture interface I will use the example of a
793         camera that has no tuners or audio input. This keeps the example relatively
794         clean. To get both combine the two driver examples.
795   </para>
796   <para>
797         Video capture devices divide into four categories. A little technology
798         backgrounder. Full motion video even at television resolution (which is
799         actually fairly low) is pretty resource-intensive. You are continually
800         passing megabytes of data every second from the capture card to the display. 
801         several alternative approaches have emerged because copying this through the 
802         processor and the user program is a particularly bad idea .
803   </para>
804   <para>
805         The first is to add the television image onto the video output directly.
806         This is also how some 3D cards work. These basic cards can generally drop the
807         video into any chosen rectangle of the display. Cards like this, which
808         include most mpeg1 cards that used the feature connector,  aren't very
809         friendly in a windowing environment. They don't understand windows or
810         clipping. The video window is always on the top of the display.
811   </para>
812   <para>
813         Chroma keying is a technique used by cards to get around this. It is an old
814         television mixing trick where you mark all the areas you wish to replace
815         with a single clear colour that isn't used in the image - TV people use an
816         incredibly bright blue while computing people often use a particularly
817         virulent purple. Bright blue occurs on the desktop. Anyone with virulent
818         purple windows has another problem besides their TV overlay.
819   </para>
820   <para>
821         The third approach is to copy the data from the capture card to the video
822         card, but to do it directly across the PCI bus. This relieves the processor
823         from doing the work but does require some smartness on the part of the video
824         capture chip, as well as a suitable video card. Programming this kind of
825         card and more so debugging it can be extremely tricky. There are some quite
826         complicated interactions with the display and you may also have to cope with
827         various chipset bugs that show up when PCI cards start talking to each
828         other. 
829   </para>
830   <para>
831         To keep our example fairly simple we will assume a card that supports
832         overlaying a flat rectangular image onto the frame buffer output, and which
833         can also capture stuff into processor memory.
834   </para>
835   </sect1>
836   <sect1 id="regvid">
837   <title>Registering Video Capture Devices</title>
838   <para>
839         This time we need to add more functions for our camera device.
840   </para>
841   <programlisting>
842 static struct video_device my_camera
843 {
844         "My Camera",
845         VID_TYPE_OVERLAY|VID_TYPE_SCALES|\
846         VID_TYPE_CAPTURE|VID_TYPE_CHROMAKEY,
847         VID_HARDWARE_MYCAMERA,
848         camera_open.
849         camera_close,
850         camera_read,      /* no read */
851         NULL,             /* no write */
852         camera_poll,      /* no poll */
853         camera_ioctl,
854         NULL,             /* no special init function */
855         NULL              /* no private data */
856 };
857   </programlisting>
858   <para>
859         We need a read() function which is used for capturing data from
860         the card, and we need a poll function so that a driver can wait for the next
861         frame to be captured.
862   </para>
863   <para>
864         We use the extra video capability flags that did not apply to the
865         radio interface. The video related flags are
866   </para>
867    <table frame="all"><title>Capture Capabilities</title>
868    <tgroup cols="2" align="left">
869    <tbody>
870    <row>
871 <entry>VID_TYPE_CAPTURE</entry><entry>We support image capture</entry>
872 </row><row>
873 <entry>VID_TYPE_TELETEXT</entry><entry>A teletext capture device (vbi{n])</entry>
874 </row><row>
875 <entry>VID_TYPE_OVERLAY</entry><entry>The image can be directly overlaid onto the
876                                 frame buffer</entry>
877 </row><row>
878 <entry>VID_TYPE_CHROMAKEY</entry><entry>Chromakey can be used to select which parts
879                                 of the image to display</entry>
880 </row><row>
881 <entry>VID_TYPE_CLIPPING</entry><entry>It is possible to give the board a list of
882                                 rectangles to draw around. </entry>
883 </row><row>
884 <entry>VID_TYPE_FRAMERAM</entry><entry>The video capture goes into the video memory
885                                 and actually changes it. Applications need
886                                 to know this so they can clean up after the
887                                 card</entry>
888 </row><row>
889 <entry>VID_TYPE_SCALES</entry><entry>The image can be scaled to various sizes,
890                                 rather than being a single fixed size.</entry>
891 </row><row>
892 <entry>VID_TYPE_MONOCHROME</entry><entry>The capture will be monochrome. This isn't a
893                                 complete answer to the question since a mono
894                                 camera on a colour capture card will still
895                                 produce mono output.</entry>
896 </row><row>
897 <entry>VID_TYPE_SUBCAPTURE</entry><entry>The card allows only part of its field of
898                                 view to be captured. This enables
899                                 applications to avoid copying all of a large
900                                 image into memory when only some section is
901                                 relevant.</entry>
902     </row>
903     </tbody>
904     </tgroup>
905     </table>
906   <para>
907         We set VID_TYPE_CAPTURE so that we are seen as a capture card,
908         VID_TYPE_CHROMAKEY so the application knows it is time to draw in virulent
909         purple, and VID_TYPE_SCALES because we can be resized.
910   </para>
911   <para>
912         Our setup is fairly similar. This time we also want an interrupt line
913         for the 'frame captured' signal. Not all cards have this so some of them
914         cannot handle poll().
915   </para>
916   <programlisting>
917
918
919 static int io = 0x320;
920 static int irq = 11;
921
922 int __init mycamera_init(struct video_init *v)
923 {
924         if(!request_region(io, MY_IO_SIZE, "mycamera"))
925         {
926                 printk(KERN_ERR 
927                       "mycamera: port 0x%03X is in use.\n", io);
928                 return -EBUSY;
929         }
930
931         if(video_device_register(&amp;my_camera, 
932             VFL_TYPE_GRABBER)==-1) {
933                 release_region(io, MY_IO_SIZE);
934                 return -EINVAL;
935         }
936         return 0;
937 }
938
939   </programlisting>
940   <para>
941         This is little changed from the needs of the radio card. We specify
942         VFL_TYPE_GRABBER this time as we want to be allocated a /dev/video name.
943   </para>
944   </sect1>
945   <sect1 id="opvid">
946   <title>Opening And Closing The Capture Device</title>
947   <programlisting>
948
949
950 static int users = 0;
951
952 static int camera_open(stuct video_device *dev, int flags)
953 {
954         if(users)
955                 return -EBUSY;
956         if(request_irq(irq, camera_irq, 0, "camera", dev)&lt;0)
957                 return -EBUSY;
958         users++;
959         return 0;
960 }
961
962
963 static int camera_close(struct video_device *dev)
964 {
965         users--;
966         free_irq(irq, dev);
967 }
968   </programlisting>
969   <para>
970         The open and close routines are also quite similar. The only real change is
971         that we now request an interrupt for the camera device interrupt line. If we
972         cannot get the interrupt we report EBUSY to the application and give up.
973   </para>
974   </sect1>
975   <sect1 id="irqvid">
976   <title>Interrupt Handling</title>
977   <para>
978         Our example handler is for an ISA bus device. If it was PCI you would be
979         able to share the interrupt and would have set SA_SHIRQ to indicate a 
980         shared IRQ. We pass the device pointer as the interrupt routine argument. We
981         don't need to since we only support one card but doing this will make it
982         easier to upgrade the driver for multiple devices in the future.
983   </para>
984   <para>
985         Our interrupt routine needs to do little if we assume the card can simply
986         queue one frame to be read after it captures it. 
987   </para>
988   <programlisting>
989
990
991 static struct wait_queue *capture_wait;
992 static int capture_ready = 0;
993
994 static void camera_irq(int irq, void *dev_id, 
995                           struct pt_regs *regs)
996 {
997         capture_ready=1;
998         wake_up_interruptible(&amp;capture_wait);
999 }
1000   </programlisting>
1001   <para>
1002         The interrupt handler is nice and simple for this card as we are assuming
1003         the card is buffering the frame for us. This means we have little to do but
1004         wake up        anybody interested. We also set a capture_ready flag, as we may
1005         capture a frame before an application needs it. In this case we need to know
1006         that a frame is ready. If we had to collect the frame on the interrupt life
1007         would be more complex.
1008   </para>
1009   <para>
1010         The two new routines we need to supply are camera_read which returns a
1011         frame, and camera_poll which waits for a frame to become ready.
1012   </para>
1013   <programlisting>
1014
1015
1016 static int camera_poll(struct video_device *dev, 
1017         struct file *file, struct poll_table *wait)
1018 {
1019         poll_wait(file, &amp;capture_wait, wait);
1020         if(capture_read)
1021                 return POLLIN|POLLRDNORM;
1022         return 0;
1023 }
1024
1025   </programlisting>
1026   <para>
1027         Our wait queue for polling is the capture_wait queue. This will cause the
1028         task to be woken up by our camera_irq routine. We check capture_read to see
1029         if there is an image present and if so report that it is readable.
1030   </para>
1031   </sect1>
1032   <sect1 id="rdvid">
1033   <title>Reading The Video Image</title>
1034   <programlisting>
1035
1036
1037 static long camera_read(struct video_device *dev, char *buf,
1038                                 unsigned long count)
1039 {
1040         struct wait_queue wait = { current, NULL };
1041         u8 *ptr;
1042         int len;
1043         int i;
1044
1045         add_wait_queue(&amp;capture_wait, &amp;wait);
1046
1047         while(!capture_ready)
1048         {
1049                 if(file->flags&amp;O_NDELAY)
1050                 {
1051                         remove_wait_queue(&amp;capture_wait, &amp;wait);
1052                         current->state = TASK_RUNNING;
1053                         return -EWOULDBLOCK;
1054                 }
1055                 if(signal_pending(current))
1056                 {
1057                         remove_wait_queue(&amp;capture_wait, &amp;wait);
1058                         current->state = TASK_RUNNING;
1059                         return -ERESTARTSYS;
1060                 }
1061                 schedule();
1062                 current->state = TASK_INTERRUPTIBLE;
1063         }
1064         remove_wait_queue(&amp;capture_wait, &amp;wait);
1065         current->state = TASK_RUNNING;
1066
1067   </programlisting>
1068   <para>
1069         The first thing we have to do is to ensure that the application waits until
1070         the next frame is ready. The code here is almost identical to the mouse code
1071         we used earlier in this chapter. It is one of the common building blocks of
1072         Linux device driver code and probably one which you will find occurs in any
1073         drivers you write.
1074   </para>
1075   <para>
1076         We wait for a frame to be ready, or for a signal to interrupt our waiting. If a
1077         signal occurs we need to return from the system call so that the signal can
1078         be sent to the application itself. We also check to see if the user actually
1079         wanted to avoid waiting - ie  if they are using non-blocking I/O and have other things 
1080         to get on with.
1081   </para>
1082   <para>
1083         Next we copy the data from the card to the user application. This is rarely
1084         as easy as our example makes out. We will add capture_w, and capture_h here
1085         to hold the width and height of the captured image. We assume the card only
1086         supports 24bit RGB for now.
1087   </para>
1088   <programlisting>
1089
1090
1091
1092         capture_ready = 0;
1093
1094         ptr=(u8 *)buf;
1095         len = capture_w * 3 * capture_h; /* 24bit RGB */
1096
1097         if(len>count)
1098                 len=count;  /* Doesn't all fit */
1099
1100         for(i=0; i&lt;len; i++)
1101         {
1102                 put_user(inb(io+IMAGE_DATA), ptr);
1103                 ptr++;
1104         }
1105
1106         hardware_restart_capture();
1107                 
1108         return i;
1109 }
1110
1111   </programlisting>
1112   <para>
1113         For a real hardware device you would try to avoid the loop with put_user().
1114         Each call to put_user() has a time overhead checking whether the accesses to user
1115         space are allowed. It would be better to read a line into a temporary buffer
1116         then copy this to user space in one go.
1117   </para>
1118   <para>
1119         Having captured the image and put it into user space we can kick the card to
1120         get the next frame acquired.
1121   </para>
1122   </sect1>
1123   <sect1 id="iocvid">
1124   <title>Video Ioctl Handling</title>
1125   <para>
1126         As with the radio driver the major control interface is via the ioctl()
1127         function. Video capture devices support the same tuner calls as a radio
1128         device and also support additional calls to control how the video functions
1129         are handled. In this simple example the card has no tuners to avoid making
1130         the code complex. 
1131   </para>
1132   <programlisting>
1133
1134
1135
1136 static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg)
1137 {
1138         switch(cmd)
1139         {
1140                 case VIDIOCGCAP:
1141                 {
1142                         struct video_capability v;
1143                         v.type = VID_TYPE_CAPTURE|\
1144                                  VID_TYPE_CHROMAKEY|\
1145                                  VID_TYPE_SCALES|\
1146                                  VID_TYPE_OVERLAY;
1147                         v.channels = 1;
1148                         v.audios = 0;
1149                         v.maxwidth = 640;
1150                         v.minwidth = 16;
1151                         v.maxheight = 480;
1152                         v.minheight = 16;
1153                         strcpy(v.name, "My Camera");
1154                         if(copy_to_user(arg, &amp;v, sizeof(v)))
1155                                 return -EFAULT;
1156                         return 0;
1157                 }
1158
1159
1160   </programlisting>
1161   <para>
1162         The first ioctl we must support and which all video capture and radio
1163         devices are required to support is VIDIOCGCAP. This behaves exactly the same
1164         as with a radio device. This time, however, we report the extra capabilities
1165         we outlined earlier on when defining our video_dev structure.
1166   </para>
1167   <para>
1168         We now set the video flags saying that we support overlay, capture,
1169         scaling and chromakey. We also report size limits - our smallest image is
1170         16x16 pixels, our largest is 640x480. 
1171   </para>
1172   <para>
1173         To keep things simple we report no audio and no tuning capabilities at all.
1174   </para>
1175   <programlisting>        
1176
1177                 case VIDIOCGCHAN:
1178                 {
1179                         struct video_channel v;
1180                         if(copy_from_user(&amp;v, arg, sizeof(v)))
1181                                 return -EFAULT;
1182                         if(v.channel != 0)
1183                                 return -EINVAL;
1184                         v.flags = 0;
1185                         v.tuners = 0;
1186                         v.type = VIDEO_TYPE_CAMERA;
1187                         v.norm = VIDEO_MODE_AUTO;
1188                         strcpy(v.name, "Camera Input");break;
1189                         if(copy_to_user(&amp;v, arg, sizeof(v)))
1190                                 return -EFAULT;
1191                         return 0;
1192                 }
1193
1194
1195   </programlisting>
1196   <para>
1197         This follows what is very much the standard way an ioctl handler looks
1198         in Linux. We copy the data into a kernel space variable and we check that the
1199         request is valid (in this case that the input is 0). Finally we copy the
1200         camera info back to the user.
1201   </para>
1202   <para>
1203         The VIDIOCGCHAN ioctl allows a user to ask about video channels (that is
1204         inputs to the video card). Our example card has a single camera input. The
1205         fields in the structure are
1206   </para>
1207    <table frame="all"><title>struct video_channel fields</title>
1208    <tgroup cols="2" align="left">
1209    <tbody>
1210    <row>
1211
1212    <entry>channel</entry><entry>The channel number we are selecting</entry>
1213    </row><row>
1214    <entry>name</entry><entry>The name for this channel. This is intended
1215                    to describe the port to the user.
1216                    Appropriate names are therefore things like
1217                    "Camera" "SCART input"</entry>
1218    </row><row>
1219    <entry>flags</entry><entry>Channel properties</entry>
1220    </row><row>
1221    <entry>type</entry><entry>Input type</entry>
1222    </row><row>
1223    <entry>norm</entry><entry>The current television encoding being used
1224                    if relevant for this channel.
1225     </entry>
1226     </row>
1227     </tbody>
1228     </tgroup>
1229     </table>
1230     <table frame="all"><title>struct video_channel flags</title>
1231     <tgroup cols="2" align="left">
1232     <tbody>
1233     <row>
1234         <entry>VIDEO_VC_TUNER</entry><entry>Channel has a tuner.</entry>
1235    </row><row>
1236         <entry>VIDEO_VC_AUDIO</entry><entry>Channel has audio.</entry>
1237     </row>
1238     </tbody>
1239     </tgroup>
1240     </table>
1241     <table frame="all"><title>struct video_channel types</title>
1242     <tgroup cols="2" align="left">
1243     <tbody>
1244     <row>
1245         <entry>VIDEO_TYPE_TV</entry><entry>Television input.</entry>
1246    </row><row>
1247         <entry>VIDEO_TYPE_CAMERA</entry><entry>Fixed camera input.</entry>
1248    </row><row>
1249         <entry>0</entry><entry>Type is unknown.</entry>
1250     </row>
1251     </tbody>
1252     </tgroup>
1253     </table>
1254     <table frame="all"><title>struct video_channel norms</title>
1255     <tgroup cols="2" align="left">
1256     <tbody>
1257     <row>
1258         <entry>VIDEO_MODE_PAL</entry><entry>PAL encoded Television</entry>
1259    </row><row>
1260         <entry>VIDEO_MODE_NTSC</entry><entry>NTSC (US) encoded Television</entry>
1261    </row><row>
1262         <entry>VIDEO_MODE_SECAM</entry><entry>SECAM (French) Television </entry>
1263    </row><row>
1264         <entry>VIDEO_MODE_AUTO</entry><entry>Automatic switching, or format does not
1265                                 matter</entry>
1266     </row>
1267     </tbody>
1268     </tgroup>
1269     </table>
1270     <para>
1271         The corresponding VIDIOCSCHAN ioctl allows a user to change channel and to
1272         request the norm is changed - for example to switch between a PAL or an NTSC
1273         format camera.
1274   </para>
1275   <programlisting>
1276
1277
1278                 case VIDIOCSCHAN:
1279                 {
1280                         struct video_channel v;
1281                         if(copy_from_user(&amp;v, arg, sizeof(v)))
1282                                 return -EFAULT;
1283                         if(v.channel != 0)
1284                                 return -EINVAL;
1285                         if(v.norm != VIDEO_MODE_AUTO)
1286                                 return -EINVAL;
1287                         return 0;
1288                 }
1289
1290
1291   </programlisting>
1292   <para>
1293         The implementation of this call in our driver is remarkably easy. Because we
1294         are assuming fixed format hardware we need only check that the user has not
1295         tried to change anything. 
1296   </para>
1297   <para>
1298         The user also needs to be able to configure and adjust the picture they are
1299         seeing. This is much like adjusting a television set. A user application
1300         also needs to know the palette being used so that it knows how to display
1301         the image that has been captured. The VIDIOCGPICT and VIDIOCSPICT ioctl
1302         calls provide this information.
1303   </para>
1304   <programlisting>
1305
1306
1307                 case VIDIOCGPICT
1308                 {
1309                         struct video_picture v;
1310                         v.brightness = hardware_brightness();
1311                         v.hue = hardware_hue();
1312                         v.colour = hardware_saturation();
1313                         v.contrast = hardware_brightness();
1314                         /* Not settable */
1315                         v.whiteness = 32768;
1316                         v.depth = 24;           /* 24bit */
1317                         v.palette = VIDEO_PALETTE_RGB24;
1318                         if(copy_to_user(&amp;v, arg, 
1319                              sizeof(v)))
1320                                 return -EFAULT;
1321                         return 0;
1322                 }
1323
1324
1325   </programlisting>
1326   <para>
1327         The brightness, hue, color, and contrast provide the picture controls that
1328         are akin to a conventional television. Whiteness provides additional
1329         control for greyscale images. All of these values are scaled between 0-65535
1330         and have 32768 as the mid point setting. The scaling means that applications
1331         do not have to worry about the capability range of the hardware but can let
1332         it make a best effort attempt.
1333   </para>
1334   <para>
1335         Our depth is 24, as this is in bits. We will be returning RGB24 format. This
1336         has one byte of red, then one of green, then one of blue. This then repeats
1337         for every other pixel in the image. The other common formats the interface 
1338         defines are
1339   </para>
1340    <table frame="all"><title>Framebuffer Encodings</title>
1341    <tgroup cols="2" align="left">
1342    <tbody>
1343    <row>
1344    <entry>GREY</entry><entry>Linear greyscale. This is for simple cameras and the
1345                         like</entry>
1346    </row><row>
1347    <entry>RGB565</entry><entry>The top 5 bits hold 32 red levels, the next six bits
1348                         hold green and the low 5 bits hold blue. </entry>
1349    </row><row>
1350    <entry>RGB555</entry><entry>The top bit is clear. The red green and blue levels
1351                         each occupy five bits.</entry>
1352     </row>
1353     </tbody>
1354     </tgroup>
1355     </table>
1356   <para>
1357         Additional modes are support for YUV capture formats. These are common for
1358         TV and video conferencing applications.
1359   </para>
1360   <para>
1361         The VIDIOCSPICT ioctl allows a user to set some of the picture parameters.
1362         Exactly which ones are supported depends heavily on the card itself. It is
1363         possible to support many modes and effects in software. In general doing
1364         this in the kernel is a bad idea. Video capture is a performance-sensitive
1365         application and the programs can often do better if they aren't being
1366         'helped' by an overkeen driver writer. Thus for our device we will report
1367         RGB24 only and refuse to allow a change.
1368   </para>
1369   <programlisting>
1370
1371
1372                 case VIDIOCSPICT:
1373                 {
1374                         struct video_picture v;
1375                         if(copy_from_user(&amp;v, arg, sizeof(v)))
1376                                 return -EFAULT;
1377                         if(v.depth!=24 || 
1378                            v.palette != VIDEO_PALETTE_RGB24)
1379                                 return -EINVAL;
1380                         set_hardware_brightness(v.brightness);
1381                         set_hardware_hue(v.hue);
1382                         set_hardware_saturation(v.colour);
1383                         set_hardware_brightness(v.contrast);
1384                         return 0;
1385                 }
1386
1387
1388   </programlisting>
1389   <para>
1390         We check the user has not tried to change the palette or the depth. We do
1391         not want to carry out some of the changes and then return an error. This may
1392         confuse the application which will be assuming no change occurred.
1393   </para>
1394   <para>
1395         In much the same way as you need to be able to set the picture controls to
1396         get the right capture images, many cards need to know what they are
1397         displaying onto when generating overlay output. In some cases getting this
1398         wrong even makes a nasty mess or may crash the computer. For that reason
1399         the VIDIOCSBUF ioctl used to set up the frame buffer information may well
1400         only be usable by root.
1401   </para>
1402   <para>
1403         We will assume our card is one of the old ISA devices with feature connector
1404         and only supports a couple of standard video modes. Very common for older
1405         cards although the PCI devices are way smarter than this.
1406   </para>
1407   <programlisting>
1408
1409
1410 static struct video_buffer capture_fb;
1411
1412                 case VIDIOCGFBUF:
1413                 {
1414                         if(copy_to_user(arg, &amp;capture_fb, 
1415                              sizeof(capture_fb)))
1416                                 return -EFAULT;
1417                         return 0;
1418                         
1419                 }
1420
1421
1422   </programlisting>
1423   <para>
1424         We keep the frame buffer information in the format the ioctl uses. This
1425         makes it nice and easy to work with in the ioctl calls.
1426   </para>
1427   <programlisting>
1428
1429                 case VIDIOCSFBUF:
1430                 {
1431                         struct video_buffer v;
1432
1433                         if(!capable(CAP_SYS_ADMIN))
1434                                 return -EPERM;
1435
1436                         if(copy_from_user(&amp;v, arg, sizeof(v)))
1437                                 return -EFAULT;
1438                         if(v.width!=320 &amp;&amp; v.width!=640)
1439                                 return -EINVAL;
1440                         if(v.height!=200 &amp;&amp; v.height!=240 
1441                                 &amp;&amp; v.height!=400
1442                                 &amp;&amp; v.height !=480)
1443                                 return -EINVAL;
1444                         memcpy(&amp;capture_fb, &amp;v, sizeof(v));
1445                         hardware_set_fb(&amp;v);
1446                         return 0;
1447                 }
1448
1449
1450
1451   </programlisting>
1452   <para>
1453         The capable() function checks a user has the required capability. The Linux
1454         operating system has a set of about 30 capabilities indicating privileged
1455         access to services. The default set up gives the superuser (uid 0) all of
1456         them and nobody else has any.
1457   </para>
1458   <para>
1459         We check that the user has the SYS_ADMIN capability, that is they are
1460         allowed to operate as the machine administrator. We don't want anyone but
1461         the administrator making a mess of the display.
1462   </para>
1463   <para>
1464         Next we check for standard PC video modes (320 or 640 wide with either
1465         EGA or VGA depths). If the mode is not a standard video mode we reject it as
1466         not supported by our card. If the mode is acceptable we save it so that
1467         VIDIOCFBUF will give the right answer next time it is called.  The
1468         hardware_set_fb() function is some undescribed card specific function to
1469         program the card for the desired mode.
1470   </para>
1471   <para>
1472         Before the driver can display an overlay window it needs to know where the
1473         window should be placed, and also how large it should be. If the card
1474         supports clipping it needs to know which rectangles to omit from the
1475         display. The video_window structure is used to describe the way the image 
1476         should be displayed. 
1477    </para>
1478    <table frame="all"><title>struct video_window fields</title>
1479    <tgroup cols="2" align="left">
1480    <tbody>
1481    <row>
1482         <entry>width</entry><entry>The width in pixels of the desired image. The card
1483                         may use a smaller size if this size is not available</entry>
1484         </row><row>
1485         <entry>height</entry><entry>The height of the image. The card may use a smaller
1486                         size if this size is not available.</entry>
1487         </row><row>
1488         <entry>x</entry><entry>   The X position of the top left of the window. This
1489                         is in pixels relative to the left hand edge of the
1490                         picture. Not all cards can display images aligned on
1491                         any pixel boundary. If the position is unsuitable
1492                         the card adjusts the image right and reduces the
1493                         width.</entry>
1494         </row><row>
1495         <entry>y</entry><entry>   The Y position of the top left of the window. This
1496                         is counted in pixels relative to the top edge of the
1497                         picture. As with the width if the card cannot
1498                         display  starting on this line it will adjust the
1499                         values.</entry>
1500         </row><row>
1501         <entry>chromakey</entry><entry>The colour (expressed in RGB32 format) for the
1502                         chromakey colour if chroma keying is being used. </entry>
1503         </row><row>
1504         <entry>clips</entry><entry>An array of rectangles that must not be drawn
1505                         over.</entry>
1506         </row><row>
1507         <entry>clipcount</entry><entry>The number of clips in this array.</entry>
1508     </row>
1509     </tbody>
1510     </tgroup>
1511     </table>
1512     <para>
1513         Each clip is a struct video_clip which has the following fields
1514    </para>
1515    <table frame="all"><title>video_clip fields</title>
1516    <tgroup cols="2" align="left">
1517    <tbody>
1518    <row>
1519         <entry>x, y</entry><entry>Co-ordinates relative to the display</entry>
1520         </row><row>
1521         <entry>width, height</entry><entry>Width and height in pixels</entry>
1522         </row><row>
1523         <entry>next</entry><entry>A spare field for the application to use</entry>
1524     </row>
1525     </tbody>
1526     </tgroup>
1527     </table>
1528     <para>
1529         The driver is required to ensure it always draws in the area requested or a        smaller area, and that it never draws in any of the areas that are clipped.
1530         This may well mean it has to leave alone. small areas the application wished to be
1531         drawn.
1532   </para>
1533   <para>
1534         Our example card uses chromakey so does not have to address most of the
1535         clipping.  We will add a video_window structure to our global variables to
1536         remember our parameters, as we did with the frame buffer.
1537   </para>
1538   <programlisting>
1539
1540
1541                 case VIDIOCGWIN:
1542                 {
1543                         if(copy_to_user(arg, &amp;capture_win, 
1544                             sizeof(capture_win)))
1545                                 return -EFAULT;
1546                         return 0;
1547                 }
1548
1549
1550                 case VIDIOCSWIN:
1551                 {
1552                         struct video_window v;
1553                         if(copy_from_user(&amp;v, arg, sizeof(v)))
1554                                 return -EFAULT;
1555                         if(v.width &gt; 640 || v.height &gt; 480)
1556                                 return -EINVAL;
1557                         if(v.width &lt; 16 || v.height &lt; 16)
1558                                 return -EINVAL;
1559                         hardware_set_key(v.chromakey);
1560                         hardware_set_window(v);
1561                         memcpy(&amp;capture_win, &amp;v, sizeof(v));
1562                         capture_w = v.width;
1563                         capture_h = v.height;
1564                         return 0;
1565                 }
1566
1567
1568   </programlisting>
1569   <para>
1570         Because we are using Chromakey our setup is fairly simple. Mostly we have to
1571         check the values are sane and load them into the capture card.
1572   </para>
1573   <para>
1574         With all the setup done we can now turn on the actual capture/overlay. This
1575         is done with the VIDIOCCAPTURE ioctl. This takes a single integer argument
1576         where 0 is on and 1 is off.
1577   </para>
1578   <programlisting>
1579
1580
1581                 case VIDIOCCAPTURE:
1582                 {
1583                         int v;
1584                         if(get_user(v, (int *)arg))
1585                                 return -EFAULT;
1586                         if(v==0)
1587                                 hardware_capture_off();
1588                         else
1589                         {
1590                                 if(capture_fb.width == 0 
1591                                     || capture_w == 0)
1592                                         return -EINVAL;
1593                                 hardware_capture_on();
1594                         }
1595                         return 0;
1596                 }
1597
1598
1599   </programlisting>
1600   <para>
1601         We grab the flag from user space and either enable or disable according to
1602         its value. There is one small corner case we have to consider here. Suppose
1603         that the capture was requested before the video window or the frame buffer
1604         had been set up. In those cases there will be unconfigured fields in our
1605         card data, as well as unconfigured hardware settings. We check for this case and
1606         return an error if the frame buffer or the capture window width is zero.
1607   </para>
1608   <programlisting>
1609
1610
1611                 default:
1612                         return -ENOIOCTLCMD;
1613         }
1614 }
1615   </programlisting>
1616   <para>
1617
1618         We don't need to support any other ioctls, so if we get this far, it is time
1619         to tell the video layer that we don't now what the user is talking about.
1620   </para>
1621   </sect1>
1622   <sect1 id="endvid">
1623   <title>Other Functionality</title>
1624   <para>
1625         The Video4Linux layer supports additional features, including a high
1626         performance mmap() based capture mode and capturing part of the image. 
1627         These features are out of the scope of the book.  You should however have enough 
1628         example code to implement most simple video4linux devices for radio and TV
1629         cards.
1630   </para>
1631   </sect1>
1632   </chapter>
1633   <chapter id="bugs">
1634      <title>Known Bugs And Assumptions</title>
1635   <para>
1636   <variablelist>
1637     <varlistentry><term>Multiple Opens</term>
1638     <listitem>
1639     <para>
1640         The driver assumes multiple opens should not be allowed. A driver
1641         can work around this but not cleanly.
1642     </para>
1643     </listitem></varlistentry>
1644
1645     <varlistentry><term>API Deficiencies</term>
1646     <listitem>
1647     <para>
1648         The existing API poorly reflects compression capable devices. There
1649         are plans afoot to merge V4L, V4L2 and some other ideas into a
1650         better interface.
1651     </para>
1652     </listitem></varlistentry>
1653   </variablelist>
1654
1655   </para>
1656   </chapter>
1657
1658   <chapter id="pubfunctions">
1659      <title>Public Functions Provided</title>
1660 !Edrivers/media/video/videodev.c
1661   </chapter>
1662
1663 </book>