[net-next-2.6.git] / Documentation / kernel-docs.txt


       Index of Documentation for People Interested in Writing and/or
                                      
                      Understanding the Linux Kernel.
                                      
               Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
                                      
/*
 * The latest version of this document may be found at:
 *   http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
 */

   The need for a document like this one became apparent in the
   linux-kernel mailing list as the same questions, asking for pointers
   to information, appeared again and again.
   
   Fortunately, as more and more people get to GNU/Linux, more and more
   get interested in the Kernel. But reading the sources is not always
   enough. It is easy to understand the code, but miss the concepts, the
   philosophy and design decisions behind this code.
   
   Unfortunately, not many documents are available for beginners to
   start. And, even if they exist, there was no "well-known" place which
   kept track of them. These lines try to cover this lack. All documents
   available on line known by the author are listed, while some reference
   books are also mentioned.
   
   PLEASE, if you know any paper not listed here or write a new document,
   send me an e-mail, and I'll include a reference to it here. Any
   corrections, ideas or comments are also welcomed.
   
   The papers that follow are listed in no particular order. All are
   cataloged with the following fields: the document's "Title", the
   "Author"/s, the "URL" where they can be found, some "Keywords" helpful
   when searching for specific topics, and a brief "Description" of the
   Document.
   
   Enjoy!
   
     ON-LINE DOCS:
       
     * Title: "Linux Device Drivers, Third Edition"
       Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
       URL: http://lwn.net/Kernel/LDD3/
       Description: A 600-page book covering the (2.6.10) driver
       programming API and kernel hacking in general.  Available under the
       Creative Commons Attribution-ShareAlike 2.0 license.

     * Title: "The Linux Kernel"
       Author: David A. Rusling.
       URL: http://www.tldp.org/LDP/tlk/tlk.html
       Keywords: everything!, book.
       Description: On line, 200 pages book describing most aspects of
       the Linux Kernel. Probably, the first reference for beginners.
       Lots of illustrations explaining data structures use and
       relationships in the purest Richard W. Stevens' style. Contents:
       "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
       4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI,
       7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The
       File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules,
       13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
       Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
       General Public License, Glossary". In short: a must have.
       
     * Title: "The Linux Kernel Hackers' Guide"
       Author: Michael K.Johnson and others.
       URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
       Keywords: everything!
       Description: No more Postscript book-like version. Only HTML now.
       Many people have contributed. The interface is similar to web
       available mailing lists archives. You can find some articles and
       then some mails asking questions about them and/or complementing
       previous contributions. A little bit anarchic in this aspect, but
       with some valuable information in some cases.
       
     * Title: "Conceptual Architecture of the Linux Kernel"
       Author: Ivan T. Bowman.
       URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a1.html
       Keywords: conceptual software arquitecture, extracted design,
       reverse engineering, system structure.
       Description: Conceptual software arquitecture of the Linux kernel,
       automatically extracted from the source code. Very detailed. Good
       figures. Gives good overall kernel understanding.
       
     * Title: "Concrete Architecture of the Linux Kernel"
       Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
       URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a2.html
       Keywords: concrete arquitecture, extracted design, reverse
       engineering, system structure, dependencies.
       Description: Concrete arquitecture of the Linux kernel,
       automatically extracted from the source code. Very detailed. Good
       figures. Gives good overall kernel understanding. This papers
       focus on lower details than its predecessor (files, variables...).
       
     * Title: "Linux as a Case Study: Its Extracted Software
       Architecture"
       Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
       URL: http://plg.uwaterloo.ca/~itbowman/papers/linuxcase.html
       Keywords: software architecture, architecture recovery,
       redocumentation.
       Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
       1999. A mixture of the previous two documents from the same
       author.
       
     * Title: "Overview of the Virtual File System"
       Author: Richard Gooch.
       URL: http://www.atnf.csiro.au/~rgooch/linux/vfs.txt
       Keywords: VFS, File System, mounting filesystems, opening files,
       dentries, dcache.
       Description: Brief introduction to the Linux Virtual File System.
       What is it, how it works, operations taken when opening a file or
       mounting a file system and description of important data
       structures explaining the purpose of each of their entries.
       
     * Title: "The Linux RAID-1, 4, 5 Code"
       Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
       URL: http://www2.linuxjournal.com/lj-issues/issue44/2391.html
       Keywords: RAID, MD driver.
       Description: Linux Journal Kernel Korner article. Here is it's
       abstract: "A description of the implementation of the RAID-1,
       RAID-4 and RAID-5 personalities of the MD device driver in the
       Linux kernel, providing users with high performance and reliable,
       secondary-storage capability using software".
       
     * Title: "Dynamic Kernels: Modularized Device Drivers"
       Author: Alessandro Rubini.
       URL: http://www2.linuxjournal.com/lj-issues/issue23/1219.html
       Keywords: device driver, module, loading/unloading modules,
       allocating resources.
       Description: Linux Journal Kernel Korner article. Here is it's
       abstract: "This is the first of a series of four articles
       co-authored by Alessandro Rubini and Georg Zezchwitz which present
       a practical approach to writing Linux device drivers as kernel
       loadable modules. This installment presents an introduction to the
       topic, preparing the reader to understand next month's
       installment".
       
     * Title: "Dynamic Kernels: Discovery"
       Author: Alessandro Rubini.
       URL: http://www2.linuxjournal.com/lj-issues/issue24/1220.html
       Keywords: character driver, init_module, clean_up module,
       autodetection, mayor number, minor number, file operations,
       open(), close().
       Description: Linux Journal Kernel Korner article. Here is it's
       abstract: "This article, the second of four, introduces part of
       the actual code to create custom module implementing a character
       device driver. It describes the code for module initialization and
       cleanup, as well as the open() and close() system calls".
       
     * Title: "The Devil's in the Details"
       Author: Georg v. Zezschwitz and Alessandro Rubini.
       URL: http://www2.linuxjournal.com/lj-issues/issue25/1221.html
       Keywords: read(), write(), select(), ioctl(), blocking/non
       blocking mode, interrupt handler.
       Description: Linux Journal Kernel Korner article. Here is it's
       abstract: "This article, the third of four on writing character
       device drivers, introduces concepts of reading, writing, and using
       ioctl-calls".
       
     * Title: "Dissecting Interrupts and Browsing DMA"
       Author: Alessandro Rubini and Georg v. Zezschwitz.
       URL: http://www2.linuxjournal.com/lj-issues/issue26/1222.html
       Keywords: interrupts, irqs, DMA, bottom halves, task queues.
       Description: Linux Journal Kernel Korner article. Here is it's
       abstract: "This is the fourth in a series of articles about
       writing character device drivers as loadable kernel modules. This
       month, we further investigate the field of interrupt handling.
       Though it is conceptually simple, practical limitations and
       constraints make this an ``interesting'' part of device driver
       writing, and several different facilities have been provided for
       different situations. We also investigate the complex topic of
       DMA".
       
     * Title: "Device Drivers Concluded"
       Author: Georg v. Zezschwitz.
       URL: http://www2.linuxjournal.com/lj-issues/issue28/1287.html
       Keywords: address spaces, pages, pagination, page management,
       demand loading, swapping, memory protection, memory mapping, mmap,
       virtual memory areas (VMAs), vremap, PCI.
       Description: Finally, the above turned out into a five articles
       series. This latest one's introduction reads: "This is the last of
       five articles about character device drivers. In this final
       section, Georg deals with memory mapping devices, beginning with
       an overall description of the Linux memory management concepts".
       
     * Title: "Network Buffers And Memory Management"
       Author: Alan Cox.
       URL: http://www2.linuxjournal.com/lj-issues/issue30/1312.html
       Keywords: sk_buffs, network devices, protocol/link layer
       variables, network devices flags, transmit, receive,
       configuration, multicast.
       Description: Linux Journal Kernel Korner. Here is the abstract:
       "Writing a network device driver for Linux is fundamentally
       simple---most of the complexity (other than talking to the
       hardware) involves managing network packets in memory".
       
     * Title: "Writing Linux Device Drivers"
       Author: Michael K. Johnson.
       URL: http://people.redhat.com/johnsonm/devices.html
       Keywords: files, VFS, file operations, kernel interface, character
       vs block devices, I/O access, hardware interrupts, DMA, access to
       user memory, memory allocation, timers.
       Description: Introductory 50-minutes (sic) tutorial on writing
       device drivers. 12 pages written by the same author of the "Kernel
       Hackers' Guide" which give a very good overview of the topic.
       
     * Title: "The Venus kernel interface"
       Author: Peter J. Braam.
       URL:
       http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html
       Keywords: coda, filesystem, venus, cache manager.
       Description: "This document describes the communication between
       Venus and kernel level file system code needed for the operation
       of the Coda filesystem. This version document is meant to describe
       the current interface (version 1.0) as well as improvements we
       envisage".
       
     * Title: "Programming PCI-Devices under Linux"
       Author: Claus Schroeter.
       URL:
       ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps
       .gz
       Keywords: PCI, device, busmastering.
       Description: 6 pages tutorial on PCI programming under Linux.
       Gives the basic concepts on the architecture of the PCI subsystem,
       as long as basic functions and macros to read/write the devices
       and perform busmastering.
       
     * Title: "Writing Character Device Driver for Linux"
       Author: R. Baruch and C. Schroeter.
       URL:
       ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers
       .ps.gz
       Keywords: character device drivers, I/O, signals, DMA, accessing
       ports in user space, kernel environment.
       Description: 68 pages paper on writing character drivers. A little
       bit old (1.993, 1.994) although still useful.
       
     * Title: "Design and Implementation of the Second Extended
       Filesystem"
Commit	Line	Data
1da177e4 LT	1
	2	Index of Documentation for People Interested in Writing and/or
	3
	4	Understanding the Linux Kernel.
	5
	6	Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
	7
	8	/*
	9	* The latest version of this document may be found at:
	10	* http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
	11	*/
	12
	13	The need for a document like this one became apparent in the
	14	linux-kernel mailing list as the same questions, asking for pointers
	15	to information, appeared again and again.
	16
	17	Fortunately, as more and more people get to GNU/Linux, more and more
	18	get interested in the Kernel. But reading the sources is not always
	19	enough. It is easy to understand the code, but miss the concepts, the
	20	philosophy and design decisions behind this code.
	21
	22	Unfortunately, not many documents are available for beginners to
	23	start. And, even if they exist, there was no "well-known" place which
	24	kept track of them. These lines try to cover this lack. All documents
	25	available on line known by the author are listed, while some reference
	26	books are also mentioned.
	27
	28	PLEASE, if you know any paper not listed here or write a new document,
	29	send me an e-mail, and I'll include a reference to it here. Any
	30	corrections, ideas or comments are also welcomed.
	31
	32	The papers that follow are listed in no particular order. All are
	33	cataloged with the following fields: the document's "Title", the
	34	"Author"/s, the "URL" where they can be found, some "Keywords" helpful
	35	when searching for specific topics, and a brief "Description" of the
	36	Document.
	37
	38	Enjoy!
	39
	40	ON-LINE DOCS:
	41
	42	* Title: "Linux Device Drivers, Third Edition"
	43	Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
	44	URL: http://lwn.net/Kernel/LDD3/
	45	Description: A 600-page book covering the (2.6.10) driver
	46	programming API and kernel hacking in general. Available under the
	47	Creative Commons Attribution-ShareAlike 2.0 license.
	48
	49	* Title: "The Linux Kernel"
	50	Author: David A. Rusling.
	51	URL: http://www.tldp.org/LDP/tlk/tlk.html
	52	Keywords: everything!, book.
	53	Description: On line, 200 pages book describing most aspects of
	54	the Linux Kernel. Probably, the first reference for beginners.
	55	Lots of illustrations explaining data structures use and
	56	relationships in the purest Richard W. Stevens' style. Contents:
	57	"1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
	58	4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI,
	59	7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The
	60	File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules,
	61	13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
	62	Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
	63	General Public License, Glossary". In short: a must have.
	64
65	* Title: "The Linux Kernel Hackers' Guide"
66	Author: Michael K.Johnson and others.
67	URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
68	Keywords: everything!
69	Description: No more Postscript book-like version. Only HTML now.
70	Many people have contributed. The interface is similar to web
71	available mailing lists archives. You can find some articles and
72	then some mails asking questions about them and/or complementing
73	previous contributions. A little bit anarchic in this aspect, but
74	with some valuable information in some cases.
75
76	* Title: "Conceptual Architecture of the Linux Kernel"
77	Author: Ivan T. Bowman.
78	URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a1.html
79	Keywords: conceptual software arquitecture, extracted design,
80	reverse engineering, system structure.
81	Description: Conceptual software arquitecture of the Linux kernel,
82	automatically extracted from the source code. Very detailed. Good
83	figures. Gives good overall kernel understanding.
84
85	* Title: "Concrete Architecture of the Linux Kernel"
86	Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
87	URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a2.html
88	Keywords: concrete arquitecture, extracted design, reverse
89	engineering, system structure, dependencies.
90	Description: Concrete arquitecture of the Linux kernel,
91	automatically extracted from the source code. Very detailed. Good
92	figures. Gives good overall kernel understanding. This papers
93	focus on lower details than its predecessor (files, variables...).
94
95	* Title: "Linux as a Case Study: Its Extracted Software
96	Architecture"
97	Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
98	URL: http://plg.uwaterloo.ca/~itbowman/papers/linuxcase.html
99	Keywords: software architecture, architecture recovery,
100	redocumentation.
101	Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
102	1999. A mixture of the previous two documents from the same
103	author.
104
105	* Title: "Overview of the Virtual File System"
106	Author: Richard Gooch.
107	URL: http://www.atnf.csiro.au/~rgooch/linux/vfs.txt
108	Keywords: VFS, File System, mounting filesystems, opening files,
109	dentries, dcache.
110	Description: Brief introduction to the Linux Virtual File System.
111	What is it, how it works, operations taken when opening a file or
112	mounting a file system and description of important data
113	structures explaining the purpose of each of their entries.
114
115	* Title: "The Linux RAID-1, 4, 5 Code"
116	Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
117	URL: http://www2.linuxjournal.com/lj-issues/issue44/2391.html
118	Keywords: RAID, MD driver.
119	Description: Linux Journal Kernel Korner article. Here is it's
120	abstract: "A description of the implementation of the RAID-1,
121	RAID-4 and RAID-5 personalities of the MD device driver in the
122	Linux kernel, providing users with high performance and reliable,
123	secondary-storage capability using software".
124
125	* Title: "Dynamic Kernels: Modularized Device Drivers"
126	Author: Alessandro Rubini.
127	URL: http://www2.linuxjournal.com/lj-issues/issue23/1219.html
128	Keywords: device driver, module, loading/unloading modules,
129	allocating resources.
130	Description: Linux Journal Kernel Korner article. Here is it's
131	abstract: "This is the first of a series of four articles
132	co-authored by Alessandro Rubini and Georg Zezchwitz which present
133	a practical approach to writing Linux device drivers as kernel
134	loadable modules. This installment presents an introduction to the
135	topic, preparing the reader to understand next month's
136	installment".
137
138	* Title: "Dynamic Kernels: Discovery"
139	Author: Alessandro Rubini.
140	URL: http://www2.linuxjournal.com/lj-issues/issue24/1220.html
141	Keywords: character driver, init_module, clean_up module,
142	autodetection, mayor number, minor number, file operations,
143	open(), close().
144	Description: Linux Journal Kernel Korner article. Here is it's
145	abstract: "This article, the second of four, introduces part of
146	the actual code to create custom module implementing a character
147	device driver. It describes the code for module initialization and
148	cleanup, as well as the open() and close() system calls".
149
150	* Title: "The Devil's in the Details"
151	Author: Georg v. Zezschwitz and Alessandro Rubini.
152	URL: http://www2.linuxjournal.com/lj-issues/issue25/1221.html
153	Keywords: read(), write(), select(), ioctl(), blocking/non
154	blocking mode, interrupt handler.
155	Description: Linux Journal Kernel Korner article. Here is it's
156	abstract: "This article, the third of four on writing character
157	device drivers, introduces concepts of reading, writing, and using
158	ioctl-calls".
159
160	* Title: "Dissecting Interrupts and Browsing DMA"
161	Author: Alessandro Rubini and Georg v. Zezschwitz.
162	URL: http://www2.linuxjournal.com/lj-issues/issue26/1222.html
163	Keywords: interrupts, irqs, DMA, bottom halves, task queues.
164	Description: Linux Journal Kernel Korner article. Here is it's
165	abstract: "This is the fourth in a series of articles about
166	writing character device drivers as loadable kernel modules. This
167	month, we further investigate the field of interrupt handling.
168	Though it is conceptually simple, practical limitations and
169	constraints make this an ``interesting'' part of device driver
170	writing, and several different facilities have been provided for
171	different situations. We also investigate the complex topic of
172	DMA".
173
174	* Title: "Device Drivers Concluded"
175	Author: Georg v. Zezschwitz.
176	URL: http://www2.linuxjournal.com/lj-issues/issue28/1287.html
177	Keywords: address spaces, pages, pagination, page management,
178	demand loading, swapping, memory protection, memory mapping, mmap,
179	virtual memory areas (VMAs), vremap, PCI.
180	Description: Finally, the above turned out into a five articles
181	series. This latest one's introduction reads: "This is the last of
182	five articles about character device drivers. In this final
183	section, Georg deals with memory mapping devices, beginning with
184	an overall description of the Linux memory management concepts".
185
186	* Title: "Network Buffers And Memory Management"
187	Author: Alan Cox.
188	URL: http://www2.linuxjournal.com/lj-issues/issue30/1312.html
189	Keywords: sk_buffs, network devices, protocol/link layer
190	variables, network devices flags, transmit, receive,
191	configuration, multicast.
192	Description: Linux Journal Kernel Korner. Here is the abstract:
193	"Writing a network device driver for Linux is fundamentally
194	simple---most of the complexity (other than talking to the
195	hardware) involves managing network packets in memory".
196
197	* Title: "Writing Linux Device Drivers"
198	Author: Michael K. Johnson.
199	URL: http://people.redhat.com/johnsonm/devices.html
200	Keywords: files, VFS, file operations, kernel interface, character
201	vs block devices, I/O access, hardware interrupts, DMA, access to
202	user memory, memory allocation, timers.
203	Description: Introductory 50-minutes (sic) tutorial on writing
204	device drivers. 12 pages written by the same author of the "Kernel
205	Hackers' Guide" which give a very good overview of the topic.
206
207	* Title: "The Venus kernel interface"
208	Author: Peter J. Braam.
209	URL:
210	http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html
211	Keywords: coda, filesystem, venus, cache manager.
212	Description: "This document describes the communication between
213	Venus and kernel level file system code needed for the operation
214	of the Coda filesystem. This version document is meant to describe
215	the current interface (version 1.0) as well as improvements we
216	envisage".
217
218	* Title: "Programming PCI-Devices under Linux"
219	Author: Claus Schroeter.
220	URL:
221	ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps
222	.gz
223	Keywords: PCI, device, busmastering.
224	Description: 6 pages tutorial on PCI programming under Linux.
225	Gives the basic concepts on the architecture of the PCI subsystem,
226	as long as basic functions and macros to read/write the devices
227	and perform busmastering.
228
229	* Title: "Writing Character Device Driver for Linux"
230	Author: R. Baruch and C. Schroeter.
231	URL:
232	ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers
233	.ps.gz
234	Keywords: character device drivers, I/O, signals, DMA, accessing
235	ports in user space, kernel environment.
236	Description: 68 pages paper on writing character drivers. A little
237	bit old (1.993, 1.994) although still useful.
238
239	* Title: "Design and Implementation of the Second Extended
240	Filesystem"
241