aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Documentation/00-INDEX3
-rw-r--r--Documentation/DocBook/Makefile2
-rw-r--r--Documentation/DocBook/videobook.tmpl1654
-rw-r--r--Documentation/SubmittingPatches2
-rw-r--r--Documentation/block/data-integrity.txt4
-rw-r--r--Documentation/development-process/1.Intro274
-rw-r--r--Documentation/development-process/2.Process459
-rw-r--r--Documentation/development-process/3.Early-stage195
-rw-r--r--Documentation/development-process/4.Coding384
-rw-r--r--Documentation/development-process/5.Posting278
-rw-r--r--Documentation/development-process/6.Followthrough202
-rw-r--r--Documentation/development-process/7.AdvancedTopics173
-rw-r--r--Documentation/development-process/8.Conclusion74
13 files changed, 2046 insertions, 1658 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 438277800103..7286ad090db7 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -21,6 +21,9 @@ Changes
21 - list of changes that break older software packages. 21 - list of changes that break older software packages.
22CodingStyle 22CodingStyle
23 - how the boss likes the C code in the kernel to look. 23 - how the boss likes the C code in the kernel to look.
24development-process/
25 - An extended tutorial on how to work with the kernel development
26 process.
24DMA-API.txt 27DMA-API.txt
25 - DMA API, pci_ API & extensions for non-consistent memory machines. 28 - DMA API, pci_ API & extensions for non-consistent memory machines.
26DMA-ISA-LPC.txt 29DMA-ISA-LPC.txt
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 1615350b7b53..fabc06466b93 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,7 +6,7 @@
6# To add a new book the only step required is to add the book to the 6# To add a new book the only step required is to add the book to the
7# list of DOCBOOKS. 7# list of DOCBOOKS.
8 8
9DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ 9DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml \
10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ 10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11 procfs-guide.xml writing_usb_driver.xml networking.xml \ 11 procfs-guide.xml writing_usb_driver.xml networking.xml \
12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ 12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
diff --git a/Documentation/DocBook/videobook.tmpl b/Documentation/DocBook/videobook.tmpl
deleted file mode 100644
index 0bc25949b668..000000000000
--- a/Documentation/DocBook/videobook.tmpl
+++ /dev/null
@@ -1,1654 +0,0 @@
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
95static struct video_device my_radio
96{
97 "My radio",
98 VID_TYPE_TUNER,
99 radio_open.
100 radio_close,
101 NULL, /* no read */
102 NULL, /* no write */
103 NULL, /* no poll */
104 radio_ioctl,
105 NULL, /* no special init function */
106 NULL /* no private data */
107};
108
109
110 </programlisting>
111 <para>
112 This declares our video4linux device driver interface. The VID_TYPE_ value
113 defines what kind of an interface we are, and defines basic capabilities.
114 </para>
115 <para>
116 The only defined value relevant for a radio card is VID_TYPE_TUNER which
117 indicates that the device can be tuned. Clearly our radio is going to have some
118 way to change channel so it is tuneable.
119 </para>
120 <para>
121 We declare an open and close routine, but we do not need read or write,
122 which are used to read and write video data to or from the card itself. As
123 we have no read or write there is no poll function.
124 </para>
125 <para>
126 The private initialise function is run when the device is registered. In
127 this driver we've already done all the work needed. The final pointer is a
128 private data pointer that can be used by the device driver to attach and
129 retrieve private data structures. We set this field "priv" to NULL for
130 the moment.
131 </para>
132 <para>
133 Having the structure defined is all very well but we now need to register it
134 with the kernel.
135 </para>
136 <programlisting>
137
138
139static int io = 0x320;
140
141int __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(&amp;my_radio, VFL_TYPE_RADIO)==-1) {
151 release_region(io, MY_IO_SIZE);
152 return -EINVAL;
153 }
154 return 0;
155}
156
157 </programlisting>
158 <para>
159 The first stage of the initialisation, as is normally the case, is to check
160 that the I/O space we are about to fiddle with doesn't belong to some other
161 driver. If it is we leave well alone. If the user gives the address of the
162 wrong device then we will spot this. These policies will generally avoid
163 crashing the machine.
164 </para>
165 <para>
166 Now we ask the Video4Linux layer to register the device for us. We hand it
167 our carefully designed video_device structure and also tell it which group
168 of devices we want it registered with. In this case VFL_TYPE_RADIO.
169 </para>
170 <para>
171 The types available are
172 </para>
173 <table frame="all" id="Device_Types"><title>Device Types</title>
174 <tgroup cols="3" align="left">
175 <tbody>
176 <row>
177 <entry>VFL_TYPE_RADIO</entry><entry>/dev/radio{n}</entry><entry>
178
179 Radio devices are assigned in this block. As with all of these
180 selections the actual number assignment is done by the video layer
181 accordijng to what is free.</entry>
182 </row><row>
183 <entry>VFL_TYPE_GRABBER</entry><entry>/dev/video{n}</entry><entry>
184 Video capture devices and also -- counter-intuitively for the name --
185 hardware video playback devices such as MPEG2 cards.</entry>
186 </row><row>
187 <entry>VFL_TYPE_VBI</entry><entry>/dev/vbi{n}</entry><entry>
188 The VBI devices capture the hidden lines on a television picture
189 that carry further information like closed caption data, teletext
190 (primarily in Europe) and now Intercast and the ATVEC internet
191 television encodings.</entry>
192 </row><row>
193 <entry>VFL_TYPE_VTX</entry><entry>/dev/vtx[n}</entry><entry>
194 VTX is 'Videotext' also known as 'Teletext'. This is a system for
195 sending numbered, 40x25, mostly textual page images over the hidden
196 lines. Unlike the /dev/vbi interfaces, this is for 'smart' decoder
197 chips. (The use of the word smart here has to be taken in context,
198 the smartest teletext chips are fairly dumb pieces of technology).
199 </entry>
200 </row>
201 </tbody>
202 </tgroup>
203 </table>
204 <para>
205 We are most definitely a radio.
206 </para>
207 <para>
208 Finally we allocate our I/O space so that nobody treads on us and return 0
209 to signify general happiness with the state of the universe.
210 </para>
211 </sect1>
212 <sect1 id="openradio">
213 <title>Opening And Closing The Radio</title>
214
215 <para>
216 The functions we declared in our video_device are mostly very simple.
217 Firstly we can drop in what is basically standard code for open and close.
218 </para>
219 <programlisting>
220
221
222static int users = 0;
223
224static int radio_open(struct video_device *dev, int flags)
225{
226 if(users)
227 return -EBUSY;
228 users++;
229 return 0;
230}
231
232 </programlisting>
233 <para>
234 At open time we need to do nothing but check if someone else is also using
235 the radio card. If nobody is using it we make a note that we are using it,
236 then we ensure that nobody unloads our driver on us.
237 </para>
238 <programlisting>
239
240
241static 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
268static 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, &amp;v, sizeof(v)))
284 return -EFAULT;
285 return 0;
286 }
287
288 </programlisting>
289 <para>
290 VIDIOCGCAP is the first ioctl all video4linux devices must support. It
291 allows the applications to find out what sort of a card they have found and
292 to figure out what they want to do about it. The fields in the structure are
293 </para>
294 <table frame="all" id="video_capability_fields"><title>struct video_capability fields</title>
295 <tgroup cols="2" align="left">
296 <tbody>
297 <row>
298 <entry>name</entry><entry>The device text name. This is intended for the user.</entry>
299 </row><row>
300 <entry>channels</entry><entry>The number of different channels you can tune on
301 this card. It could even by zero for a card that has
302 no tuning capability. For our simple FM radio it is 1.
303 An AM/FM radio would report 2.</entry>
304 </row><row>
305 <entry>audios</entry><entry>The number of audio inputs on this device. For our
306 radio there is only one audio input.</entry>
307 </row><row>
308 <entry>minwidth,minheight</entry><entry>The smallest size the card is capable of capturing
309 images in. We set these to zero. Radios do not
310 capture pictures</entry>
311 </row><row>
312 <entry>maxwidth,maxheight</entry><entry>The largest image size the card is capable of
313 capturing. For our radio we report 0.
314 </entry>
315 </row><row>
316 <entry>type</entry><entry>This reports the capabilities of the device, and
317 matches the field we filled in in the struct
318 video_device when registering.</entry>
319 </row>
320 </tbody>
321 </tgroup>
322 </table>
323 <para>
324 Having filled in the fields, we use copy_to_user to copy the structure into
325 the users buffer. If the copy fails we return an EFAULT to the application
326 so that it knows it tried to feed us garbage.
327 </para>
328 <para>
329 The next pair of ioctl operations select which tuner is to be used and let
330 the application find the tuner properties. We have only a single FM band
331 tuner in our example device.
332 </para>
333 <programlisting>
334
335
336 case VIDIOCGTUNER:
337 {
338 struct video_tuner v;
339 if(copy_from_user(&amp;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(&amp;v, arg, sizeof(v))!=0)
350 return -EFAULT;
351 return 0;
352 }
353
354 </programlisting>
355 <para>
356 The VIDIOCGTUNER ioctl allows applications to query a tuner. The application
357 sets the tuner field to the tuner number it wishes to query. The query does
358 not change the tuner that is being used, it merely enquires about the tuner
359 in question.
360 </para>
361 <para>
362 We have exactly one tuner so after copying the user buffer to our temporary
363 structure we complain if they asked for a tuner other than tuner 0.
364 </para>
365 <para>
366 The video_tuner structure has the following fields
367 </para>
368 <table frame="all" id="video_tuner_fields"><title>struct video_tuner fields</title>
369 <tgroup cols="2" align="left">
370 <tbody>
371 <row>
372 <entry>int tuner</entry><entry>The number of the tuner in question</entry>
373 </row><row>
374 <entry>char name[32]</entry><entry>A text description of this tuner. "FM" will do fine.
375 This is intended for the application.</entry>
376 </row><row>
377 <entry>u32 flags</entry>
378 <entry>Tuner capability flags</entry>
379 </row>
380 <row>
381 <entry>u16 mode</entry><entry>The current reception mode</entry>
382
383 </row><row>
384 <entry>u16 signal</entry><entry>The signal strength scaled between 0 and 65535. If
385 a device cannot tell the signal strength it should
386 report 65535. Many simple cards contain only a
387 signal/no signal bit. Such cards will report either
388 0 or 65535.</entry>
389
390 </row><row>
391 <entry>u32 rangelow, rangehigh</entry><entry>
392 The range of frequencies supported by the radio
393 or TV. It is scaled according to the VIDEO_TUNER_LOW
394 flag.</entry>
395
396 </row>
397 </tbody>
398 </tgroup>
399 </table>
400
401 <table frame="all" id="video_tuner_flags"><title>struct video_tuner flags</title>
402 <tgroup cols="2" align="left">
403 <tbody>
404 <row>
405 <entry>VIDEO_TUNER_PAL</entry><entry>A PAL TV tuner</entry>
406 </row><row>
407 <entry>VIDEO_TUNER_NTSC</entry><entry>An NTSC (US) TV tuner</entry>
408 </row><row>
409 <entry>VIDEO_TUNER_SECAM</entry><entry>A SECAM (French) TV tuner</entry>
410 </row><row>
411 <entry>VIDEO_TUNER_LOW</entry><entry>
412 The tuner frequency is scaled in 1/16th of a KHz
413 steps. If not it is in 1/16th of a MHz steps
414 </entry>
415 </row><row>
416 <entry>VIDEO_TUNER_NORM</entry><entry>The tuner can set its format</entry>
417 </row><row>
418 <entry>VIDEO_TUNER_STEREO_ON</entry><entry>The tuner is currently receiving a stereo signal</entry>
419 </row>
420 </tbody>
421 </tgroup>
422 </table>
423
424 <table frame="all" id="video_tuner_modes"><title>struct video_tuner modes</title>
425 <tgroup cols="2" align="left">
426 <tbody>
427 <row>
428 <entry>VIDEO_MODE_PAL</entry><entry>PAL Format</entry>
429 </row><row>
430 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC Format (USA)</entry>
431 </row><row>
432 <entry>VIDEO_MODE_SECAM</entry><entry>French Format</entry>
433 </row><row>
434 <entry>VIDEO_MODE_AUTO</entry><entry>A device that does not need to do
435 TV format switching</entry>
436 </row>
437 </tbody>
438 </tgroup>
439 </table>
440 <para>
441 The settings for the radio card are thus fairly simple. We report that we
442 are a tuner called "FM" for FM radio. In order to get the best tuning
443 resolution we report VIDEO_TUNER_LOW and select tuning to 1/16th of KHz. Its
444 unlikely our card can do that resolution but it is a fair bet the card can
445 do better than 1/16th of a MHz. VIDEO_TUNER_LOW is appropriate to almost all
446 radio usage.
447 </para>
448 <para>
449 We report that the tuner automatically handles deciding what format it is
450 receiving - true enough as it only handles FM radio. Our example card is
451 also incapable of detecting stereo or signal strengths so it reports a
452 strength of 0xFFFF (maximum) and no stereo detected.
453 </para>
454 <para>
455 To finish off we set the range that can be tuned to be 87-108Mhz, the normal
456 FM broadcast radio range. It is important to find out what the card is
457 actually capable of tuning. It is easy enough to simply use the FM broadcast
458 range. Unfortunately if you do this you will discover the FM broadcast
459 ranges in the USA, Europe and Japan are all subtly different and some users
460 cannot receive all the stations they wish.
461 </para>
462 <para>
463 The application also needs to be able to set the tuner it wishes to use. In
464 our case, with a single tuner this is rather simple to arrange.
465 </para>
466 <programlisting>
467
468 case VIDIOCSTUNER:
469 {
470 struct video_tuner v;
471 if(copy_from_user(&amp;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
493static unsigned long current_freq;
494
495
496
497 case VIDIOCGFREQ:
498 if(copy_to_user(arg, &amp;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, &amp;freq,
516 sizeof(unsigned long))!=0)
517 return -EFAULT;
518 if(hardware_set_freq(freq)&lt;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
544static int current_volume=0;
545
546 case VIDIOCGAUDIO:
547 {
548 struct video_audio v;
549 if(copy_from_user(&amp;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. &amp;v, sizeof(v)))
562 return -EFAULT;
563 return 0;
564 }
565
566 </programlisting>
567 <para>
568 Much like the tuner we start by copying the user structure into kernel
569 space. Again we check if the user has asked for a valid audio input. We have
570 only input 0 and we punt if they ask for another input.
571 </para>
572 <para>
573 Then we fill in the video_audio structure. This has the following format
574 </para>
575 <table frame="all" id="video_audio_fields"><title>struct video_audio fields</title>
576 <tgroup cols="2" align="left">
577 <tbody>
578 <row>
579 <entry>audio</entry><entry>The input the user wishes to query</entry>
580 </row><row>
581 <entry>volume</entry><entry>The volume setting on a scale of 0-65535</entry>
582 </row><row>
583 <entry>base</entry><entry>The base level on a scale of 0-65535</entry>
584 </row><row>
585 <entry>treble</entry><entry>The treble level on a scale of 0-65535</entry>
586 </row><row>
587 <entry>flags</entry><entry>The features this audio device supports
588 </entry>
589 </row><row>
590 <entry>name</entry><entry>A text name to display to the user. We picked
591 "Radio" as it explains things quite nicely.</entry>
592 </row><row>
593 <entry>mode</entry><entry>The current reception mode for the audio
594
595 We report MONO because our card is too stupid to know if it is in
596 mono or stereo.
597 </entry>
598 </row><row>
599 <entry>balance</entry><entry>The stereo balance on a scale of 0-65535, 32768 is
600 middle.</entry>
601 </row><row>
602 <entry>step</entry><entry>The step by which the volume control jumps. This is
603 used to help make it easy for applications to set
604 slider behaviour.</entry>
605 </row>
606 </tbody>
607 </tgroup>
608 </table>
609
610 <table frame="all" id="video_audio_flags"><title>struct video_audio flags</title>
611 <tgroup cols="2" align="left">
612 <tbody>
613 <row>
614 <entry>VIDEO_AUDIO_MUTE</entry><entry>The audio is currently muted. We
615 could fake this in our driver but we
616 choose not to bother.</entry>
617 </row><row>
618 <entry>VIDEO_AUDIO_MUTABLE</entry><entry>The input has a mute option</entry>
619 </row><row>
620 <entry>VIDEO_AUDIO_TREBLE</entry><entry>The input has a treble control</entry>
621 </row><row>
622 <entry>VIDEO_AUDIO_BASS</entry><entry>The input has a base control</entry>
623 </row>
624 </tbody>
625 </tgroup>
626 </table>
627
628 <table frame="all" id="video_audio_modes"><title>struct video_audio modes</title>
629 <tgroup cols="2" align="left">
630 <tbody>
631 <row>
632 <entry>VIDEO_SOUND_MONO</entry><entry>Mono sound</entry>
633 </row><row>
634 <entry>VIDEO_SOUND_STEREO</entry><entry>Stereo sound</entry>
635 </row><row>
636 <entry>VIDEO_SOUND_LANG1</entry><entry>Alternative language 1 (TV specific)</entry>
637 </row><row>
638 <entry>VIDEO_SOUND_LANG2</entry><entry>Alternative language 2 (TV specific)</entry>
639 </row>
640 </tbody>
641 </tgroup>
642 </table>
643 <para>
644 Having filled in the structure we copy it back to user space.
645 </para>
646 <para>
647 The VIDIOCSAUDIO ioctl allows the user to set the audio parameters in the
648 video_audio structure. The driver does its best to honour the request.
649 </para>
650 <programlisting>
651
652 case VIDIOCSAUDIO:
653 {
654 struct video_audio v;
655 if(copy_from_user(&amp;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(&amp;v, arg, sizeof(v)))
676 return -EFAULT;
677 if(v.audio)
678 return -EINVAL;
679 current_volume = v/16384;
680 if(v.flags&amp;VIDEO_AUDIO_MUTE)
681 hardware_set_volume(0);
682 else
683 hardware_set_volume(current_volume);
684 current_muted = v.flags &amp;
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
722static int io = 0x300;
723
724#else
725
726static int io = -1;
727
728#endif
729
730MODULE_AUTHOR("Alan Cox");
731MODULE_DESCRIPTION("A driver for an imaginary radio card.");
732module_param(io, int, 0444);
733MODULE_PARM_DESC(io, "I/O address of the card.");
734
735static 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
746static void __exit cleanup(void)
747{
748 video_unregister_device(&amp;my_radio);
749 release_region(io, MY_IO_SIZE);
750}
751
752module_init(init);
753module_exit(cleanup);
754
755 </programlisting>
756 <para>
757 In this example we set the IO base by default if the driver is compiled into
758 the kernel: you can still set it using "my_radio.irq" if this file is called <filename>my_radio.c</filename>. For the module we require the
759 user sets the parameter. We set io to a nonsense port (-1) so that we can
760 tell if the user supplied an io parameter or not.
761 </para>
762 <para>
763 We use MODULE_ defines to give an author for the card driver and a
764 description. We also use them to declare that io is an integer and it is the
765 address of the card, and can be read by anyone from sysfs.
766 </para>
767 <para>
768 The clean-up routine unregisters the video_device we registered, and frees
769 up the I/O space. Note that the unregister takes the actual video_device
770 structure as its argument. Unlike the file operations structure which can be
771 shared by all instances of a device a video_device structure as an actual
772 instance of the device. If you are registering multiple radio devices you
773 need to fill in one structure per device (most likely by setting up a
774 template and copying it to each of the actual device structures).
775 </para>
776 </sect1>
777 </chapter>
778 <chapter id="Video_Capture_Devices">
779 <title>Video Capture Devices</title>
780 <sect1 id="introvid">
781 <title>Video Capture Device Types</title>
782 <para>
783 The video capture devices share the same interfaces as radio devices. In
784 order to explain the video capture interface I will use the example of a
785 camera that has no tuners or audio input. This keeps the example relatively
786 clean. To get both combine the two driver examples.
787 </para>
788 <para>
789 Video capture devices divide into four categories. A little technology
790 backgrounder. Full motion video even at television resolution (which is
791 actually fairly low) is pretty resource-intensive. You are continually
792 passing megabytes of data every second from the capture card to the display.
793 several alternative approaches have emerged because copying this through the
794 processor and the user program is a particularly bad idea .
795 </para>
796 <para>
797 The first is to add the television image onto the video output directly.
798 This is also how some 3D cards work. These basic cards can generally drop the
799 video into any chosen rectangle of the display. Cards like this, which
800 include most mpeg1 cards that used the feature connector, aren't very
801 friendly in a windowing environment. They don't understand windows or
802 clipping. The video window is always on the top of the display.
803 </para>
804 <para>
805 Chroma keying is a technique used by cards to get around this. It is an old
806 television mixing trick where you mark all the areas you wish to replace
807 with a single clear colour that isn't used in the image - TV people use an
808 incredibly bright blue while computing people often use a particularly
809 virulent purple. Bright blue occurs on the desktop. Anyone with virulent
810 purple windows has another problem besides their TV overlay.
811 </para>
812 <para>
813 The third approach is to copy the data from the capture card to the video
814 card, but to do it directly across the PCI bus. This relieves the processor
815 from doing the work but does require some smartness on the part of the video
816 capture chip, as well as a suitable video card. Programming this kind of
817 card and more so debugging it can be extremely tricky. There are some quite
818 complicated interactions with the display and you may also have to cope with
819 various chipset bugs that show up when PCI cards start talking to each
820 other.
821 </para>
822 <para>
823 To keep our example fairly simple we will assume a card that supports
824 overlaying a flat rectangular image onto the frame buffer output, and which
825 can also capture stuff into processor memory.
826 </para>
827 </sect1>
828 <sect1 id="regvid">
829 <title>Registering Video Capture Devices</title>
830 <para>
831 This time we need to add more functions for our camera device.
832 </para>
833 <programlisting>
834static struct video_device my_camera
835{
836 "My Camera",
837 VID_TYPE_OVERLAY|VID_TYPE_SCALES|\
838 VID_TYPE_CAPTURE|VID_TYPE_CHROMAKEY,
839 camera_open.
840 camera_close,
841 camera_read, /* no read */
842 NULL, /* no write */
843 camera_poll, /* no poll */
844 camera_ioctl,
845 NULL, /* no special init function */
846 NULL /* no private data */
847};
848 </programlisting>
849 <para>
850 We need a read() function which is used for capturing data from
851 the card, and we need a poll function so that a driver can wait for the next
852 frame to be captured.
853 </para>
854 <para>
855 We use the extra video capability flags that did not apply to the
856 radio interface. The video related flags are
857 </para>
858 <table frame="all" id="Capture_Capabilities"><title>Capture Capabilities</title>
859 <tgroup cols="2" align="left">
860 <tbody>
861 <row>
862<entry>VID_TYPE_CAPTURE</entry><entry>We support image capture</entry>
863</row><row>
864<entry>VID_TYPE_TELETEXT</entry><entry>A teletext capture device (vbi{n])</entry>
865</row><row>
866<entry>VID_TYPE_OVERLAY</entry><entry>The image can be directly overlaid onto the
867 frame buffer</entry>
868</row><row>
869<entry>VID_TYPE_CHROMAKEY</entry><entry>Chromakey can be used to select which parts
870 of the image to display</entry>
871</row><row>
872<entry>VID_TYPE_CLIPPING</entry><entry>It is possible to give the board a list of
873 rectangles to draw around. </entry>
874</row><row>
875<entry>VID_TYPE_FRAMERAM</entry><entry>The video capture goes into the video memory
876 and actually changes it. Applications need
877 to know this so they can clean up after the
878 card</entry>
879</row><row>
880<entry>VID_TYPE_SCALES</entry><entry>The image can be scaled to various sizes,
881 rather than being a single fixed size.</entry>
882</row><row>
883<entry>VID_TYPE_MONOCHROME</entry><entry>The capture will be monochrome. This isn't a
884 complete answer to the question since a mono
885 camera on a colour capture card will still
886 produce mono output.</entry>
887</row><row>
888<entry>VID_TYPE_SUBCAPTURE</entry><entry>The card allows only part of its field of
889 view to be captured. This enables
890 applications to avoid copying all of a large
891 image into memory when only some section is
892 relevant.</entry>
893 </row>
894 </tbody>
895 </tgroup>
896 </table>
897 <para>
898 We set VID_TYPE_CAPTURE so that we are seen as a capture card,
899 VID_TYPE_CHROMAKEY so the application knows it is time to draw in virulent
900 purple, and VID_TYPE_SCALES because we can be resized.
901 </para>
902 <para>
903 Our setup is fairly similar. This time we also want an interrupt line
904 for the 'frame captured' signal. Not all cards have this so some of them
905 cannot handle poll().
906 </para>
907 <programlisting>
908
909
910static int io = 0x320;
911static int irq = 11;
912
913int __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(&amp;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
941static int users = 0;
942
943static int camera_open(struct video_device *dev, int flags)
944{
945 if(users)
946 return -EBUSY;
947 if(request_irq(irq, camera_irq, 0, "camera", dev)&lt;0)
948 return -EBUSY;
949 users++;
950 return 0;
951}
952
953
954static int camera_close(struct video_device *dev)
955{
956 users--;
957 free_irq(irq, dev);
958}
959 </programlisting>
960 <para>
961 The open and close routines are also quite similar. The only real change is
962 that we now request an interrupt for the camera device interrupt line. If we
963 cannot get the interrupt we report EBUSY to the application and give up.
964 </para>
965 </sect1>
966 <sect1 id="irqvid">
967 <title>Interrupt Handling</title>
968 <para>
969 Our example handler is for an ISA bus device. If it was PCI you would be
970 able to share the interrupt and would have set IRQF_SHARED to indicate a
971 shared IRQ. We pass the device pointer as the interrupt routine argument. We
972 don't need to since we only support one card but doing this will make it
973 easier to upgrade the driver for multiple devices in the future.
974 </para>
975 <para>
976 Our interrupt routine needs to do little if we assume the card can simply
977 queue one frame to be read after it captures it.
978 </para>
979 <programlisting>
980
981
982static struct wait_queue *capture_wait;
983static int capture_ready = 0;
984
985static void camera_irq(int irq, void *dev_id,
986 struct pt_regs *regs)
987{
988 capture_ready=1;
989 wake_up_interruptible(&amp;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
1007static int camera_poll(struct video_device *dev,
1008 struct file *file, struct poll_table *wait)
1009{
1010 poll_wait(file, &amp;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
1028static 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(&amp;capture_wait, &amp;wait);
1037
1038 while(!capture_ready)
1039 {
1040 if(file->flags&amp;O_NDELAY)
1041 {
1042 remove_wait_queue(&amp;capture_wait, &amp;wait);
1043 current->state = TASK_RUNNING;
1044 return -EWOULDBLOCK;
1045 }
1046 if(signal_pending(current))
1047 {
1048 remove_wait_queue(&amp;capture_wait, &amp;wait);
1049 current->state = TASK_RUNNING;
1050 return -ERESTARTSYS;
1051 }
1052 schedule();
1053 current->state = TASK_INTERRUPTIBLE;
1054 }
1055 remove_wait_queue(&amp;capture_wait, &amp;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&lt;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
1127static 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, &amp;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(&amp;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(&amp;v, arg, sizeof(v)))
1181 return -EFAULT;
1182 return 0;
1183 }
1184
1185
1186 </programlisting>
1187 <para>
1188 This follows what is very much the standard way an ioctl handler looks
1189 in Linux. We copy the data into a kernel space variable and we check that the
1190 request is valid (in this case that the input is 0). Finally we copy the
1191 camera info back to the user.
1192 </para>
1193 <para>
1194 The VIDIOCGCHAN ioctl allows a user to ask about video channels (that is
1195 inputs to the video card). Our example card has a single camera input. The
1196 fields in the structure are
1197 </para>
1198 <table frame="all" id="video_channel_fields"><title>struct video_channel fields</title>
1199 <tgroup cols="2" align="left">
1200 <tbody>
1201 <row>
1202
1203 <entry>channel</entry><entry>The channel number we are selecting</entry>
1204 </row><row>
1205 <entry>name</entry><entry>The name for this channel. This is intended
1206 to describe the port to the user.
1207 Appropriate names are therefore things like
1208 "Camera" "SCART input"</entry>
1209 </row><row>
1210 <entry>flags</entry><entry>Channel properties</entry>
1211 </row><row>
1212 <entry>type</entry><entry>Input type</entry>
1213 </row><row>
1214 <entry>norm</entry><entry>The current television encoding being used
1215 if relevant for this channel.
1216 </entry>
1217 </row>
1218 </tbody>
1219 </tgroup>
1220 </table>
1221 <table frame="all" id="video_channel_flags"><title>struct video_channel flags</title>
1222 <tgroup cols="2" align="left">
1223 <tbody>
1224 <row>
1225 <entry>VIDEO_VC_TUNER</entry><entry>Channel has a tuner.</entry>
1226 </row><row>
1227 <entry>VIDEO_VC_AUDIO</entry><entry>Channel has audio.</entry>
1228 </row>
1229 </tbody>
1230 </tgroup>
1231 </table>
1232 <table frame="all" id="video_channel_types"><title>struct video_channel types</title>
1233 <tgroup cols="2" align="left">
1234 <tbody>
1235 <row>
1236 <entry>VIDEO_TYPE_TV</entry><entry>Television input.</entry>
1237 </row><row>
1238 <entry>VIDEO_TYPE_CAMERA</entry><entry>Fixed camera input.</entry>
1239 </row><row>
1240 <entry>0</entry><entry>Type is unknown.</entry>
1241 </row>
1242 </tbody>
1243 </tgroup>
1244 </table>
1245 <table frame="all" id="video_channel_norms"><title>struct video_channel norms</title>
1246 <tgroup cols="2" align="left">
1247 <tbody>
1248 <row>
1249 <entry>VIDEO_MODE_PAL</entry><entry>PAL encoded Television</entry>
1250 </row><row>
1251 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC (US) encoded Television</entry>
1252 </row><row>
1253 <entry>VIDEO_MODE_SECAM</entry><entry>SECAM (French) Television </entry>
1254 </row><row>
1255 <entry>VIDEO_MODE_AUTO</entry><entry>Automatic switching, or format does not
1256 matter</entry>
1257 </row>
1258 </tbody>
1259 </tgroup>
1260 </table>
1261 <para>
1262 The corresponding VIDIOCSCHAN ioctl allows a user to change channel and to
1263 request the norm is changed - for example to switch between a PAL or an NTSC
1264 format camera.
1265 </para>
1266 <programlisting>
1267
1268
1269 case VIDIOCSCHAN:
1270 {
1271 struct video_channel v;
1272 if(copy_from_user(&amp;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(&amp;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>
1331 <table frame="all" id="Framebuffer_Encodings"><title>Framebuffer Encodings</title>
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(&amp;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
1401static struct video_buffer capture_fb;
1402
1403 case VIDIOCGFBUF:
1404 {
1405 if(copy_to_user(arg, &amp;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(&amp;v, arg, sizeof(v)))
1428 return -EFAULT;
1429 if(v.width!=320 &amp;&amp; v.width!=640)
1430 return -EINVAL;
1431 if(v.height!=200 &amp;&amp; v.height!=240
1432 &amp;&amp; v.height!=400
1433 &amp;&amp; v.height !=480)
1434 return -EINVAL;
1435 memcpy(&amp;capture_fb, &amp;v, sizeof(v));
1436 hardware_set_fb(&amp;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>
1469 <table frame="all" id="video_window_fields"><title>struct video_window fields</title>
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>
1506 <table frame="all" id="video_clip_fields"><title>video_clip fields</title>
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, &amp;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(&amp;v, arg, sizeof(v)))
1545 return -EFAULT;
1546 if(v.width &gt; 640 || v.height &gt; 480)
1547 return -EINVAL;
1548 if(v.width &lt; 16 || v.height &lt; 16)
1549 return -EINVAL;
1550 hardware_set_key(v.chromakey);
1551 hardware_set_window(v);
1552 memcpy(&amp;capture_win, &amp;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/v4l2-dev.c
1652 </chapter>
1653
1654</book>
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7b67f3bf8dd3..f309d3c6221c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -405,7 +405,7 @@ person it names. This tag documents that potentially interested parties
405have been included in the discussion 405have been included in the discussion
406 406
407 407
40814) Using Test-by: and Reviewed-by: 40814) Using Tested-by: and Reviewed-by:
409 409
410A Tested-by: tag indicates that the patch has been successfully tested (in 410A Tested-by: tag indicates that the patch has been successfully tested (in
411some environment) by the person named. This tag informs maintainers that 411some environment) by the person named. This tag informs maintainers that
diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.txt
index e9dc8d86adc7..e8ca040ba2cf 100644
--- a/Documentation/block/data-integrity.txt
+++ b/Documentation/block/data-integrity.txt
@@ -246,7 +246,7 @@ will require extra work due to the application tag.
246 retrieve the tag buffer using bio_integrity_get_tag(). 246 retrieve the tag buffer using bio_integrity_get_tag().
247 247
248 248
2496.3 PASSING EXISTING INTEGRITY METADATA 2495.3 PASSING EXISTING INTEGRITY METADATA
250 250
251 Filesystems that either generate their own integrity metadata or 251 Filesystems that either generate their own integrity metadata or
252 are capable of transferring IMD from user space can use the 252 are capable of transferring IMD from user space can use the
@@ -283,7 +283,7 @@ will require extra work due to the application tag.
283 integrity upon completion. 283 integrity upon completion.
284 284
285 285
2866.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY 2865.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY
287 METADATA 287 METADATA
288 288
289 To enable integrity exchange on a block device the gendisk must be 289 To enable integrity exchange on a block device the gendisk must be
diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro
new file mode 100644
index 000000000000..8cc2cba2b10d
--- /dev/null
+++ b/Documentation/development-process/1.Intro
@@ -0,0 +1,274 @@
11: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS
2
3The purpose of this document is to help developers (and their managers)
4work with the development community with a minimum of frustration. It is
5an attempt to document how this community works in a way which is
6accessible to those who are not intimately familiar with Linux kernel
7development (or, indeed, free software development in general). While
8there is some technical material here, this is very much a process-oriented
9discussion which does not require a deep knowledge of kernel programming to
10understand.
11
12
131.1: EXECUTIVE SUMMARY
14
15The rest of this section covers the scope of the kernel development process
16and the kinds of frustrations that developers and their employers can
17encounter there. There are a great many reasons why kernel code should be
18merged into the official ("mainline") kernel, including automatic
19availability to users, community support in many forms, and the ability to
20influence the direction of kernel development. Code contributed to the
21Linux kernel must be made available under a GPL-compatible license.
22
23Section 2 introduces the development process, the kernel release cycle, and
24the mechanics of the merge window. The various phases in the patch
25development, review, and merging cycle are covered. There is some
26discussion of tools and mailing lists. Developers wanting to get started
27with kernel development are encouraged to track down and fix bugs as an
28initial exercise.
29
30Section 3 covers early-stage project planning, with an emphasis on
31involving the development community as soon as possible.
32
33Section 4 is about the coding process; several pitfalls which have been
34encountered by other developers are discussed. Some requirements for
35patches are covered, and there is an introduction to some of the tools
36which can help to ensure that kernel patches are correct.
37
38Section 5 talks about the process of posting patches for review. To be
39taken seriously by the development community, patches must be properly
40formatted and described, and they must be sent to the right place.
41Following the advice in this section should help to ensure the best
42possible reception for your work.
43
44Section 6 covers what happens after posting patches; the job is far from
45done at that point. Working with reviewers is a crucial part of the
46development process; this section offers a number of tips on how to avoid
47problems at this important stage. Developers are cautioned against
48assuming that the job is done when a patch is merged into the mainline.
49
50Section 7 introduces a couple of "advanced" topics: managing patches with
51git and reviewing patches posted by others.
52
53Section 8 concludes the document with pointers to sources for more
54information on kernel development.
55
56
571.2: WHAT THIS DOCUMENT IS ABOUT
58
59The Linux kernel, at over 6 million lines of code and well over 1000 active
60contributors, is one of the largest and most active free software projects
61in existence. Since its humble beginning in 1991, this kernel has evolved
62into a best-of-breed operating system component which runs on pocket-sized
63digital music players, desktop PCs, the largest supercomputers in
64existence, and all types of systems in between. It is a robust, efficient,
65and scalable solution for almost any situation.
66
67With the growth of Linux has come an increase in the number of developers
68(and companies) wishing to participate in its development. Hardware
69vendors want to ensure that Linux supports their products well, making
70those products attractive to Linux users. Embedded systems vendors, who
71use Linux as a component in an integrated product, want Linux to be as
72capable and well-suited to the task at hand as possible. Distributors and
73other software vendors who base their products on Linux have a clear
74interest in the capabilities, performance, and reliability of the Linux
75kernel. And end users, too, will often wish to change Linux to make it
76better suit their needs.
77
78One of the most compelling features of Linux is that it is accessible to
79these developers; anybody with the requisite skills can improve Linux and
80influence the direction of its development. Proprietary products cannot
81offer this kind of openness, which is a characteristic of the free software
82process. But, if anything, the kernel is even more open than most other
83free software projects. A typical three-month kernel development cycle can
84involve over 1000 developers working for more than 100 different companies
85(or for no company at all).
86
87Working with the kernel development community is not especially hard. But,
88that notwithstanding, many potential contributors have experienced
89difficulties when trying to do kernel work. The kernel community has
90evolved its own distinct ways of operating which allow it to function
91smoothly (and produce a high-quality product) in an environment where
92thousands of lines of code are being changed every day. So it is not
93surprising that Linux kernel development process differs greatly from
94proprietary development methods.
95
96The kernel's development process may come across as strange and
97intimidating to new developers, but there are good reasons and solid
98experience behind it. A developer who does not understand the kernel
99community's ways (or, worse, who tries to flout or circumvent them) will
100have a frustrating experience in store. The development community, while
101being helpful to those who are trying to learn, has little time for those
102who will not listen or who do not care about the development process.
103
104It is hoped that those who read this document will be able to avoid that
105frustrating experience. There is a lot of material here, but the effort
106involved in reading it will be repaid in short order. The development
107community is always in need of developers who will help to make the kernel
108better; the following text should help you - or those who work for you -
109join our community.
110
111
1121.3: CREDITS
113
114This document was written by Jonathan Corbet, corbet@lwn.net. It has been
115improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
116Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,
117Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and
118Jochen Voß.
119
120This work was supported by the Linux Foundation; thanks especially to
121Amanda McPherson, who saw the value of this effort and made it all happen.
122
123
1241.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE
125
126Some companies and developers occasionally wonder why they should bother
127learning how to work with the kernel community and get their code into the
128mainline kernel (the "mainline" being the kernel maintained by Linus
129Torvalds and used as a base by Linux distributors). In the short term,
130contributing code can look like an avoidable expense; it seems easier to
131just keep the code separate and support users directly. The truth of the
132matter is that keeping code separate ("out of tree") is a false economy.
133
134As a way of illustrating the costs of out-of-tree code, here are a few
135relevant aspects of the kernel development process; most of these will be
136discussed in greater detail later in this document. Consider:
137
138- Code which has been merged into the mainline kernel is available to all
139 Linux users. It will automatically be present on all distributions which
140 enable it. There is no need for driver disks, downloads, or the hassles
141 of supporting multiple versions of multiple distributions; it all just
142 works, for the developer and for the user. Incorporation into the
143 mainline solves a large number of distribution and support problems.
144
145- While kernel developers strive to maintain a stable interface to user
146 space, the internal kernel API is in constant flux. The lack of a stable
147 internal interface is a deliberate design decision; it allows fundamental
148 improvements to be made at any time and results in higher-quality code.
149 But one result of that policy is that any out-of-tree code requires
150 constant upkeep if it is to work with new kernels. Maintaining
151 out-of-tree code requires significant amounts of work just to keep that
152 code working.
153
154 Code which is in the mainline, instead, does not require this work as the
155 result of a simple rule requiring any developer who makes an API change
156 to also fix any code that breaks as the result of that change. So code
157 which has been merged into the mainline has significantly lower
158 maintenance costs.
159
160- Beyond that, code which is in the kernel will often be improved by other
161 developers. Surprising results can come from empowering your user
162 community and customers to improve your product.
163
164- Kernel code is subjected to review, both before and after merging into
165 the mainline. No matter how strong the original developer's skills are,
166 this review process invariably finds ways in which the code can be
167 improved. Often review finds severe bugs and security problems. This is
168 especially true for code which has been developed in a closed
169 environment; such code benefits strongly from review by outside
170 developers. Out-of-tree code is lower-quality code.
171
172- Participation in the development process is your way to influence the
173 direction of kernel development. Users who complain from the sidelines
174 are heard, but active developers have a stronger voice - and the ability
175 to implement changes which make the kernel work better for their needs.
176
177- When code is maintained separately, the possibility that a third party
178 will contribute a different implementation of a similar feature always
179 exists. Should that happen, getting your code merged will become much
180 harder - to the point of impossibility. Then you will be faced with the
181 unpleasant alternatives of either (1) maintaining a nonstandard feature
182 out of tree indefinitely, or (2) abandoning your code and migrating your
183 users over to the in-tree version.
184
185- Contribution of code is the fundamental action which makes the whole
186 process work. By contributing your code you can add new functionality to
187 the kernel and provide capabilities and examples which are of use to
188 other kernel developers. If you have developed code for Linux (or are
189 thinking about doing so), you clearly have an interest in the continued
190 success of this platform; contributing code is one of the best ways to
191 help ensure that success.
192
193All of the reasoning above applies to any out-of-tree kernel code,
194including code which is distributed in proprietary, binary-only form.
195There are, however, additional factors which should be taken into account
196before considering any sort of binary-only kernel code distribution. These
197include:
198
199- The legal issues around the distribution of proprietary kernel modules
200 are cloudy at best; quite a few kernel copyright holders believe that
201 most binary-only modules are derived products of the kernel and that, as
202 a result, their distribution is a violation of the GNU General Public
203 license (about which more will be said below). Your author is not a
204 lawyer, and nothing in this document can possibly be considered to be
205 legal advice. The true legal status of closed-source modules can only be
206 determined by the courts. But the uncertainty which haunts those modules
207 is there regardless.
208
209- Binary modules greatly increase the difficulty of debugging kernel
210 problems, to the point that most kernel developers will not even try. So
211 the distribution of binary-only modules will make it harder for your
212 users to get support from the community.
213
214- Support is also harder for distributors of binary-only modules, who must
215 provide a version of the module for every distribution and every kernel
216 version they wish to support. Dozens of builds of a single module can
217 be required to provide reasonably comprehensive coverage, and your users
218 will have to upgrade your module separately every time they upgrade their
219 kernel.
220
221- Everything that was said above about code review applies doubly to
222 closed-source code. Since this code is not available at all, it cannot
223 have been reviewed by the community and will, beyond doubt, have serious
224 problems.
225
226Makers of embedded systems, in particular, may be tempted to disregard much
227of what has been said in this section in the belief that they are shipping
228a self-contained product which uses a frozen kernel version and requires no
229more development after its release. This argument misses the value of
230widespread code review and the value of allowing your users to add
231capabilities to your product. But these products, too, have a limited
232commercial life, after which a new version must be released. At that
233point, vendors whose code is in the mainline and well maintained will be
234much better positioned to get the new product ready for market quickly.
235
236
2371.5: LICENSING
238
239Code is contributed to the Linux kernel under a number of licenses, but all
240code must be compatible with version 2 of the GNU General Public License
241(GPLv2), which is the license covering the kernel distribution as a whole.
242In practice, that means that all code contributions are covered either by
243GPLv2 (with, optionally, language allowing distribution under later
244versions of the GPL) or the three-clause BSD license. Any contributions
245which are not covered by a compatible license will not be accepted into the
246kernel.
247
248Copyright assignments are not required (or requested) for code contributed
249to the kernel. All code merged into the mainline kernel retains its
250original ownership; as a result, the kernel now has thousands of owners.
251
252One implication of this ownership structure is that any attempt to change
253the licensing of the kernel is doomed to almost certain failure. There are
254few practical scenarios where the agreement of all copyright holders could
255be obtained (or their code removed from the kernel). So, in particular,
256there is no prospect of a migration to version 3 of the GPL in the
257foreseeable future.
258
259It is imperative that all code contributed to the kernel be legitimately
260free software. For that reason, code from anonymous (or pseudonymous)
261contributors will not be accepted. All contributors are required to "sign
262off" on their code, stating that the code can be distributed with the
263kernel under the GPL. Code which has not been licensed as free software by
264its owner, or which risks creating copyright-related problems for the
265kernel (such as code which derives from reverse-engineering efforts lacking
266proper safeguards) cannot be contributed.
267
268Questions about copyright-related issues are common on Linux development
269mailing lists. Such questions will normally receive no shortage of
270answers, but one should bear in mind that the people answering those
271questions are not lawyers and cannot provide legal advice. If you have
272legal questions relating to Linux source code, there is no substitute for
273talking with a lawyer who understands this field. Relying on answers
274obtained on technical mailing lists is a risky affair.
diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process
new file mode 100644
index 000000000000..d750321acd5a
--- /dev/null
+++ b/Documentation/development-process/2.Process
@@ -0,0 +1,459 @@
12: HOW THE DEVELOPMENT PROCESS WORKS
2
3Linux kernel development in the early 1990's was a pretty loose affair,
4with relatively small numbers of users and developers involved. With a
5user base in the millions and with some 2,000 developers involved over the
6course of one year, the kernel has since had to evolve a number of
7processes to keep development happening smoothly. A solid understanding of
8how the process works is required in order to be an effective part of it.
9
10
112.1: THE BIG PICTURE
12
13The kernel developers use a loosely time-based release process, with a new
14major kernel release happening every two or three months. The recent
15release history looks like this:
16
17 2.6.26 July 13, 2008
18 2.6.25 April 16, 2008
19 2.6.24 January 24, 2008
20 2.6.23 October 9, 2007
21 2.6.22 July 8, 2007
22 2.6.21 April 25, 2007
23 2.6.20 February 4, 2007
24
25Every 2.6.x release is a major kernel release with new features, internal
26API changes, and more. A typical 2.6 release can contain over 10,000
27changesets with changes to several hundred thousand lines of code. 2.6 is
28thus the leading edge of Linux kernel development; the kernel uses a
29rolling development model which is continually integrating major changes.
30
31A relatively straightforward discipline is followed with regard to the
32merging of patches for each release. At the beginning of each development
33cycle, the "merge window" is said to be open. At that time, code which is
34deemed to be sufficiently stable (and which is accepted by the development
35community) is merged into the mainline kernel. The bulk of changes for a
36new development cycle (and all of the major changes) will be merged during
37this time, at a rate approaching 1,000 changes ("patches," or "changesets")
38per day.
39
40(As an aside, it is worth noting that the changes integrated during the
41merge window do not come out of thin air; they have been collected, tested,
42and staged ahead of time. How that process works will be described in
43detail later on).
44
45The merge window lasts for two weeks. At the end of this time, Linus
46Torvalds will declare that the window is closed and release the first of
47the "rc" kernels. For the kernel which is destined to be 2.6.26, for
48example, the release which happens at the end of the merge window will be
49called 2.6.26-rc1. The -rc1 release is the signal that the time to merge
50new features has passed, and that the time to stabilize the next kernel has
51begun.
52
53Over the next six to ten weeks, only patches which fix problems should be
54submitted to the mainline. On occasion a more significant change will be
55allowed, but such occasions are rare; developers who try to merge new
56features outside of the merge window tend to get an unfriendly reception.
57As a general rule, if you miss the merge window for a given feature, the
58best thing to do is to wait for the next development cycle. (An occasional
59exception is made for drivers for previously-unsupported hardware; if they
60touch no in-tree code, they cannot cause regressions and should be safe to
61add at any time).
62
63As fixes make their way into the mainline, the patch rate will slow over
64time. Linus releases new -rc kernels about once a week; a normal series
65will get up to somewhere between -rc6 and -rc9 before the kernel is
66considered to be sufficiently stable and the final 2.6.x release is made.
67At that point the whole process starts over again.
68
69As an example, here is how the 2.6.25 development cycle went (all dates in
702008):
71
72 January 24 2.6.24 stable release
73 February 10 2.6.25-rc1, merge window closes
74 February 15 2.6.25-rc2
75 February 24 2.6.25-rc3
76 March 4 2.6.25-rc4
77 March 9 2.6.25-rc5
78 March 16 2.6.25-rc6
79 March 25 2.6.25-rc7
80 April 1 2.6.25-rc8
81 April 11 2.6.25-rc9
82 April 16 2.6.25 stable release
83
84How do the developers decide when to close the development cycle and create
85the stable release? The most significant metric used is the list of
86regressions from previous releases. No bugs are welcome, but those which
87break systems which worked in the past are considered to be especially
88serious. For this reason, patches which cause regressions are looked upon
89unfavorably and are quite likely to be reverted during the stabilization
90period.
91
92The developers' goal is to fix all known regressions before the stable
93release is made. In the real world, this kind of perfection is hard to
94achieve; there are just too many variables in a project of this size.
95There comes a point where delaying the final release just makes the problem
96worse; the pile of changes waiting for the next merge window will grow
97larger, creating even more regressions the next time around. So most 2.6.x
98kernels go out with a handful of known regressions though, hopefully, none
99of them are serious.
100
101Once a stable release is made, its ongoing maintenance is passed off to the
102"stable team," currently comprised of Greg Kroah-Hartman and Chris Wright.
103The stable team will release occasional updates to the stable release using
104the 2.6.x.y numbering scheme. To be considered for an update release, a
105patch must (1) fix a significant bug, and (2) already be merged into the
106mainline for the next development kernel. Continuing our 2.6.25 example,
107the history (as of this writing) is:
108
109 May 1 2.6.25.1
110 May 6 2.6.25.2
111 May 9 2.6.25.3
112 May 15 2.6.25.4
113 June 7 2.6.25.5
114 June 9 2.6.25.6
115 June 16 2.6.25.7
116 June 21 2.6.25.8
117 June 24 2.6.25.9
118
119Stable updates for a given kernel are made for approximately six months;
120after that, the maintenance of stable releases is solely the responsibility
121of the distributors which have shipped that particular kernel.
122
123
1242.2: THE LIFECYCLE OF A PATCH
125
126Patches do not go directly from the developer's keyboard into the mainline
127kernel. There is, instead, a somewhat involved (if somewhat informal)
128process designed to ensure that each patch is reviewed for quality and that
129each patch implements a change which is desirable to have in the mainline.
130This process can happen quickly for minor fixes, or, in the case of large
131and controversial changes, go on for years. Much developer frustration
132comes from a lack of understanding of this process or from attempts to
133circumvent it.
134
135In the hopes of reducing that frustration, this document will describe how
136a patch gets into the kernel. What follows below is an introduction which
137describes the process in a somewhat idealized way. A much more detailed
138treatment will come in later sections.
139
140The stages that a patch goes through are, generally:
141
142 - Design. This is where the real requirements for the patch - and the way
143 those requirements will be met - are laid out. Design work is often
144 done without involving the community, but it is better to do this work
145 in the open if at all possible; it can save a lot of time redesigning
146 things later.
147
148 - Early review. Patches are posted to the relevant mailing list, and
149 developers on that list reply with any comments they may have. This
150 process should turn up any major problems with a patch if all goes
151 well.
152
153 - Wider review. When the patch is getting close to ready for mainline
154 inclusion, it will be accepted by a relevant subsystem maintainer -
155 though this acceptance is not a guarantee that the patch will make it
156 all the way to the mainline. The patch will show up in the maintainer's
157 subsystem tree and into the staging trees (described below). When the
158 process works, this step leads to more extensive review of the patch and
159 the discovery of any problems resulting from the integration of this
160 patch with work being done by others.
161
162 - Merging into the mainline. Eventually, a successful patch will be
163 merged into the mainline repository managed by Linus Torvalds. More
164 comments and/or problems may surface at this time; it is important that
165 the developer be responsive to these and fix any issues which arise.
166
167 - Stable release. The number of users potentially affected by the patch
168 is now large, so, once again, new problems may arise.
169
170 - Long-term maintenance. While it is certainly possible for a developer
171 to forget about code after merging it, that sort of behavior tends to
172 leave a poor impression in the development community. Merging code
173 eliminates some of the maintenance burden, in that others will fix
174 problems caused by API changes. But the original developer should
175 continue to take responsibility for the code if it is to remain useful
176 in the longer term.
177
178One of the largest mistakes made by kernel developers (or their employers)
179is to try to cut the process down to a single "merging into the mainline"
180step. This approach invariably leads to frustration for everybody
181involved.
182
183
1842.3: HOW PATCHES GET INTO THE KERNEL
185
186There is exactly one person who can merge patches into the mainline kernel
187repository: Linus Torvalds. But, of the over 12,000 patches which went
188into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus
189himself. The kernel project has long since grown to a size where no single
190developer could possibly inspect and select every patch unassisted. The
191way the kernel developers have addressed this growth is through the use of
192a lieutenant system built around a chain of trust.
193
194The kernel code base is logically broken down into a set of subsystems:
195networking, specific architecture support, memory management, video
196devices, etc. Most subsystems have a designated maintainer, a developer
197who has overall responsibility for the code within that subsystem. These
198subsystem maintainers are the gatekeepers (in a loose way) for the portion
199of the kernel they manage; they are the ones who will (usually) accept a
200patch for inclusion into the mainline kernel.
201
202Subsystem maintainers each manage their own version of the kernel source
203tree, usually (but certainly not always) using the git source management
204tool. Tools like git (and related tools like quilt or mercurial) allow
205maintainers to track a list of patches, including authorship information
206and other metadata. At any given time, the maintainer can identify which
207patches in his or her repository are not found in the mainline.
208
209When the merge window opens, top-level maintainers will ask Linus to "pull"
210the patches they have selected for merging from their repositories. If
211Linus agrees, the stream of patches will flow up into his repository,
212becoming part of the mainline kernel. The amount of attention that Linus
213pays to specific patches received in a pull operation varies. It is clear
214that, sometimes, he looks quite closely. But, as a general rule, Linus
215trusts the subsystem maintainers to not send bad patches upstream.
216
217Subsystem maintainers, in turn, can pull patches from other maintainers.
218For example, the networking tree is built from patches which accumulated
219first in trees dedicated to network device drivers, wireless networking,
220etc. This chain of repositories can be arbitrarily long, though it rarely
221exceeds two or three links. Since each maintainer in the chain trusts
222those managing lower-level trees, this process is known as the "chain of
223trust."
224
225Clearly, in a system like this, getting patches into the kernel depends on
226finding the right maintainer. Sending patches directly to Linus is not
227normally the right way to go.
228
229
2302.4: STAGING TREES
231
232The chain of subsystem trees guides the flow of patches into the kernel,
233but it also raises an interesting question: what if somebody wants to look
234at all of the patches which are being prepared for the next merge window?
235Developers will be interested in what other changes are pending to see
236whether there are any conflicts to worry about; a patch which changes a
237core kernel function prototype, for example, will conflict with any other
238patches which use the older form of that function. Reviewers and testers
239want access to the changes in their integrated form before all of those
240changes land in the mainline kernel. One could pull changes from all of
241the interesting subsystem trees, but that would be a big and error-prone
242job.
243
244The answer comes in the form of staging trees, where subsystem trees are
245collected for testing and review. The older of these trees, maintained by
246Andrew Morton, is called "-mm" (for memory management, which is how it got
247started). The -mm tree integrates patches from a long list of subsystem
248trees; it also has some patches aimed at helping with debugging.
249
250Beyond that, -mm contains a significant collection of patches which have
251been selected by Andrew directly. These patches may have been posted on a
252mailing list, or they may apply to a part of the kernel for which there is
253no designated subsystem tree. As a result, -mm operates as a sort of
254subsystem tree of last resort; if there is no other obvious path for a
255patch into the mainline, it is likely to end up in -mm. Miscellaneous
256patches which accumulate in -mm will eventually either be forwarded on to
257an appropriate subsystem tree or be sent directly to Linus. In a typical
258development cycle, approximately 10% of the patches going into the mainline
259get there via -mm.
260
261The current -mm patch can always be found from the front page of
262
263 http://kernel.org/
264
265Those who want to see the current state of -mm can get the "-mm of the
266moment" tree, found at:
267
268 http://userweb.kernel.org/~akpm/mmotm/
269
270Use of the MMOTM tree is likely to be a frustrating experience, though;
271there is a definite chance that it will not even compile.
272
273The other staging tree, started more recently, is linux-next, maintained by
274Stephen Rothwell. The linux-next tree is, by design, a snapshot of what
275the mainline is expected to look like after the next merge window closes.
276Linux-next trees are announced on the linux-kernel and linux-next mailing
277lists when they are assembled; they can be downloaded from:
278
279 http://www.kernel.org/pub/linux/kernel/people/sfr/linux-next/
280
281Some information about linux-next has been gathered at:
282
283 http://linux.f-seidel.de/linux-next/pmwiki/
284
285How the linux-next tree will fit into the development process is still
286changing. As of this writing, the first full development cycle involving
287linux-next (2.6.26) is coming to an end; thus far, it has proved to be a
288valuable resource for finding and fixing integration problems before the
289beginning of the merge window. See http://lwn.net/Articles/287155/ for
290more information on how linux-next has worked to set up the 2.6.27 merge
291window.
292
293Some developers have begun to suggest that linux-next should be used as the
294target for future development as well. The linux-next tree does tend to be
295far ahead of the mainline and is more representative of the tree into which
296any new work will be merged. The downside to this idea is that the
297volatility of linux-next tends to make it a difficult development target.
298See http://lwn.net/Articles/289013/ for more information on this topic, and
299stay tuned; much is still in flux where linux-next is involved.
300
301
3022.5: TOOLS
303
304As can be seen from the above text, the kernel development process depends
305heavily on the ability to herd collections of patches in various
306directions. The whole thing would not work anywhere near as well as it
307does without suitably powerful tools. Tutorials on how to use these tools
308are well beyond the scope of this document, but there is space for a few
309pointers.
310
311By far the dominant source code management system used by the kernel
312community is git. Git is one of a number of distributed version control
313systems being developed in the free software community. It is well tuned
314for kernel development, in that it performs quite well when dealing with
315large repositories and large numbers of patches. It also has a reputation
316for being difficult to learn and use, though it has gotten better over
317time. Some sort of familiarity with git is almost a requirement for kernel
318developers; even if they do not use it for their own work, they'll need git
319to keep up with what other developers (and the mainline) are doing.
320
321Git is now packaged by almost all Linux distributions. There is a home
322page at
323
324 http://git.or.cz/
325
326That page has pointers to documentation and tutorials. One should be
327aware, in particular, of the Kernel Hacker's Guide to git, which has
328information specific to kernel development:
329
330 http://linux.yyz.us/git-howto.html
331
332Among the kernel developers who do not use git, the most popular choice is
333almost certainly Mercurial:
334
335 http://www.selenic.com/mercurial/
336
337Mercurial shares many features with git, but it provides an interface which
338many find easier to use.
339
340The other tool worth knowing about is Quilt:
341
342 http://savannah.nongnu.org/projects/quilt/
343
344Quilt is a patch management system, rather than a source code management
345system. It does not track history over time; it is, instead, oriented
346toward tracking a specific set of changes against an evolving code base.
347Some major subsystem maintainers use quilt to manage patches intended to go
348upstream. For the management of certain kinds of trees (-mm, for example),
349quilt is the best tool for the job.
350
351
3522.6: MAILING LISTS
353
354A great deal of Linux kernel development work is done by way of mailing
355lists. It is hard to be a fully-functioning member of the community
356without joining at least one list somewhere. But Linux mailing lists also
357represent a potential hazard to developers, who risk getting buried under a
358load of electronic mail, running afoul of the conventions used on the Linux
359lists, or both.
360
361Most kernel mailing lists are run on vger.kernel.org; the master list can
362be found at:
363
364 http://vger.kernel.org/vger-lists.html
365
366There are lists hosted elsewhere, though; a number of them are at
367lists.redhat.com.
368
369The core mailing list for kernel development is, of course, linux-kernel.
370This list is an intimidating place to be; volume can reach 500 messages per
371day, the amount of noise is high, the conversation can be severely
372technical, and participants are not always concerned with showing a high
373degree of politeness. But there is no other place where the kernel
374development community comes together as a whole; developers who avoid this
375list will miss important information.
376
377There are a few hints which can help with linux-kernel survival:
378
379- Have the list delivered to a separate folder, rather than your main
380 mailbox. One must be able to ignore the stream for sustained periods of
381 time.
382
383- Do not try to follow every conversation - nobody else does. It is
384 important to filter on both the topic of interest (though note that
385 long-running conversations can drift away from the original subject
386 without changing the email subject line) and the people who are
387 participating.
388
389- Do not feed the trolls. If somebody is trying to stir up an angry
390 response, ignore them.
391
392- When responding to linux-kernel email (or that on other lists) preserve
393 the Cc: header for all involved. In the absence of a strong reason (such
394 as an explicit request), you should never remove recipients. Always make
395 sure that the person you are responding to is in the Cc: list. This
396 convention also makes it unnecessary to explicitly ask to be copied on
397 replies to your postings.
398
399- Search the list archives (and the net as a whole) before asking
400 questions. Some developers can get impatient with people who clearly
401 have not done their homework.
402
403- Avoid top-posting (the practice of putting your answer above the quoted
404 text you are responding to). It makes your response harder to read and
405 makes a poor impression.
406
407- Ask on the correct mailing list. Linux-kernel may be the general meeting
408 point, but it is not the best place to find developers from all
409 subsystems.
410
411The last point - finding the correct mailing list - is a common place for
412beginning developers to go wrong. Somebody who asks a networking-related
413question on linux-kernel will almost certainly receive a polite suggestion
414to ask on the netdev list instead, as that is the list frequented by most
415networking developers. Other lists exist for the SCSI, video4linux, IDE,
416filesystem, etc. subsystems. The best place to look for mailing lists is
417in the MAINTAINERS file packaged with the kernel source.
418
419
4202.7: GETTING STARTED WITH KERNEL DEVELOPMENT
421
422Questions about how to get started with the kernel development process are
423common - from both individuals and companies. Equally common are missteps
424which make the beginning of the relationship harder than it has to be.
425
426Companies often look to hire well-known developers to get a development
427group started. This can, in fact, be an effective technique. But it also
428tends to be expensive and does not do much to grow the pool of experienced
429kernel developers. It is possible to bring in-house developers up to speed
430on Linux kernel development, given the investment of a bit of time. Taking
431this time can endow an employer with a group of developers who understand
432the kernel and the company both, and who can help to train others as well.
433Over the medium term, this is often the more profitable approach.
434
435Individual developers are often, understandably, at a loss for a place to
436start. Beginning with a large project can be intimidating; one often wants
437to test the waters with something smaller first. This is the point where
438some developers jump into the creation of patches fixing spelling errors or
439minor coding style issues. Unfortunately, such patches create a level of
440noise which is distracting for the development community as a whole, so,
441increasingly, they are looked down upon. New developers wishing to
442introduce themselves to the community will not get the sort of reception
443they wish for by these means.
444
445Andrew Morton gives this advice for aspiring kernel developers
446
447 The #1 project for all kernel beginners should surely be "make sure
448 that the kernel runs perfectly at all times on all machines which
449 you can lay your hands on". Usually the way to do this is to work
450 with others on getting things fixed up (this can require
451 persistence!) but that's fine - it's a part of kernel development.
452
453(http://lwn.net/Articles/283982/).
454
455In the absence of obvious problems to fix, developers are advised to look
456at the current lists of regressions and open bugs in general. There is
457never any shortage of issues in need of fixing; by addressing these issues,
458developers will gain experience with the process while, at the same time,
459building respect with the rest of the development community.
diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage
new file mode 100644
index 000000000000..307a159a70ca
--- /dev/null
+++ b/Documentation/development-process/3.Early-stage
@@ -0,0 +1,195 @@
13: EARLY-STAGE PLANNING
2
3When contemplating a Linux kernel development project, it can be tempting
4to jump right in and start coding. As with any significant project,
5though, much of the groundwork for success is best laid before the first
6line of code is written. Some time spent in early planning and
7communication can save far more time later on.
8
9
103.1: SPECIFYING THE PROBLEM
11
12Like any engineering project, a successful kernel enhancement starts with a
13clear description of the problem to be solved. In some cases, this step is
14easy: when a driver is needed for a specific piece of hardware, for
15example. In others, though, it is tempting to confuse the real problem
16with the proposed solution, and that can lead to difficulties.
17
18Consider an example: some years ago, developers working with Linux audio
19sought a way to run applications without dropouts or other artifacts caused
20by excessive latency in the system. The solution they arrived at was a
21kernel module intended to hook into the Linux Security Module (LSM)
22framework; this module could be configured to give specific applications
23access to the realtime scheduler. This module was implemented and sent to
24the linux-kernel mailing list, where it immediately ran into problems.
25
26To the audio developers, this security module was sufficient to solve their
27immediate problem. To the wider kernel community, though, it was seen as a
28misuse of the LSM framework (which is not intended to confer privileges
29onto processes which they would not otherwise have) and a risk to system
30stability. Their preferred solutions involved realtime scheduling access
31via the rlimit mechanism for the short term, and ongoing latency reduction
32work in the long term.
33
34The audio community, however, could not see past the particular solution
35they had implemented; they were unwilling to accept alternatives. The
36resulting disagreement left those developers feeling disillusioned with the
37entire kernel development process; one of them went back to an audio list
38and posted this:
39
40 There are a number of very good Linux kernel developers, but they
41 tend to get outshouted by a large crowd of arrogant fools. Trying
42 to communicate user requirements to these people is a waste of
43 time. They are much too "intelligent" to listen to lesser mortals.
44
45(http://lwn.net/Articles/131776/).
46
47The reality of the situation was different; the kernel developers were far
48more concerned about system stability, long-term maintenance, and finding
49the right solution to the problem than they were with a specific module.
50The moral of the story is to focus on the problem - not a specific solution
51- and to discuss it with the development community before investing in the
52creation of a body of code.
53
54So, when contemplating a kernel development project, one should obtain
55answers to a short set of questions:
56
57 - What, exactly, is the problem which needs to be solved?
58
59 - Who are the users affected by this problem? Which use cases should the
60 solution address?
61
62 - How does the kernel fall short in addressing that problem now?
63
64Only then does it make sense to start considering possible solutions.
65
66
673.2: EARLY DISCUSSION
68
69When planning a kernel development project, it makes great sense to hold
70discussions with the community before launching into implementation. Early
71communication can save time and trouble in a number of ways:
72
73 - It may well be that the problem is addressed by the kernel in ways which
74 you have not understood. The Linux kernel is large and has a number of
75 features and capabilities which are not immediately obvious. Not all
76 kernel capabilities are documented as well as one might like, and it is
77 easy to miss things. Your author has seen the posting of a complete
78 driver which duplicated an existing driver that the new author had been
79 unaware of. Code which reinvents existing wheels is not only wasteful;
80 it will also not be accepted into the mainline kernel.
81
82 - There may be elements of the proposed solution which will not be
83 acceptable for mainline merging. It is better to find out about
84 problems like this before writing the code.
85
86 - It's entirely possible that other developers have thought about the
87 problem; they may have ideas for a better solution, and may be willing
88 to help in the creation of that solution.
89
90Years of experience with the kernel development community have taught a
91clear lesson: kernel code which is designed and developed behind closed
92doors invariably has problems which are only revealed when the code is
93released into the community. Sometimes these problems are severe,
94requiring months or years of effort before the code can be brought up to
95the kernel community's standards. Some examples include:
96
97 - The Devicescape network stack was designed and implemented for
98 single-processor systems. It could not be merged into the mainline
99 until it was made suitable for multiprocessor systems. Retrofitting
100 locking and such into code is a difficult task; as a result, the merging
101 of this code (now called mac80211) was delayed for over a year.
102
103 - The Reiser4 filesystem included a number of capabilities which, in the
104 core kernel developers' opinion, should have been implemented in the
105 virtual filesystem layer instead. It also included features which could
106 not easily be implemented without exposing the system to user-caused
107 deadlocks. The late revelation of these problems - and refusal to
108 address some of them - has caused Reiser4 to stay out of the mainline
109 kernel.
110
111 - The AppArmor security module made use of internal virtual filesystem
112 data structures in ways which were considered to be unsafe and
113 unreliable. This code has since been significantly reworked, but
114 remains outside of the mainline.
115
116In each of these cases, a great deal of pain and extra work could have been
117avoided with some early discussion with the kernel developers.
118
119
1203.3: WHO DO YOU TALK TO?
121
122When developers decide to take their plans public, the next question will
123be: where do we start? The answer is to find the right mailing list(s) and
124the right maintainer. For mailing lists, the best approach is to look in
125the MAINTAINERS file for a relevant place to post. If there is a suitable
126subsystem list, posting there is often preferable to posting on
127linux-kernel; you are more likely to reach developers with expertise in the
128relevant subsystem and the environment may be more supportive.
129
130Finding maintainers can be a bit harder. Again, the MAINTAINERS file is
131the place to start. That file tends to not always be up to date, though,
132and not all subsystems are represented there. The person listed in the
133MAINTAINERS file may, in fact, not be the person who is actually acting in
134that role currently. So, when there is doubt about who to contact, a
135useful trick is to use git (and "git log" in particular) to see who is
136currently active within the subsystem of interest. Look at who is writing
137patches, and who, if anybody, is attaching Signed-off-by lines to those
138patches. Those are the people who will be best placed to help with a new
139development project.
140
141If all else fails, talking to Andrew Morton can be an effective way to
142track down a maintainer for a specific piece of code.
143
144
1453.4: WHEN TO POST?
146
147If possible, posting your plans during the early stages can only be
148helpful. Describe the problem being solved and any plans that have been
149made on how the implementation will be done. Any information you can
150provide can help the development community provide useful input on the
151project.
152
153One discouraging thing which can happen at this stage is not a hostile
154reaction, but, instead, little or no reaction at all. The sad truth of the
155matter is (1) kernel developers tend to be busy, (2) there is no shortage
156of people with grand plans and little code (or even prospect of code) to
157back them up, and (3) nobody is obligated to review or comment on ideas
158posted by others. If a request-for-comments posting yields little in the
159way of comments, do not assume that it means there is no interest in the
160project. Unfortunately, you also cannot assume that there are no problems
161with your idea. The best thing to do in this situation is to proceed,
162keeping the community informed as you go.
163
164
1653.5: GETTING OFFICIAL BUY-IN
166
167If your work is being done in a corporate environment - as most Linux
168kernel work is - you must, obviously, have permission from suitably
169empowered managers before you can post your company's plans or code to a
170public mailing list. The posting of code which has not been cleared for
171release under a GPL-compatible license can be especially problematic; the
172sooner that a company's management and legal staff can agree on the posting
173of a kernel development project, the better off everybody involved will be.
174
175Some readers may be thinking at this point that their kernel work is
176intended to support a product which does not yet have an officially
177acknowledged existence. Revealing their employer's plans on a public
178mailing list may not be a viable option. In cases like this, it is worth
179considering whether the secrecy is really necessary; there is often no real
180need to keep development plans behind closed doors.
181
182That said, there are also cases where a company legitimately cannot
183disclose its plans early in the development process. Companies with
184experienced kernel developers may choose to proceed in an open-loop manner
185on the assumption that they will be able to avoid serious integration
186problems later. For companies without that sort of in-house expertise, the
187best option is often to hire an outside developer to review the plans under
188a non-disclosure agreement. The Linux Foundation operates an NDA program
189designed to help with this sort of situation; more information can be found
190at:
191
192 http://www.linuxfoundation.org/en/NDA_program
193
194This kind of review is often enough to avoid serious problems later on
195without requiring public disclosure of the project.
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding
new file mode 100644
index 000000000000..014aca8f14e2
--- /dev/null
+++ b/Documentation/development-process/4.Coding
@@ -0,0 +1,384 @@
14: GETTING THE CODE RIGHT
2
3While there is much to be said for a solid and community-oriented design
4process, the proof of any kernel development project is in the resulting
5code. It is the code which will be examined by other developers and merged
6(or not) into the mainline tree. So it is the quality of this code which
7will determine the ultimate success of the project.
8
9This section will examine the coding process. We'll start with a look at a
10number of ways in which kernel developers can go wrong. Then the focus
11will shift toward doing things right and the tools which can help in that
12quest.
13
14
154.1: PITFALLS
16
17* Coding style
18
19The kernel has long had a standard coding style, described in
20Documentation/CodingStyle. For much of that time, the policies described
21in that file were taken as being, at most, advisory. As a result, there is
22a substantial amount of code in the kernel which does not meet the coding
23style guidelines. The presence of that code leads to two independent
24hazards for kernel developers.
25
26The first of these is to believe that the kernel coding standards do not
27matter and are not enforced. The truth of the matter is that adding new
28code to the kernel is very difficult if that code is not coded according to
29the standard; many developers will request that the code be reformatted
30before they will even review it. A code base as large as the kernel
31requires some uniformity of code to make it possible for developers to
32quickly understand any part of it. So there is no longer room for
33strangely-formatted code.
34
35Occasionally, the kernel's coding style will run into conflict with an
36employer's mandated style. In such cases, the kernel's style will have to
37win before the code can be merged. Putting code into the kernel means
38giving up a degree of control in a number of ways - including control over
39how the code is formatted.
40
41The other trap is to assume that code which is already in the kernel is
42urgently in need of coding style fixes. Developers may start to generate
43reformatting patches as a way of gaining familiarity with the process, or
44as a way of getting their name into the kernel changelogs - or both. But
45pure coding style fixes are seen as noise by the development community;
46they tend to get a chilly reception. So this type of patch is best
47avoided. It is natural to fix the style of a piece of code while working
48on it for other reasons, but coding style changes should not be made for
49their own sake.
50
51The coding style document also should not be read as an absolute law which
52can never be transgressed. If there is a good reason to go against the
53style (a line which becomes far less readable if split to fit within the
5480-column limit, for example), just do it.
55
56
57* Abstraction layers
58
59Computer Science professors teach students to make extensive use of
60abstraction layers in the name of flexibility and information hiding.
61Certainly the kernel makes extensive use of abstraction; no project
62involving several million lines of code could do otherwise and survive.
63But experience has shown that excessive or premature abstraction can be
64just as harmful as premature optimization. Abstraction should be used to
65the level required and no further.
66
67At a simple level, consider a function which has an argument which is
68always passed as zero by all callers. One could retain that argument just
69in case somebody eventually needs to use the extra flexibility that it
70provides. By that time, though, chances are good that the code which
71implements this extra argument has been broken in some subtle way which was
72never noticed - because it has never been used. Or, when the need for
73extra flexibility arises, it does not do so in a way which matches the
74programmer's early expectation. Kernel developers will routinely submit
75patches to remove unused arguments; they should, in general, not be added
76in the first place.
77
78Abstraction layers which hide access to hardware - often to allow the bulk
79of a driver to be used with multiple operating systems - are especially
80frowned upon. Such layers obscure the code and may impose a performance
81penalty; they do not belong in the Linux kernel.
82
83On the other hand, if you find yourself copying significant amounts of code
84from another kernel subsystem, it is time to ask whether it would, in fact,
85make sense to pull out some of that code into a separate library or to
86implement that functionality at a higher level. There is no value in
87replicating the same code throughout the kernel.
88
89
90* #ifdef and preprocessor use in general
91
92The C preprocessor seems to present a powerful temptation to some C
93programmers, who see it as a way to efficiently encode a great deal of
94flexibility into a source file. But the preprocessor is not C, and heavy
95use of it results in code which is much harder for others to read and
96harder for the compiler to check for correctness. Heavy preprocessor use
97is almost always a sign of code which needs some cleanup work.
98
99Conditional compilation with #ifdef is, indeed, a powerful feature, and it
100is used within the kernel. But there is little desire to see code which is
101sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use
102should be confined to header files whenever possible.
103Conditionally-compiled code can be confined to functions which, if the code
104is not to be present, simply become empty. The compiler will then quietly
105optimize out the call to the empty function. The result is far cleaner
106code which is easier to follow.
107
108C preprocessor macros present a number of hazards, including possible
109multiple evaluation of expressions with side effects and no type safety.
110If you are tempted to define a macro, consider creating an inline function
111instead. The code which results will be the same, but inline functions are
112easier to read, do not evaluate their arguments multiple times, and allow
113the compiler to perform type checking on the arguments and return value.
114
115
116* Inline functions
117
118Inline functions present a hazard of their own, though. Programmers can
119become enamored of the perceived efficiency inherent in avoiding a function
120call and fill a source file with inline functions. Those functions,
121however, can actually reduce performance. Since their code is replicated
122at each call site, they end up bloating the size of the compiled kernel.
123That, in turn, creates pressure on the processor's memory caches, which can
124slow execution dramatically. Inline functions, as a rule, should be quite
125small and relatively rare. The cost of a function call, after all, is not
126that high; the creation of large numbers of inline functions is a classic
127example of premature optimization.
128
129In general, kernel programmers ignore cache effects at their peril. The
130classic time/space tradeoff taught in beginning data structures classes
131often does not apply to contemporary hardware. Space *is* time, in that a
132larger program will run slower than one which is more compact.
133
134
135* Locking
136
137In May, 2006, the "Devicescape" networking stack was, with great
138fanfare, released under the GPL and made available for inclusion in the
139mainline kernel. This donation was welcome news; support for wireless
140networking in Linux was considered substandard at best, and the Devicescape
141stack offered the promise of fixing that situation. Yet, this code did not
142actually make it into the mainline until June, 2007 (2.6.22). What
143happened?
144
145This code showed a number of signs of having been developed behind
146corporate doors. But one large problem in particular was that it was not
147designed to work on multiprocessor systems. Before this networking stack
148(now called mac80211) could be merged, a locking scheme needed to be
149retrofitted onto it.
150
151Once upon a time, Linux kernel code could be developed without thinking
152about the concurrency issues presented by multiprocessor systems. Now,
153however, this document is being written on a dual-core laptop. Even on
154single-processor systems, work being done to improve responsiveness will
155raise the level of concurrency within the kernel. The days when kernel
156code could be written without thinking about locking are long past.
157
158Any resource (data structures, hardware registers, etc.) which could be
159accessed concurrently by more than one thread must be protected by a lock.
160New code should be written with this requirement in mind; retrofitting
161locking after the fact is a rather more difficult task. Kernel developers
162should take the time to understand the available locking primitives well
163enough to pick the right tool for the job. Code which shows a lack of
164attention to concurrency will have a difficult path into the mainline.
165
166
167* Regressions
168
169One final hazard worth mentioning is this: it can be tempting to make a
170change (which may bring big improvements) which causes something to break
171for existing users. This kind of change is called a "regression," and
172regressions have become most unwelcome in the mainline kernel. With few
173exceptions, changes which cause regressions will be backed out if the
174regression cannot be fixed in a timely manner. Far better to avoid the
175regression in the first place.
176
177It is often argued that a regression can be justified if it causes things
178to work for more people than it creates problems for. Why not make a
179change if it brings new functionality to ten systems for each one it
180breaks? The best answer to this question was expressed by Linus in July,
1812007:
182
183 So we don't fix bugs by introducing new problems. That way lies
184 madness, and nobody ever knows if you actually make any real
185 progress at all. Is it two steps forwards, one step back, or one
186 step forward and two steps back?
187
188(http://lwn.net/Articles/243460/).
189
190An especially unwelcome type of regression is any sort of change to the
191user-space ABI. Once an interface has been exported to user space, it must
192be supported indefinitely. This fact makes the creation of user-space
193interfaces particularly challenging: since they cannot be changed in
194incompatible ways, they must be done right the first time. For this
195reason, a great deal of thought, clear documentation, and wide review for
196user-space interfaces is always required.
197
198
199
2004.2: CODE CHECKING TOOLS
201
202For now, at least, the writing of error-free code remains an ideal that few
203of us can reach. What we can hope to do, though, is to catch and fix as
204many of those errors as possible before our code goes into the mainline
205kernel. To that end, the kernel developers have put together an impressive
206array of tools which can catch a wide variety of obscure problems in an
207automated way. Any problem caught by the computer is a problem which will
208not afflict a user later on, so it stands to reason that the automated
209tools should be used whenever possible.
210
211The first step is simply to heed the warnings produced by the compiler.
212Contemporary versions of gcc can detect (and warn about) a large number of
213potential errors. Quite often, these warnings point to real problems.
214Code submitted for review should, as a rule, not produce any compiler
215warnings. When silencing warnings, take care to understand the real cause
216and try to avoid "fixes" which make the warning go away without addressing
217its cause.
218
219Note that not all compiler warnings are enabled by default. Build the
220kernel with "make EXTRA_CFLAGS=-W" to get the full set.
221
222The kernel provides several configuration options which turn on debugging
223features; most of these are found in the "kernel hacking" submenu. Several
224of these options should be turned on for any kernel used for development or
225testing purposes. In particular, you should turn on:
226
227 - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an
228 extra set of warnings for problems like the use of deprecated interfaces
229 or ignoring an important return value from a function. The output
230 generated by these warnings can be verbose, but one need not worry about
231 warnings from other parts of the kernel.
232
233 - DEBUG_OBJECTS will add code to track the lifetime of various objects
234 created by the kernel and warn when things are done out of order. If
235 you are adding a subsystem which creates (and exports) complex objects
236 of its own, consider adding support for the object debugging
237 infrastructure.
238
239 - DEBUG_SLAB can find a variety of memory allocation and use errors; it
240 should be used on most development kernels.
241
242 - DEBUG_SPINLOCK, DEBUG_SPINLOCK_SLEEP, and DEBUG_MUTEXES will find a
243 number of common locking errors.
244
245There are quite a few other debugging options, some of which will be
246discussed below. Some of them have a significant performance impact and
247should not be used all of the time. But some time spent learning the
248available options will likely be paid back many times over in short order.
249
250One of the heavier debugging tools is the locking checker, or "lockdep."
251This tool will track the acquisition and release of every lock (spinlock or
252mutex) in the system, the order in which locks are acquired relative to
253each other, the current interrupt environment, and more. It can then
254ensure that locks are always acquired in the same order, that the same
255interrupt assumptions apply in all situations, and so on. In other words,
256lockdep can find a number of scenarios in which the system could, on rare
257occasion, deadlock. This kind of problem can be painful (for both
258developers and users) in a deployed system; lockdep allows them to be found
259in an automated manner ahead of time. Code with any sort of non-trivial
260locking should be run with lockdep enabled before being submitted for
261inclusion.
262
263As a diligent kernel programmer, you will, beyond doubt, check the return
264status of any operation (such as a memory allocation) which can fail. The
265fact of the matter, though, is that the resulting failure recovery paths
266are, probably, completely untested. Untested code tends to be broken code;
267you could be much more confident of your code if all those error-handling
268paths had been exercised a few times.
269
270The kernel provides a fault injection framework which can do exactly that,
271especially where memory allocations are involved. With fault injection
272enabled, a configurable percentage of memory allocations will be made to
273fail; these failures can be restricted to a specific range of code.
274Running with fault injection enabled allows the programmer to see how the
275code responds when things go badly. See
276Documentation/fault-injection/fault-injection.text for more information on
277how to use this facility.
278
279Other kinds of errors can be found with the "sparse" static analysis tool.
280With sparse, the programmer can be warned about confusion between
281user-space and kernel-space addresses, mixture of big-endian and
282small-endian quantities, the passing of integer values where a set of bit
283flags is expected, and so on. Sparse must be installed separately (it can
284be found at http://www.kernel.org/pub/software/devel/sparse/ if your
285distributor does not package it); it can then be run on the code by adding
286"C=1" to your make command.
287
288Other kinds of portability errors are best found by compiling your code for
289other architectures. If you do not happen to have an S/390 system or a
290Blackfin development board handy, you can still perform the compilation
291step. A large set of cross compilers for x86 systems can be found at
292
293 http://www.kernel.org/pub/tools/crosstool/
294
295Some time spent installing and using these compilers will help avoid
296embarrassment later.
297
298
2994.3: DOCUMENTATION
300
301Documentation has often been more the exception than the rule with kernel
302development. Even so, adequate documentation will help to ease the merging
303of new code into the kernel, make life easier for other developers, and
304will be helpful for your users. In many cases, the addition of
305documentation has become essentially mandatory.
306
307The first piece of documentation for any patch is its associated
308changelog. Log entries should describe the problem being solved, the form
309of the solution, the people who worked on the patch, any relevant
310effects on performance, and anything else that might be needed to
311understand the patch.
312
313Any code which adds a new user-space interface - including new sysfs or
314/proc files - should include documentation of that interface which enables
315user-space developers to know what they are working with. See
316Documentation/ABI/README for a description of how this documentation should
317be formatted and what information needs to be provided.
318
319The file Documentation/kernel-parameters.txt describes all of the kernel's
320boot-time parameters. Any patch which adds new parameters should add the
321appropriate entries to this file.
322
323Any new configuration options must be accompanied by help text which
324clearly explains the options and when the user might want to select them.
325
326Internal API information for many subsystems is documented by way of
327specially-formatted comments; these comments can be extracted and formatted
328in a number of ways by the "kernel-doc" script. If you are working within
329a subsystem which has kerneldoc comments, you should maintain them and add
330them, as appropriate, for externally-available functions. Even in areas
331which have not been so documented, there is no harm in adding kerneldoc
332comments for the future; indeed, this can be a useful activity for
333beginning kernel developers. The format of these comments, along with some
334information on how to create kerneldoc templates can be found in the file
335Documentation/kernel-doc-nano-HOWTO.txt.
336
337Anybody who reads through a significant amount of existing kernel code will
338note that, often, comments are most notable by their absence. Once again,
339the expectations for new code are higher than they were in the past;
340merging uncommented code will be harder. That said, there is little desire
341for verbosely-commented code. The code should, itself, be readable, with
342comments explaining the more subtle aspects.
343
344Certain things should always be commented. Uses of memory barriers should
345be accompanied by a line explaining why the barrier is necessary. The
346locking rules for data structures generally need to be explained somewhere.
347Major data structures need comprehensive documentation in general.
348Non-obvious dependencies between separate bits of code should be pointed
349out. Anything which might tempt a code janitor to make an incorrect
350"cleanup" needs a comment saying why it is done the way it is. And so on.
351
352
3534.4: INTERNAL API CHANGES
354
355The binary interface provided by the kernel to user space cannot be broken
356except under the most severe circumstances. The kernel's internal
357programming interfaces, instead, are highly fluid and can be changed when
358the need arises. If you find yourself having to work around a kernel API,
359or simply not using a specific functionality because it does not meet your
360needs, that may be a sign that the API needs to change. As a kernel
361developer, you are empowered to make such changes.
362
363There are, of course, some catches. API changes can be made, but they need
364to be well justified. So any patch making an internal API change should be
365accompanied by a description of what the change is and why it is
366necessary. This kind of change should also be broken out into a separate
367patch, rather than buried within a larger patch.
368
369The other catch is that a developer who changes an internal API is
370generally charged with the task of fixing any code within the kernel tree
371which is broken by the change. For a widely-used function, this duty can
372lead to literally hundreds or thousands of changes - many of which are
373likely to conflict with work being done by other developers. Needless to
374say, this can be a large job, so it is best to be sure that the
375justification is solid.
376
377When making an incompatible API change, one should, whenever possible,
378ensure that code which has not been updated is caught by the compiler.
379This will help you to be sure that you have found all in-tree uses of that
380interface. It will also alert developers of out-of-tree code that there is
381a change that they need to respond to. Supporting out-of-tree code is not
382something that kernel developers need to be worried about, but we also do
383not have to make life harder for out-of-tree developers than it it needs to
384be.
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting
new file mode 100644
index 000000000000..dd48132a74dd
--- /dev/null
+++ b/Documentation/development-process/5.Posting
@@ -0,0 +1,278 @@
15: POSTING PATCHES
2
3Sooner or later, the time comes when your work is ready to be presented to
4the community for review and, eventually, inclusion into the mainline
5kernel. Unsurprisingly, the kernel development community has evolved a set
6of conventions and procedures which are used in the posting of patches;
7following them will make life much easier for everybody involved. This
8document will attempt to cover these expectations in reasonable detail;
9more information can also be found in the files SubmittingPatches,
10SubmittingDrivers, and SubmitChecklist in the kernel documentation
11directory.
12
13
145.1: WHEN TO POST
15
16There is a constant temptation to avoid posting patches before they are
17completely "ready." For simple patches, that is not a problem. If the
18work being done is complex, though, there is a lot to be gained by getting
19feedback from the community before the work is complete. So you should
20consider posting in-progress work, or even making a git tree available so
21that interested developers can catch up with your work at any time.
22
23When posting code which is not yet considered ready for inclusion, it is a
24good idea to say so in the posting itself. Also mention any major work
25which remains to be done and any known problems. Fewer people will look at
26patches which are known to be half-baked, but those who do will come in
27with the idea that they can help you drive the work in the right direction.
28
29
305.2: BEFORE CREATING PATCHES
31
32There are a number of things which should be done before you consider
33sending patches to the development community. These include:
34
35 - Test the code to the extent that you can. Make use of the kernel's
36 debugging tools, ensure that the kernel will build with all reasonable
37 combinations of configuration options, use cross-compilers to build for
38 different architectures, etc.
39
40 - Make sure your code is compliant with the kernel coding style
41 guidelines.
42
43 - Does your change have performance implications? If so, you should run
44 benchmarks showing what the impact (or benefit) of your change is; a
45 summary of the results should be included with the patch.
46
47 - Be sure that you have the right to post the code. If this work was done
48 for an employer, the employer likely has a right to the work and must be
49 agreeable with its release under the GPL.
50
51As a general rule, putting in some extra thought before posting code almost
52always pays back the effort in short order.
53
54
555.3: PATCH PREPARATION
56
57The preparation of patches for posting can be a surprising amount of work,
58but, once again, attempting to save time here is not generally advisable
59even in the short term.
60
61Patches must be prepared against a specific version of the kernel. As a
62general rule, a patch should be based on the current mainline as found in
63Linus's git tree. It may become necessary to make versions against -mm,
64linux-next, or a subsystem tree, though, to facilitate wider testing and
65review. Depending on the area of your patch and what is going on
66elsewhere, basing a patch against these other trees can require a
67significant amount of work resolving conflicts and dealing with API
68changes.
69
70Only the most simple changes should be formatted as a single patch;
71everything else should be made as a logical series of changes. Splitting
72up patches is a bit of an art; some developers spend a long time figuring
73out how to do it in the way that the community expects. There are a few
74rules of thumb, however, which can help considerably:
75
76 - The patch series you post will almost certainly not be the series of
77 changes found in your working revision control system. Instead, the
78 changes you have made need to be considered in their final form, then
79 split apart in ways which make sense. The developers are interested in
80 discrete, self-contained changes, not the path you took to get to those
81 changes.
82
83 - Each logically independent change should be formatted as a separate
84 patch. These changes can be small ("add a field to this structure") or
85 large (adding a significant new driver, for example), but they should be
86 conceptually small and amenable to a one-line description. Each patch
87 should make a specific change which can be reviewed on its own and
88 verified to do what it says it does.
89
90 - As a way of restating the guideline above: do not mix different types of
91 changes in the same patch. If a single patch fixes a critical security
92 bug, rearranges a few structures, and reformats the code, there is a
93 good chance that it will be passed over and the important fix will be
94 lost.
95
96 - Each patch should yield a kernel which builds and runs properly; if your
97 patch series is interrupted in the middle, the result should still be a
98 working kernel. Partial application of a patch series is a common
99 scenario when the "git bisect" tool is used to find regressions; if the
100 result is a broken kernel, you will make life harder for developers and
101 users who are engaging in the noble work of tracking down problems.
102
103 - Do not overdo it, though. One developer recently posted a set of edits
104 to a single file as 500 separate patches - an act which did not make him
105 the most popular person on the kernel mailing list. A single patch can
106 be reasonably large as long as it still contains a single *logical*
107 change.
108
109 - It can be tempting to add a whole new infrastructure with a series of
110 patches, but to leave that infrastructure unused until the final patch
111 in the series enables the whole thing. This temptation should be
112 avoided if possible; if that series adds regressions, bisection will
113 finger the last patch as the one which caused the problem, even though
114 the real bug is elsewhere. Whenever possible, a patch which adds new
115 code should make that code active immediately.
116
117Working to create the perfect patch series can be a frustrating process
118which takes quite a bit of time and thought after the "real work" has been
119done. When done properly, though, it is time well spent.
120
121
1225.4: PATCH FORMATTING
123
124So now you have a perfect series of patches for posting, but the work is
125not done quite yet. Each patch needs to be formatted into a message which
126quickly and clearly communicates its purpose to the rest of the world. To
127that end, each patch will be composed of the following:
128
129 - An optional "From" line naming the author of the patch. This line is
130 only necessary if you are passing on somebody else's patch via email,
131 but it never hurts to add it when in doubt.
132
133 - A one-line description of what the patch does. This message should be
134 enough for a reader who sees it with no other context to figure out the
135 scope of the patch; it is the line that will show up in the "short form"
136 changelogs. This message is usually formatted with the relevant
137 subsystem name first, followed by the purpose of the patch. For
138 example:
139
140 gpio: fix build on CONFIG_GPIO_SYSFS=n
141
142 - A blank line followed by a detailed description of the contents of the
143 patch. This description can be as long as is required; it should say
144 what the patch does and why it should be applied to the kernel.
145
146 - One or more tag lines, with, at a minimum, one Signed-off-by: line from
147 the author of the patch. Tags will be described in more detail below.
148
149The above three items should, normally, be the text used when committing
150the change to a revision control system. They are followed by:
151
152 - The patch itself, in the unified ("-u") patch format. Using the "-p"
153 option to diff will associate function names with changes, making the
154 resulting patch easier for others to read.
155
156You should avoid including changes to irrelevant files (those generated by
157the build process, for example, or editor backup files) in the patch. The
158file "dontdiff" in the Documentation directory can help in this regard;
159pass it to diff with the "-X" option.
160
161The tags mentioned above are used to describe how various developers have
162been associated with the development of this patch. They are described in
163detail in the SubmittingPatches document; what follows here is a brief
164summary. Each of these lines has the format:
165
166 tag: Full Name <email address> optional-other-stuff
167
168The tags in common use are:
169
170 - Signed-off-by: this is a developer's certification that he or she has
171 the right to submit the patch for inclusion into the kernel. It is an
172 agreement to the Developer's Certificate of Origin, the full text of
173 which can be found in Documentation/SubmittingPatches. Code without a
174 proper signoff cannot be merged into the mainline.
175
176 - Acked-by: indicates an agreement by another developer (often a
177 maintainer of the relevant code) that the patch is appropriate for
178 inclusion into the kernel.
179
180 - Tested-by: states that the named person has tested the patch and found
181 it to work.
182
183 - Reviewed-by: the named developer has reviewed the patch for correctness;
184 see the reviewer's statement in Documentation/SubmittingPatches for more
185 detail.
186
187 - Reported-by: names a user who reported a problem which is fixed by this
188 patch; this tag is used to give credit to the (often underappreciated)
189 people who test our code and let us know when things do not work
190 correctly.
191
192 - Cc: the named person received a copy of the patch and had the
193 opportunity to comment on it.
194
195Be careful in the addition of tags to your patches: only Cc: is appropriate
196for addition without the explicit permission of the person named.
197
198
1995.5: SENDING THE PATCH
200
201Before you mail your patches, there are a couple of other things you should
202take care of:
203
204 - Are you sure that your mailer will not corrupt the patches? Patches
205 which have had gratuitous white-space changes or line wrapping performed
206 by the mail client will not apply at the other end, and often will not
207 be examined in any detail. If there is any doubt at all, mail the patch
208 to yourself and convince yourself that it shows up intact.
209
210 Documentation/email-clients.txt has some helpful hints on making
211 specific mail clients work for sending patches.
212
213 - Are you sure your patch is free of silly mistakes? You should always
214 run patches through scripts/checkpatch.pl and address the complaints it
215 comes up with. Please bear in mind that checkpatch.pl, while being the
216 embodiment of a fair amount of thought about what kernel patches should
217 look like, is not smarter than you. If fixing a checkpatch.pl complaint
218 would make the code worse, don't do it.
219
220Patches should always be sent as plain text. Please do not send them as
221attachments; that makes it much harder for reviewers to quote sections of
222the patch in their replies. Instead, just put the patch directly into your
223message.
224
225When mailing patches, it is important to send copies to anybody who might
226be interested in it. Unlike some other projects, the kernel encourages
227people to err on the side of sending too many copies; don't assume that the
228relevant people will see your posting on the mailing lists. In particular,
229copies should go to:
230
231 - The maintainer(s) of the affected subsystem(s). As described earlier,
232 the MAINTAINERS file is the first place to look for these people.
233
234 - Other developers who have been working in the same area - especially
235 those who might be working there now. Using git to see who else has
236 modified the files you are working on can be helpful.
237
238 - If you are responding to a bug report or a feature request, copy the
239 original poster as well.
240
241 - Send a copy to the relevant mailing list, or, if nothing else applies,
242 the linux-kernel list.
243
244 - If you are fixing a bug, think about whether the fix should go into the
245 next stable update. If so, stable@kernel.org should get a copy of the
246 patch. Also add a "Cc: stable@kernel.org" to the tags within the patch
247 itself; that will cause the stable team to get a notification when your
248 fix goes into the mainline.
249
250When selecting recipients for a patch, it is good to have an idea of who
251you think will eventually accept the patch and get it merged. While it
252is possible to send patches directly to Linus Torvalds and have him merge
253them, things are not normally done that way. Linus is busy, and there are
254subsystem maintainers who watch over specific parts of the kernel. Usually
255you will be wanting that maintainer to merge your patches. If there is no
256obvious maintainer, Andrew Morton is often the patch target of last resort.
257
258Patches need good subject lines. The canonical format for a patch line is
259something like:
260
261 [PATCH nn/mm] subsys: one-line description of the patch
262
263where "nn" is the ordinal number of the patch, "mm" is the total number of
264patches in the series, and "subsys" is the name of the affected subsystem.
265Clearly, nn/mm can be omitted for a single, standalone patch.
266
267If you have a significant series of patches, it is customary to send an
268introductory description as part zero. This convention is not universally
269followed though; if you use it, remember that information in the
270introduction does not make it into the kernel changelogs. So please ensure
271that the patches, themselves, have complete changelog information.
272
273In general, the second and following parts of a multi-part patch should be
274sent as a reply to the first part so that they all thread together at the
275receiving end. Tools like git and quilt have commands to mail out a set of
276patches with the proper threading. If you have a long series, though, and
277are using git, please provide the --no-chain-reply-to option to avoid
278creating exceptionally deep nesting.
diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough
new file mode 100644
index 000000000000..a8fba3d83a85
--- /dev/null
+++ b/Documentation/development-process/6.Followthrough
@@ -0,0 +1,202 @@
16: FOLLOWTHROUGH
2
3At this point, you have followed the guidelines given so far and, with the
4addition of your own engineering skills, have posted a perfect series of
5patches. One of the biggest mistakes that even experienced kernel
6developers can make is to conclude that their work is now done. In truth,
7posting patches indicates a transition into the next stage of the process,
8with, possibly, quite a bit of work yet to be done.
9
10It is a rare patch which is so good at its first posting that there is no
11room for improvement. The kernel development process recognizes this fact,
12and, as a result, is heavily oriented toward the improvement of posted
13code. You, as the author of that code, will be expected to work with the
14kernel community to ensure that your code is up to the kernel's quality
15standards. A failure to participate in this process is quite likely to
16prevent the inclusion of your patches into the mainline.
17
18
196.1: WORKING WITH REVIEWERS
20
21A patch of any significance will result in a number of comments from other
22developers as they review the code. Working with reviewers can be, for
23many developers, the most intimidating part of the kernel development
24process. Life can be made much easier, though, if you keep a few things in
25mind:
26
27 - If you have explained your patch well, reviewers will understand its
28 value and why you went to the trouble of writing it. But that value
29 will not keep them from asking a fundamental question: what will it be
30 like to maintain a kernel with this code in it five or ten years later?
31 Many of the changes you may be asked to make - from coding style tweaks
32 to substantial rewrites - come from the understanding that Linux will
33 still be around and under development a decade from now.
34
35 - Code review is hard work, and it is a relatively thankless occupation;
36 people remember who wrote kernel code, but there is little lasting fame
37 for those who reviewed it. So reviewers can get grumpy, especially when
38 they see the same mistakes being made over and over again. If you get a
39 review which seems angry, insulting, or outright offensive, resist the
40 impulse to respond in kind. Code review is about the code, not about
41 the people, and code reviewers are not attacking you personally.
42
43 - Similarly, code reviewers are not trying to promote their employers'
44 agendas at the expense of your own. Kernel developers often expect to
45 be working on the kernel years from now, but they understand that their
46 employer could change. They truly are, almost without exception,
47 working toward the creation of the best kernel they can; they are not
48 trying to create discomfort for their employers' competitors.
49
50What all of this comes down to is that, when reviewers send you comments,
51you need to pay attention to the technical observations that they are
52making. Do not let their form of expression or your own pride keep that
53from happening. When you get review comments on a patch, take the time to
54understand what the reviewer is trying to say. If possible, fix the things
55that the reviewer is asking you to fix. And respond back to the reviewer:
56thank them, and describe how you will answer their questions.
57
58Note that you do not have to agree with every change suggested by
59reviewers. If you believe that the reviewer has misunderstood your code,
60explain what is really going on. If you have a technical objection to a
61suggested change, describe it and justify your solution to the problem. If
62your explanations make sense, the reviewer will accept them. Should your
63explanation not prove persuasive, though, especially if others start to
64agree with the reviewer, take some time to think things over again. It can
65be easy to become blinded by your own solution to a problem to the point
66that you don't realize that something is fundamentally wrong or, perhaps,
67you're not even solving the right problem.
68
69One fatal mistake is to ignore review comments in the hope that they will
70go away. They will not go away. If you repost code without having
71responded to the comments you got the time before, you're likely to find
72that your patches go nowhere.
73
74Speaking of reposting code: please bear in mind that reviewers are not
75going to remember all the details of the code you posted the last time
76around. So it is always a good idea to remind reviewers of previously
77raised issues and how you dealt with them; the patch changelog is a good
78place for this kind of information. Reviewers should not have to search
79through list archives to familiarize themselves with what was said last
80time; if you help them get a running start, they will be in a better mood
81when they revisit your code.
82
83What if you've tried to do everything right and things still aren't going
84anywhere? Most technical disagreements can be resolved through discussion,
85but there are times when somebody simply has to make a decision. If you
86honestly believe that this decision is going against you wrongly, you can
87always try appealing to a higher power. As of this writing, that higher
88power tends to be Andrew Morton. Andrew has a great deal of respect in the
89kernel development community; he can often unjam a situation which seems to
90be hopelessly blocked. Appealing to Andrew should not be done lightly,
91though, and not before all other alternatives have been explored. And bear
92in mind, of course, that he may not agree with you either.
93
94
956.2: WHAT HAPPENS NEXT
96
97If a patch is considered to be a good thing to add to the kernel, and once
98most of the review issues have been resolved, the next step is usually
99entry into a subsystem maintainer's tree. How that works varies from one
100subsystem to the next; each maintainer has his or her own way of doing
101things. In particular, there may be more than one tree - one, perhaps,
102dedicated to patches planned for the next merge window, and another for
103longer-term work.
104
105For patches applying to areas for which there is no obvious subsystem tree
106(memory management patches, for example), the default tree often ends up
107being -mm. Patches which affect multiple subsystems can also end up going
108through the -mm tree.
109
110Inclusion into a subsystem tree can bring a higher level of visibility to a
111patch. Now other developers working with that tree will get the patch by
112default. Subsystem trees typically feed into -mm and linux-next as well,
113making their contents visible to the development community as a whole. At
114this point, there's a good chance that you will get more comments from a
115new set of reviewers; these comments need to be answered as in the previous
116round.
117
118What may also happen at this point, depending on the nature of your patch,
119is that conflicts with work being done by others turn up. In the worst
120case, heavy patch conflicts can result in some work being put on the back
121burner so that the remaining patches can be worked into shape and merged.
122Other times, conflict resolution will involve working with the other
123developers and, possibly, moving some patches between trees to ensure that
124everything applies cleanly. This work can be a pain, but count your
125blessings: before the advent of the linux-next tree, these conflicts often
126only turned up during the merge window and had to be addressed in a hurry.
127Now they can be resolved at leisure, before the merge window opens.
128
129Some day, if all goes well, you'll log on and see that your patch has been
130merged into the mainline kernel. Congratulations! Once the celebration is
131complete (and you have added yourself to the MAINTAINERS file), though, it
132is worth remembering an important little fact: the job still is not done.
133Merging into the mainline brings its own challenges.
134
135To begin with, the visibility of your patch has increased yet again. There
136may be a new round of comments from developers who had not been aware of
137the patch before. It may be tempting to ignore them, since there is no
138longer any question of your code being merged. Resist that temptation,
139though; you still need to be responsive to developers who have questions or
140suggestions.
141
142More importantly, though: inclusion into the mainline puts your code into
143the hands of a much larger group of testers. Even if you have contributed
144a driver for hardware which is not yet available, you will be surprised by
145how many people will build your code into their kernels. And, of course,
146where there are testers, there will be bug reports.
147
148The worst sort of bug reports are regressions. If your patch causes a
149regression, you'll find an uncomfortable number of eyes upon you;
150regressions need to be fixed as soon as possible. If you are unwilling or
151unable to fix the regression (and nobody else does it for you), your patch
152will almost certainly be removed during the stabilization period. Beyond
153negating all of the work you have done to get your patch into the mainline,
154having a patch pulled as the result of a failure to fix a regression could
155well make it harder for you to get work merged in the future.
156
157After any regressions have been dealt with, there may be other, ordinary
158bugs to deal with. The stabilization period is your best opportunity to
159fix these bugs and ensure that your code's debut in a mainline kernel
160release is as solid as possible. So, please, answer bug reports, and fix
161the problems if at all possible. That's what the stabilization period is
162for; you can start creating cool new patches once any problems with the old
163ones have been taken care of.
164
165And don't forget that there are other milestones which may also create bug
166reports: the next mainline stable release, when prominent distributors pick
167up a version of the kernel containing your patch, etc. Continuing to
168respond to these reports is a matter of basic pride in your work. If that
169is insufficient motivation, though, it's also worth considering that the
170development community remembers developers who lose interest in their code
171after it's merged. The next time you post a patch, they will be evaluating
172it with the assumption that you will not be around to maintain it
173afterward.
174
175
1766.3: OTHER THINGS THAT CAN HAPPEN
177
178One day, you may open your mail client and see that somebody has mailed you
179a patch to your code. That is one of the advantages of having your code
180out there in the open, after all. If you agree with the patch, you can
181either forward it on to the subsystem maintainer (be sure to include a
182proper From: line so that the attribution is correct, and add a signoff of
183your own), or send an Acked-by: response back and let the original poster
184send it upward.
185
186If you disagree with the patch, send a polite response explaining why. If
187possible, tell the author what changes need to be made to make the patch
188acceptable to you. There is a certain resistance to merging patches which
189are opposed by the author and maintainer of the code, but it only goes so
190far. If you are seen as needlessly blocking good work, those patches will
191eventually flow around you and get into the mainline anyway. In the Linux
192kernel, nobody has absolute veto power over any code. Except maybe Linus.
193
194On very rare occasion, you may see something completely different: another
195developer posts a different solution to your problem. At that point,
196chances are that one of the two patches will not be merged, and "mine was
197here first" is not considered to be a compelling technical argument. If
198somebody else's patch displaces yours and gets into the mainline, there is
199really only one way to respond: be pleased that your problem got solved and
200get on with your work. Having one's work shoved aside in this manner can
201be hurtful and discouraging, but the community will remember your reaction
202long after they have forgotten whose patch actually got merged.
diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics
new file mode 100644
index 000000000000..a2cf74093aa1
--- /dev/null
+++ b/Documentation/development-process/7.AdvancedTopics
@@ -0,0 +1,173 @@
17: ADVANCED TOPICS
2
3At this point, hopefully, you have a handle on how the development process
4works. There is still more to learn, however! This section will cover a
5number of topics which can be helpful for developers wanting to become a
6regular part of the Linux kernel development process.
7
87.1: MANAGING PATCHES WITH GIT
9
10The use of distributed version control for the kernel began in early 2002,
11when Linus first started playing with the proprietary BitKeeper
12application. While BitKeeper was controversial, the approach to software
13version management it embodied most certainly was not. Distributed version
14control enabled an immediate acceleration of the kernel development
15project. In current times, there are several free alternatives to
16BitKeeper. For better or for worse, the kernel project has settled on git
17as its tool of choice.
18
19Managing patches with git can make life much easier for the developer,
20especially as the volume of those patches grows. Git also has its rough
21edges and poses certain hazards; it is a young and powerful tool which is
22still being civilized by its developers. This document will not attempt to
23teach the reader how to use git; that would be sufficient material for a
24long document in its own right. Instead, the focus here will be on how git
25fits into the kernel development process in particular. Developers who
26wish to come up to speed with git will find more information at:
27
28 http://git.or.cz/
29
30 http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
31
32and on various tutorials found on the web.
33
34The first order of business is to read the above sites and get a solid
35understanding of how git works before trying to use it to make patches
36available to others. A git-using developer should be able to obtain a copy
37of the mainline repository, explore the revision history, commit changes to
38the tree, use branches, etc. An understanding of git's tools for the
39rewriting of history (such as rebase) is also useful. Git comes with its
40own terminology and concepts; a new user of git should know about refs,
41remote branches, the index, fast-forward merges, pushes and pulls, detached
42heads, etc. It can all be a little intimidating at the outset, but the
43concepts are not that hard to grasp with a bit of study.
44
45Using git to generate patches for submission by email can be a good
46exercise while coming up to speed.
47
48When you are ready to start putting up git trees for others to look at, you
49will, of course, need a server that can be pulled from. Setting up such a
50server with git-daemon is relatively straightforward if you have a system
51which is accessible to the Internet. Otherwise, free, public hosting sites
52(Github, for example) are starting to appear on the net. Established
53developers can get an account on kernel.org, but those are not easy to come
54by; see http://kernel.org/faq/ for more information.
55
56The normal git workflow involves the use of a lot of branches. Each line
57of development can be separated into a separate "topic branch" and
58maintained independently. Branches in git are cheap, there is no reason to
59not make free use of them. And, in any case, you should not do your
60development in any branch which you intend to ask others to pull from.
61Publicly-available branches should be created with care; merge in patches
62from development branches when they are in complete form and ready to go -
63not before.
64
65Git provides some powerful tools which can allow you to rewrite your
66development history. An inconvenient patch (one which breaks bisection,
67say, or which has some other sort of obvious bug) can be fixed in place or
68made to disappear from the history entirely. A patch series can be
69rewritten as if it had been written on top of today's mainline, even though
70you have been working on it for months. Changes can be transparently
71shifted from one branch to another. And so on. Judicious use of git's
72ability to revise history can help in the creation of clean patch sets with
73fewer problems.
74
75Excessive use of this capability can lead to other problems, though, beyond
76a simple obsession for the creation of the perfect project history.
77Rewriting history will rewrite the changes contained in that history,
78turning a tested (hopefully) kernel tree into an untested one. But, beyond
79that, developers cannot easily collaborate if they do not have a shared
80view of the project history; if you rewrite history which other developers
81have pulled into their repositories, you will make life much more difficult
82for those developers. So a simple rule of thumb applies here: history
83which has been exported to others should generally be seen as immutable
84thereafter.
85
86So, once you push a set of changes to your publicly-available server, those
87changes should not be rewritten. Git will attempt to enforce this rule if
88you try to push changes which do not result in a fast-forward merge
89(i.e. changes which do not share the same history). It is possible to
90override this check, and there may be times when it is necessary to rewrite
91an exported tree. Moving changesets between trees to avoid conflicts in
92linux-next is one example. But such actions should be rare. This is one
93of the reasons why development should be done in private branches (which
94can be rewritten if necessary) and only moved into public branches when
95it's in a reasonably advanced state.
96
97As the mainline (or other tree upon which a set of changes is based)
98advances, it is tempting to merge with that tree to stay on the leading
99edge. For a private branch, rebasing can be an easy way to keep up with
100another tree, but rebasing is not an option once a tree is exported to the
101world. Once that happens, a full merge must be done. Merging occasionally
102makes good sense, but overly frequent merges can clutter the history
103needlessly. Suggested technique in this case is to merge infrequently, and
104generally only at specific release points (such as a mainline -rc
105release). If you are nervous about specific changes, you can always
106perform test merges in a private branch. The git "rerere" tool can be
107useful in such situations; it remembers how merge conflicts were resolved
108so that you don't have to do the same work twice.
109
110One of the biggest recurring complaints about tools like git is this: the
111mass movement of patches from one repository to another makes it easy to
112slip in ill-advised changes which go into the mainline below the review
113radar. Kernel developers tend to get unhappy when they see that kind of
114thing happening; putting up a git tree with unreviewed or off-topic patches
115can affect your ability to get trees pulled in the future. Quoting Linus:
116
117 You can send me patches, but for me to pull a git patch from you, I
118 need to know that you know what you're doing, and I need to be able
119 to trust things *without* then having to go and check every
120 individual change by hand.
121
122(http://lwn.net/Articles/224135/).
123
124To avoid this kind of situation, ensure that all patches within a given
125branch stick closely to the associated topic; a "driver fixes" branch
126should not be making changes to the core memory management code. And, most
127importantly, do not use a git tree to bypass the review process. Post an
128occasional summary of the tree to the relevant list, and, when the time is
129right, request that the tree be included in linux-next.
130
131If and when others start to send patches for inclusion into your tree,
132don't forget to review them. Also ensure that you maintain the correct
133authorship information; the git "am" tool does its best in this regard, but
134you may have to add a "From:" line to the patch if it has been relayed to
135you via a third party.
136
137When requesting a pull, be sure to give all the relevant information: where
138your tree is, what branch to pull, and what changes will result from the
139pull. The git request-pull command can be helpful in this regard; it will
140format the request as other developers expect, and will also check to be
141sure that you have remembered to push those changes to the public server.
142
143
1447.2: REVIEWING PATCHES
145
146Some readers will certainly object to putting this section with "advanced
147topics" on the grounds that even beginning kernel developers should be
148reviewing patches. It is certainly true that there is no better way to
149learn how to program in the kernel environment than by looking at code
150posted by others. In addition, reviewers are forever in short supply; by
151looking at code you can make a significant contribution to the process as a
152whole.
153
154Reviewing code can be an intimidating prospect, especially for a new kernel
155developer who may well feel nervous about questioning code - in public -
156which has been posted by those with more experience. Even code written by
157the most experienced developers can be improved, though. Perhaps the best
158piece of advice for reviewers (all reviewers) is this: phrase review
159comments as questions rather than criticisms. Asking "how does the lock
160get released in this path?" will always work better than stating "the
161locking here is wrong."
162
163Different developers will review code from different points of view. Some
164are mostly concerned with coding style and whether code lines have trailing
165white space. Others will focus primarily on whether the change implemented
166by the patch as a whole is a good thing for the kernel or not. Yet others
167will check for problematic locking, excessive stack usage, possible
168security issues, duplication of code found elsewhere, adequate
169documentation, adverse effects on performance, user-space ABI changes, etc.
170All types of review, if they lead to better code going into the kernel, are
171welcome and worthwhile.
172
173
diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion
new file mode 100644
index 000000000000..1990ab4b4949
--- /dev/null
+++ b/Documentation/development-process/8.Conclusion
@@ -0,0 +1,74 @@
18: FOR MORE INFORMATION
2
3There are numerous sources of information on Linux kernel development and
4related topics. First among those will always be the Documentation
5directory found in the kernel source distribution. The top-level HOWTO
6file is an important starting point; SubmittingPatches and
7SubmittingDrivers are also something which all kernel developers should
8read. Many internal kernel APIs are documented using the kerneldoc
9mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those
10documents in HTML or PDF format (though the version of TeX shipped by some
11distributions runs into internal limits and fails to process the documents
12properly).
13
14Various web sites discuss kernel development at all levels of detail. Your
15author would like to humbly suggest http://lwn.net/ as a source;
16information on many specific kernel topics can be found via the LWN kernel
17index at:
18
19 http://lwn.net/Kernel/Index/
20
21Beyond that, a valuable resource for kernel developers is:
22
23 http://kernelnewbies.org/
24
25Information about the linux-next tree gathers at:
26
27 http://linux.f-seidel.de/linux-next/pmwiki/
28
29And, of course, one should not forget http://kernel.org/, the definitive
30location for kernel release information.
31
32There are a number of books on kernel development:
33
34 Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro
35 Rubini, and Greg Kroah-Hartman). Online at
36 http://lwn.net/Kernel/LDD3/.
37
38 Linux Kernel Development (Robert Love).
39
40 Understanding the Linux Kernel (Daniel Bovet and Marco Cesati).
41
42All of these books suffer from a common fault, though: they tend to be
43somewhat obsolete by the time they hit the shelves, and they have been on
44the shelves for a while now. Still, there is quite a bit of good
45information to be found there.
46
47Documentation for git can be found at:
48
49 http://www.kernel.org/pub/software/scm/git/docs/
50
51 http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
52
53
549: CONCLUSION
55
56Congratulations to anybody who has made it through this long-winded
57document. Hopefully it has provided a helpful understanding of how the
58Linux kernel is developed and how you can participate in that process.
59
60In the end, it's the participation that matters. Any open source software
61project is no more than the sum of what its contributors put into it. The
62Linux kernel has progressed as quickly and as well as it has because it has
63been helped by an impressively large group of developers, all of whom are
64working to make it better. The kernel is a premier example of what can be
65done when thousands of people work together toward a common goal.
66
67The kernel can always benefit from a larger developer base, though. There
68is always more work to do. But, just as importantly, most other
69participants in the Linux ecosystem can benefit through contributing to the
70kernel. Getting code into the mainline is the key to higher code quality,
71lower maintenance and distribution costs, a higher level of influence over
72the direction of kernel development, and more. It is a situation where
73everybody involved wins. Fire up your editor and come join us; you will be
74more than welcome.
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-17 23:04:01 -0500