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