[PATCH] x86_64 irq: Properly update vector_irq

[linux.git] / Documentation / kernel-docs.txt

       Index of Documentation for People Interested in Writing and/or
                                      
                      Understanding the Linux Kernel.
                                      
               Juan-Mariano de Goyeneche <[email protected]>
                                      
/*
 * 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://users.evitech.fi/~tk/rtos/writing_linux_device_d.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"