Commit | Line | Data |
---|---|---|
1da177e4 LT |
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(&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 | ||
32357988 | 232 | static int radio_open(struct video_device *dev, int flags) |
1da177e4 LT |
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, &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(&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(&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(&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, &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, &freq, | |
524 | sizeof(unsigned long))!=0) | |
525 | return -EFAULT; | |
526 | if(hardware_set_freq(freq)<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(&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. &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(&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(&v, arg, sizeof(v))) | |
684 | return -EFAULT; | |
685 | if(v.audio) | |
686 | return -EINVAL; | |
687 | current_volume = v/16384; | |
688 | if(v.flags&VIDEO_AUDIO_MUTE) | |
689 | hardware_set_volume(0); | |
690 | else | |
691 | hardware_set_volume(current_volume); | |
692 | current_muted = v.flags & | |
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(&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(&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 | ||
32357988 | 952 | static int camera_open(struct video_device *dev, int flags) |
1da177e4 LT |
953 | { |
954 | if(users) | |
955 | return -EBUSY; | |
956 | if(request_irq(irq, camera_irq, 0, "camera", dev)<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 | |
6ce6c7fa | 979 | able to share the interrupt and would have set IRQF_SHARED to indicate a |
1da177e4 LT |
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(&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, &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(&capture_wait, &wait); | |
1046 | ||
1047 | while(!capture_ready) | |
1048 | { | |
1049 | if(file->flags&O_NDELAY) | |
1050 | { | |
1051 | remove_wait_queue(&capture_wait, &wait); | |
1052 | current->state = TASK_RUNNING; | |
1053 | return -EWOULDBLOCK; | |
1054 | } | |
1055 | if(signal_pending(current)) | |
1056 | { | |
1057 | remove_wait_queue(&capture_wait, &wait); | |
1058 | current->state = TASK_RUNNING; | |
1059 | return -ERESTARTSYS; | |
1060 | } | |
1061 | schedule(); | |
1062 | current->state = TASK_INTERRUPTIBLE; | |
1063 | } | |
1064 | remove_wait_queue(&capture_wait, &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<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, &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(&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(&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(&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(&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(&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, &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(&v, arg, sizeof(v))) | |
1437 | return -EFAULT; | |
1438 | if(v.width!=320 && v.width!=640) | |
1439 | return -EINVAL; | |
1440 | if(v.height!=200 && v.height!=240 | |
1441 | && v.height!=400 | |
1442 | && v.height !=480) | |
1443 | return -EINVAL; | |
1444 | memcpy(&capture_fb, &v, sizeof(v)); | |
1445 | hardware_set_fb(&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, &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(&v, arg, sizeof(v))) | |
1554 | return -EFAULT; | |
1555 | if(v.width > 640 || v.height > 480) | |
1556 | return -EINVAL; | |
1557 | if(v.width < 16 || v.height < 16) | |
1558 | return -EINVAL; | |
1559 | hardware_set_key(v.chromakey); | |
1560 | hardware_set_window(v); | |
1561 | memcpy(&capture_win, &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> |