Skip to content

Commit

Permalink
[PATCH] DocBook: changes and extensions to the kernel documentation
Browse files Browse the repository at this point in the history 
I have recompiled Linux kernel 2.6.11.5 documentation for me and our
university students again.  The documentation could be extended for more
sources which are equipped by structured comments for recent 2.6 kernels.  I
have tried to proceed with that task.  I have done that more times from 2.6.0
time and it gets boring to do same changes again and again.  Linux kernel
compiles after changes for i386 and ARM targets.  I have added references to
some more files into kernel-api book, I have added some section names as well.
 So please, check that changes do not break something and that categories are
not too much skewed.

I have changed kernel-doc to accept "fastcall" and "asmlinkage" words reserved
by kernel convention.  Most of the other changes are modifications in the
comments to make kernel-doc happy, accept some parameters description and do
not bail out on errors.  Changed <pid> to @pid in the description, moved some
#ifdef before comments to correct function to comments bindings, etc.

You can see result of the modified documentation build at
  http://cmp.felk.cvut.cz/~pisa/linux/lkdb-2.6.11.tar.gz

Some more sources are ready to be included into kernel-doc generated
documentation.  Sources has been added into kernel-api for now.  Some more
section names added and probably some more chaos introduced as result of quick
cleanup work.

Signed-off-by: Pavel Pisa <[email protected]>
Signed-off-by: Martin Waitz <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>
  • Loading branch information
@ppisa
ppisa authored and Linus Torvalds committed May 1, 2005
1 parent 333f981 commit 4dc3b16
Show file tree
Hide file tree
Showing 16 changed files with 320 additions and 148 deletions.
186 changes: 179 additions & 7 deletions Documentation/DocBook/kernel-api.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,33 @@
!Iinclude/asm-i386/unaligned.h
</sect1>

<!-- FIXME:
kernel/sched.c has no docs, which stuffs up the sgml. Comment
out until somebody adds docs. KAO
<sect1><title>Delaying, scheduling, and timer routines</title>
X!Ekernel/sched.c
!Iinclude/linux/sched.h
!Ekernel/sched.c
!Ekernel/timer.c
</sect1>
KAO -->
<sect1><title>Internal Functions</title>
!Ikernel/exit.c
!Ikernel/signal.c
</sect1>

<sect1><title>Kernel objects manipulation</title>
<!--
X!Iinclude/linux/kobject.h
-->
!Elib/kobject.c
</sect1>

<sect1><title>Kernel utility functions</title>
!Iinclude/linux/kernel.h
<!-- This needs to clean up to make kernel-doc happy
X!Ekernel/printk.c
-->
!Ekernel/panic.c
!Ekernel/sys.c
!Ekernel/rcupdate.c
</sect1>

</chapter>

<chapter id="adt">
Expand All @@ -81,7 +101,9 @@ KAO -->
!Elib/vsprintf.c
</sect1>
<sect1><title>String Manipulation</title>
!Ilib/string.c
<!-- All functions are exported at now
X!Ilib/string.c
-->
!Elib/string.c
</sect1>
<sect1><title>Bit Operations</title>
Expand All @@ -98,6 +120,25 @@ KAO -->
!Iinclude/asm-i386/uaccess.h
!Iarch/i386/lib/usercopy.c
</sect1>
<sect1><title>More Memory Management Functions</title>
!Iinclude/linux/rmap.h
!Emm/readahead.c
!Emm/filemap.c
!Emm/memory.c
!Emm/vmalloc.c
!Emm/mempool.c
!Emm/page-writeback.c
!Emm/truncate.c
</sect1>
</chapter>


<chapter id="ipc">
<title>Kernel IPC facilities</title>

<sect1><title>IPC utilities</title>
!Iipc/util.c
</sect1>
</chapter>

<chapter id="kfifo">
Expand All @@ -114,6 +155,10 @@ KAO -->
<sect1><title>sysctl interface</title>
!Ekernel/sysctl.c
</sect1>

<sect1><title>proc filesystem interface</title>
!Ifs/proc/base.c
</sect1>
</chapter>

<chapter id="debugfs">
Expand All @@ -127,6 +172,10 @@ KAO -->

<chapter id="vfs">
<title>The Linux VFS</title>
<sect1><title>The Filesystem types</title>
!Iinclude/linux/fs.h
!Einclude/linux/fs.h
</sect1>
<sect1><title>The Directory Cache</title>
!Efs/dcache.c
!Iinclude/linux/dcache.h
Expand All @@ -142,13 +191,31 @@ KAO -->
!Efs/locks.c
!Ifs/locks.c
</sect1>
<sect1><title>Other Functions</title>
!Efs/mpage.c
!Efs/namei.c
!Efs/buffer.c
!Efs/bio.c
!Efs/seq_file.c
!Efs/filesystems.c
!Efs/fs-writeback.c
!Efs/block_dev.c
</sect1>
</chapter>

<chapter id="netcore">
<title>Linux Networking</title>
<sect1><title>Networking Base Types</title>
!Iinclude/linux/net.h
</sect1>
<sect1><title>Socket Buffer Functions</title>
!Iinclude/linux/skbuff.h
!Iinclude/net/sock.h
!Enet/socket.c
!Enet/core/skbuff.c
!Enet/core/sock.c
!Enet/core/datagram.c
!Enet/core/stream.c
</sect1>
<sect1><title>Socket Filter</title>
!Enet/core/filter.c
Expand All @@ -158,6 +225,14 @@ KAO -->
!Enet/core/gen_stats.c
!Enet/core/gen_estimator.c
</sect1>
<sect1><title>SUN RPC subsystem</title>
<!-- The !D functionality is not perfect, garbage has to be protected by comments
!Dnet/sunrpc/sunrpc_syms.c
-->
!Enet/sunrpc/xdr.c
!Enet/sunrpc/svcsock.c
!Enet/sunrpc/sched.c
</sect1>
</chapter>

<chapter id="netdev">
Expand Down Expand Up @@ -194,11 +269,26 @@ X!Ekernel/module.c
!Iarch/i386/kernel/irq.c
</sect1>

<sect1><title>Resources Management</title>
!Ekernel/resource.c
</sect1>

<sect1><title>MTRR Handling</title>
!Earch/i386/kernel/cpu/mtrr/main.c
</sect1>
<sect1><title>PCI Support Library</title>
!Edrivers/pci/pci.c
!Edrivers/pci/pci-driver.c
!Edrivers/pci/remove.c
!Edrivers/pci/pci-acpi.c
<!-- kerneldoc does not understand to __devinit
X!Edrivers/pci/search.c
-->
!Edrivers/pci/msi.c
!Edrivers/pci/bus.c
!Edrivers/pci/hotplug.c
!Edrivers/pci/probe.c
!Edrivers/pci/rom.c
</sect1>
<sect1><title>PCI Hotplug Support Library</title>
!Edrivers/pci/hotplug/pci_hotplug_core.c
Expand All @@ -223,6 +313,14 @@ X!Earch/i386/kernel/mca.c
!Efs/devfs/base.c
</chapter>

<chapter id="sysfs">
<title>The Filesystem for Exporting Kernel Objects</title>
!Efs/sysfs/file.c
!Efs/sysfs/dir.c
!Efs/sysfs/symlink.c
!Efs/sysfs/bin.c
</chapter>

<chapter id="security">
<title>Security Framework</title>
!Esecurity/security.c
Expand All @@ -233,6 +331,61 @@ X!Earch/i386/kernel/mca.c
!Ekernel/power/pm.c
</chapter>

<chapter id="devdrivers">
<title>Device drivers infrastructure</title>
<sect1><title>Device Drivers Base</title>
<!--
X!Iinclude/linux/device.h
-->
!Edrivers/base/driver.c
!Edrivers/base/class_simple.c
!Edrivers/base/core.c
!Edrivers/base/firmware_class.c
!Edrivers/base/transport_class.c
!Edrivers/base/dmapool.c
<!-- Cannot be included, because
attribute_container_add_class_device_adapter
and attribute_container_classdev_to_container
exceed allowed 44 characters maximum
X!Edrivers/base/attribute_container.c
-->
!Edrivers/base/sys.c
<!--
X!Edrivers/base/interface.c
-->
!Edrivers/base/platform.c
!Edrivers/base/bus.c
</sect1>
<sect1><title>Device Drivers Power Management</title>
!Edrivers/base/power/main.c
!Edrivers/base/power/resume.c
!Edrivers/base/power/suspend.c
</sect1>
<sect1><title>Device Drivers ACPI Support</title>
<!-- Internal functions only
X!Edrivers/acpi/sleep/main.c
X!Edrivers/acpi/sleep/wakeup.c
X!Edrivers/acpi/motherboard.c
X!Edrivers/acpi/bus.c
-->
!Edrivers/acpi/scan.c
<!-- No correct structured comments
X!Edrivers/acpi/pci_bind.c
-->
</sect1>
<sect1><title>Device drivers PnP support</title>
!Edrivers/pnp/core.c
<!-- No correct structured comments
X!Edrivers/pnp/system.c
-->
!Edrivers/pnp/card.c
!Edrivers/pnp/driver.c
!Edrivers/pnp/manager.c
!Edrivers/pnp/support.c
</sect1>
</chapter>


<chapter id="blkdev">
<title>Block Devices</title>
!Edrivers/block/ll_rw_blk.c
Expand All @@ -250,14 +403,31 @@ X!Earch/i386/kernel/mca.c

<chapter id="snddev">
<title>Sound Devices</title>
!Iinclude/sound/core.h
!Esound/sound_core.c
!Iinclude/sound/pcm.h
!Esound/core/pcm.c
!Esound/core/device.c
!Esound/core/info.c
!Esound/core/rawmidi.c
!Esound/core/sound.c
!Esound/core/memory.c
!Esound/core/pcm_memory.c
!Esound/core/init.c
!Esound/core/isadma.c
!Esound/core/control.c
!Esound/core/pcm_lib.c
!Esound/core/hwdep.c
!Esound/core/pcm_native.c
!Esound/core/memalloc.c
<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
</chapter>

<chapter id="uart16x50">
<title>16x50 UART Driver</title>
!Iinclude/linux/serial_core.h
!Edrivers/serial/serial_core.c
!Edrivers/serial/8250.c
</chapter>
Expand Down Expand Up @@ -310,9 +480,11 @@ X!Isound/sound_firmware.c
<sect1><title>Frame Buffer Memory</title>
!Edrivers/video/fbmem.c
</sect1>
<!--
<sect1><title>Frame Buffer Console</title>
!Edrivers/video/console/fbcon.c
X!Edrivers/video/console/fbcon.c
</sect1>
-->
<sect1><title>Frame Buffer Colormap</title>
!Edrivers/video/fbcmap.c
</sect1>
Expand Down
5 changes: 2 additions & 3 deletions drivers/video/fbmem.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1257,6 +1257,8 @@ int fb_new_modelist(struct fb_info *info)
static char *video_options[FB_MAX];
static int ofonly;

extern const char *global_mode_option;

/**
* fb_get_options - get kernel boot parameters
* @name: framebuffer name as it would appear in
Expand Down Expand Up @@ -1297,9 +1299,6 @@ int fb_get_options(char *name, char **option)
return retval;
}


extern const char *global_mode_option;

/**
* video_setup - process command line options
* @options: string of options
Expand Down
10 changes: 5 additions & 5 deletions fs/proc/base.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1703,13 +1703,13 @@ static struct inode_operations proc_self_inode_operations = {
};

/**
* proc_pid_unhash - Unhash /proc/<pid> entry from the dcache.
* proc_pid_unhash - Unhash /proc/@pid entry from the dcache.
* @p: task that should be flushed.
*
* Drops the /proc/<pid> dcache entry from the hash chains.
* Drops the /proc/@pid dcache entry from the hash chains.
*
* Dropping /proc/<pid> entries and detach_pid must be synchroneous,
* otherwise e.g. /proc/<pid>/exe might point to the wrong executable,
* Dropping /proc/@pid entries and detach_pid must be synchroneous,
* otherwise e.g. /proc/@pid/exe might point to the wrong executable,
* if the pid value is immediately reused. This is enforced by
* - caller must acquire spin_lock(p->proc_lock)
* - must be called before detach_pid()
Expand Down Expand Up @@ -1741,7 +1741,7 @@ struct dentry *proc_pid_unhash(struct task_struct *p)
}

/**
* proc_pid_flush - recover memory used by stale /proc/<pid>/x entries
* proc_pid_flush - recover memory used by stale /proc/@pid/x entries
* @proc_entry: directoy to prune.
*
* Shrink the /proc directory that was used by the just killed thread.
Expand Down
12 changes: 6 additions & 6 deletions include/linux/fs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1053,12 +1053,12 @@ static inline void file_accessed(struct file *file)
int sync_inode(struct inode *inode, struct writeback_control *wbc);

/**
* &export_operations - for nfsd to communicate with file systems
* decode_fh: decode a file handle fragment and return a &struct dentry
* encode_fh: encode a file handle fragment from a dentry
* get_name: find the name for a given inode in a given directory
* get_parent: find the parent of a given directory
* get_dentry: find a dentry for the inode given a file handle sub-fragment
* struct export_operations - for nfsd to communicate with file systems
* @decode_fh: decode a file handle fragment and return a &struct dentry
* @encode_fh: encode a file handle fragment from a dentry
* @get_name: find the name for a given inode in a given directory
* @get_parent: find the parent of a given directory
* @get_dentry: find a dentry for the inode given a file handle sub-fragment
*
* Description:
* The export_operations structure provides a means for nfsd to communicate
Expand Down
Loading

0 comments on commit 4dc3b16

Please sign in to comment.