[FE training-materials-updates] Add \kerneldoc macro

Michael Opdenacker michael.opdenacker at free-electrons.com
Fri Oct 5 14:18:18 CEST 2012

Repository : git://git.free-electrons.com/training-materials.git

On branch  : master
Link       : http://git.free-electrons.com/training-materials/commit/?id=7cd412215c7f9402bf6190d7c000caecfd7b8293


commit 7cd412215c7f9402bf6190d7c000caecfd7b8293
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Fri Oct 5 14:18:15 2012 +0200

    Add \kerneldoc macro
    To give hyperlinks to the on-line version of kernel documentation,
    available on http://free-electrons.com/kerneldoc/
    Convenient for peole reading the PDF files


 common/beamerthemeFreeElectrons.sty                |    4 ++++
 labs/kernel-serial-driver/kernel-serial-driver.tex |    2 +-
 ...nel-driver-development-architecture-drivers.tex |    4 ++--
 .../kernel-driver-development-concurrency.tex      |    2 +-
 .../kernel-driver-development-debugging.tex        |   18 ++++++++----------
 .../kernel-driver-development-dma.tex              |    2 +-
 .../kernel-driver-development-io-memory.tex        |    2 +-
 .../kernel-driver-development-memory.tex           |    6 +++---
 .../kernel-driver-development-modules.tex          |    2 +-
 .../kernel-porting-content.tex                     |    2 +-
 .../kernel-power-management-content.tex            |   12 ++++++------
 .../kernel-resources-advice.tex                    |    6 +++---
 .../kernel-serial-drivers-content.tex              |    4 ++--
 .../kernel-source-code-drivers.tex                 |    8 +++-----
 .../sysdev-block-filesystems.tex                   |    2 +-
 .../sysdev-linux-intro-cross-compilation.tex       |    4 ++--
 slides/sysdev-realtime/sysdev-realtime.tex         |    2 +-
 .../sysdev-root-filesystem-principles.tex          |    4 ++--
 .../sysdev-root-filesystem-virtual-fs.tex          |    7 +++----
 slides/sysdev-udev/sysdev-udev.tex                 |    2 +-
 20 files changed, 47 insertions(+), 48 deletions(-)

diff --git a/common/beamerthemeFreeElectrons.sty b/common/beamerthemeFreeElectrons.sty
index b8428c4..6eb83cc 100644
--- a/common/beamerthemeFreeElectrons.sty
+++ b/common/beamerthemeFreeElectrons.sty
@@ -171,4 +171,8 @@
   {\large \color{red}TODO: #1}
+  {\href{http://free-electrons.com/kerneldoc/latest/#1}{\code{Documentation/#1}}}
diff --git a/labs/kernel-serial-driver/kernel-serial-driver.tex b/labs/kernel-serial-driver/kernel-serial-driver.tex
index a536b6c..df51afa 100644
--- a/labs/kernel-serial-driver/kernel-serial-driver.tex
+++ b/labs/kernel-serial-driver/kernel-serial-driver.tex
@@ -65,7 +65,7 @@ Instantiate a \code{uart_driver} structure with the following values:
 \item \code{dev_name}, \code{ttyS}
 \item \code{major}, \code{TTY_MAJOR} (this is the usual major for TTY devices)
 \item \code{minor}, \code{64} (this is the usual minor for TTY serial
-  devices, see \code{Documentation/devices.txt} in the kernel source tree)
+  devices, see \kerneldoc{devices.txt} in the kernel source tree)
 \item \code{nr}, \code{1} (we will support only one port)
diff --git a/slides/kernel-driver-development-architecture-drivers/kernel-driver-development-architecture-drivers.tex b/slides/kernel-driver-development-architecture-drivers/kernel-driver-development-architecture-drivers.tex
index 2ced16a..5af919a 100644
--- a/slides/kernel-driver-development-architecture-drivers/kernel-driver-development-architecture-drivers.tex
+++ b/slides/kernel-driver-development-architecture-drivers/kernel-driver-development-architecture-drivers.tex
@@ -907,8 +907,8 @@ static void __init dk_board_init(void)
   \item Kernel documentation
-    \item \code{Documentation/driver-model/}
-    \item \code{Documentation/filesystems/sysfs.txt}
+    \item \kerneldoc{driver-model/}
+    \item \kerneldoc{filesystems/sysfs.txt}
   \item The kernel source code
diff --git a/slides/kernel-driver-development-concurrency/kernel-driver-development-concurrency.tex b/slides/kernel-driver-development-concurrency/kernel-driver-development-concurrency.tex
index 2329a97..138955b 100644
--- a/slides/kernel-driver-development-concurrency/kernel-driver-development-concurrency.tex
+++ b/slides/kernel-driver-development-concurrency/kernel-driver-development-concurrency.tex
@@ -224,7 +224,7 @@ static unsigned int ulite_tx_empty
     \item Not suitable for production systems but acceptable overhead
       in development.
-  \item See \code{Documentation/lockdep-design.txt} for details
+  \item See \kerneldoc{lockdep-design.txt} for details
diff --git a/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex b/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex
index 821d248..474bea7 100644
--- a/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex
+++ b/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex
@@ -43,7 +43,7 @@
     then those messages can dynamically be enabled on a per-file,
     per-module or per-message basis
-    \item See \code{Documentation/dynamic-debug-howto.txt} for details
+    \item See \kerneldoc{dynamic-debug-howto.txt} for details
     \item Very powerful feature to only get the debug messages you're
       interested in.
@@ -68,11 +68,11 @@
     \item The \code{loglevel} kernel parameter, which defines the
       priority above which messages are displayed on the console. See
-      \code{Documentation/kernel-parameters.txt} for details.
+      \kerneldoc{kernel-parameters.txt} for details.
     \item The value of \code{/proc/sys/kernel/printk}, which allows to
       change at runtime the priority above which messages are
       displayed on the console. See
-      \code{Documentation/sysctl/kernel.txt} for details.
+      \kerneldoc{sysctl/kernel.txt} for details.
@@ -96,8 +96,7 @@
     \item First described on \url{http://lwn.net/Articles/115405/}
     \item API documented in the Linux Kernel Filesystem API:
-      \item \href{http://free-electrons.com/kerneldoc/latest/DocBook/filesystems/}
-          {Documentation/DocBook/filesystems/}
+      \item \kerneldoc{DocBook/filesystems/}
@@ -169,7 +168,7 @@
     \item \code{b}: reboot the system
     \item You can even register your own!
-  \item Detailed in \code{Documentation/sysrq.txt}
+  \item Detailed in \kerneldoc{sysrq.txt}
@@ -189,8 +188,7 @@
   \frametitle{Using kgdb 1/2}
   \item Details available in the kernel documentation:
-    \href{http://free-electrons.com/kerneldoc/latest/DocBook/kgdb/}
-         {Documentation/DocBook/kgdb/}
+    \kerneldoc{DocBook/kgdb/}
   \item Recommended to turn on \code{CONFIG_FRAME_POINTER} to aid in
     producing more reliable stack backtraces in gdb.
   \item You must include a kgdb I/O driver. One of them is kgdb over
@@ -285,7 +283,7 @@
       execute a new, clean kernel from a reserved location in RAM, to
       perform post-mortem analysis of the memory of the crashed
-    \item See \code{Documentation/kdump/kdump.txt} in the kernel
+    \item See \kerneldoc{kdump/kdump.txt} in the kernel
       sources for details.
@@ -307,7 +305,7 @@
     \item Uses a simple scripting language.
     \item Several example scripts and probe points are available.
     \item Based on the \code{Kprobes} instrumentation infrastructure.
-    \item See \code{Documentation/kprobes.txt} in kernel sources.
+    \item See \kerneldoc{kprobes.txt} in kernel sources.
     \item Now supported on most popular CPUs.
diff --git a/slides/kernel-driver-development-dma/kernel-driver-development-dma.tex b/slides/kernel-driver-development-dma/kernel-driver-development-dma.tex
index 56b1caa..18f8fe8 100644
--- a/slides/kernel-driver-development-dma/kernel-driver-development-dma.tex
+++ b/slides/kernel-driver-development-dma/kernel-driver-development-dma.tex
@@ -99,7 +99,7 @@ dmabuf = ioremap (
     \item Either allocating a buffer in a cache coherent area,
     \item Or making sure caches are flushed when required,
     \item Managing the DMA mappings and IOMMU (if any).
-    \item See \code{Documentation/DMA-API.txt} for details about the
+    \item See \kerneldoc{DMA-API.txt} for details about the
       Linux DMA generic API.
     \item Most subsystems (such as PCI or USB) supply their own DMA
       API, derived from the generic one. May be sufficient for most
diff --git a/slides/kernel-driver-development-io-memory/kernel-driver-development-io-memory.tex b/slides/kernel-driver-development-io-memory/kernel-driver-development-io-memory.tex
index b132e75..6583ac9 100644
--- a/slides/kernel-driver-development-io-memory/kernel-driver-development-io-memory.tex
+++ b/slides/kernel-driver-development-io-memory/kernel-driver-development-io-memory.tex
@@ -245,7 +245,7 @@ __raw_writel(1 << KS8695_IRQ_UART_TX,
   \item Starts to be a problem with CPUs that reorder instructions and
-  \item See \code{Documentation/memory-barriers.txt} for details
+  \item See \kerneldoc{memory-barriers.txt} for details
diff --git a/slides/kernel-driver-development-memory/kernel-driver-development-memory.tex b/slides/kernel-driver-development-memory/kernel-driver-development-memory.tex
index 4b49e4b..d7d0147 100644
--- a/slides/kernel-driver-development-memory/kernel-driver-development-memory.tex
+++ b/slides/kernel-driver-development-memory/kernel-driver-development-memory.tex
@@ -55,7 +55,7 @@
       (\code{CONFIG_VMSPLIT_3G)} $\Rightarrow$ reduces total memory
       available for each process
     \item Change for a 64 bit architecture ;-) See
-      \code{Documentation/x86/x86_64/mm.txt} for an example.
+      \kerneldoc{x86/x86_64/mm.txt} for an example.
     \item Activate \emph{highmem} support if available for your
@@ -364,13 +364,13 @@ kfree(work);
       \item Dynamic checker for access to uninitialized memory.
       \item Only available on \code{x86} so far (Linux 3.6 status), but will
         help to improve architecture independent code anyway.
-      \item See \code{Documentation/kmemcheck.txt} for details.
+      \item See \kerneldoc{kmemcheck.txt} for details.
     \item \code{Kmemleak}
       \item Dynamic checker for memory leaks
       \item This feature is available for all architectures.
-      \item See \code{Documentation/kmemleak.txt} for details.
+      \item See \kerneldoc{kmemleak.txt} for details.
   \item Both have a significant overhead. Only use them in development!
diff --git a/slides/kernel-driver-development-modules/kernel-driver-development-modules.tex b/slides/kernel-driver-development-modules/kernel-driver-development-modules.tex
index 6926b81..3b988ee 100644
--- a/slides/kernel-driver-development-modules/kernel-driver-development-modules.tex
+++ b/slides/kernel-driver-development-modules/kernel-driver-development-modules.tex
@@ -259,7 +259,7 @@ config USB_SERIAL_NAVMAN
     \item Run \code{make xconfig} and see your new options!
     \item Run \code{make} and your new files are compiled!
-    \item See \code{Documentation/kbuild/} for details and more
+    \item See \kerneldoc{kbuild/} for details and more
       elaborate examples like drivers with several source files, or
       drivers in their own subdirectory, etc.
diff --git a/slides/kernel-porting-content/kernel-porting-content.tex b/slides/kernel-porting-content/kernel-porting-content.tex
index 4e28129..1e5a686 100644
--- a/slides/kernel-porting-content/kernel-porting-content.tex
+++ b/slides/kernel-porting-content/kernel-porting-content.tex
@@ -243,7 +243,7 @@ MACHINE_END
       left the boot parameters (the kernel command line)
     \item The bootloader can override this address in register
-    \item See also \code{Documentation/arm/Booting} for the details of
+    \item See also \kerneldoc{arm/Booting} for the details of
       the environment expected by the kernel when booted
diff --git a/slides/kernel-power-management-content/kernel-power-management-content.tex b/slides/kernel-power-management-content/kernel-power-management-content.tex
index e17ed8e..0b7792e 100644
--- a/slides/kernel-power-management-content/kernel-power-management-content.tex
+++ b/slides/kernel-power-management-content/kernel-power-management-content.tex
@@ -164,7 +164,7 @@ static void pmc_sys_mode(struct clk *clk, int is_on)
   \item New hooks must be added to the drivers:
     \code{runtime_suspend()}, \code{runtime_resume()},
-  \item API and details on \code{Documentation/power/runtime_pm.txt}
+  \item API and details on \kerneldoc{power/runtime_pm.txt}
   \item See also Kevin Hilman's presentation at ELC Europe 2010:
@@ -203,7 +203,7 @@ static void pmc_sys_mode(struct clk *clk, int is_on)
       \item Platform-independent governors (ladder and menu)
       \item Available for x86/ACPI, not supported yet by all ARM cpus.
         (look for \code{cpuidle*} files under \code{arch/arm/})
-      \item See \code{Documentation/cpuidle/} in kernel sources.
+      \item See \kerneldoc{cpuidle/} in kernel sources.
@@ -263,7 +263,7 @@ static void pmc_sys_mode(struct clk *clk, int is_on)
     \item \code{setpolicy()} or \code{target()} to actually perform
       the frequency change
-  \item See \code{Documentation/cpu-freq/} for useful explanations
+  \item See \kerneldoc{cpu-freq/} for useful explanations
@@ -280,7 +280,7 @@ static void pmc_sys_mode(struct clk *clk, int is_on)
   \item According to these requirements, PM QoS allows kernel drivers
     to adjust their power management
-  \item See \code{Documentation/power/pm_qos_interface.txt} and Mark
+  \item See \kerneldoc{power/pm_qos_interface.txt} and Mark
     Gross' presentation at ELC 2008
   \item Still in very early deployment (only 4 drivers in 2.6.36).
@@ -300,7 +300,7 @@ static void pmc_sys_mode(struct clk *clk, int is_on)
     \item sysfs interface for userspace
   \item Merged in Linux 2.6.27.
-  \item See \code{Documentation/power/regulator/} in kernel sources.
+  \item See \kerneldoc{power/regulator/} in kernel sources.
   \item See Liam Girdwood's presentation at ELC 2008
@@ -330,7 +330,7 @@ static void pmc_sys_mode(struct clk *clk, int is_on)
   \frametitle{Useful Resources}
-  \item \code{Documentation/power/} in the Linux kernel sources.
+  \item \kerneldoc{power/} in the Linux kernel sources.
     \item Will give you many useful details.
diff --git a/slides/kernel-resources-advice/kernel-resources-advice.tex b/slides/kernel-resources-advice/kernel-resources-advice.tex
index 529ddf7..5b3f3bc 100644
--- a/slides/kernel-resources-advice/kernel-resources-advice.tex
+++ b/slides/kernel-resources-advice/kernel-resources-advice.tex
@@ -39,7 +39,7 @@
   \item First make sure you're using the latest version
   \item Make sure you investigate the issue as much as you can: see
-    \code{Documentation/BUG-HUNTING}
+    \kerneldoc{BUG-HUNTING}
   \item Check for previous bugs reports. Use web search engines,
     accessing public mailing list archives.
   \item If the subsystem you report a bug on has a mailing list, use
@@ -54,7 +54,7 @@
   \item Recommended resources
-    \item See \code{Documentation/SubmittingPatches} for guidelines
+    \item See \kerneldoc{SubmittingPatches} for guidelines
       and \url{http://kernelnewbies.org/UpstreamMerge} for very
       helpful advice to have your changes merged upstream (by Rik van
@@ -79,7 +79,7 @@
   \item Send the patches to yourself first, as an inline
     attachment. This is required to let people reply to parts of your
     patches. Make sure your patches still applies. See
-    \code{Documentation/email-clients.txt} for help configuring e-mail
+    \kerneldoc{email-clients.txt} for help configuring e-mail
     clients. Best to use \code{git send-email}, which never corrupts
   \item Run \code{scripts/get_maintainer.pl} on your patches, to know
diff --git a/slides/kernel-serial-drivers-content/kernel-serial-drivers-content.tex b/slides/kernel-serial-drivers-content/kernel-serial-drivers-content.tex
index befc0a7..ffdc598 100644
--- a/slides/kernel-serial-drivers-content/kernel-serial-drivers-content.tex
+++ b/slides/kernel-serial-drivers-content/kernel-serial-drivers-content.tex
@@ -245,7 +245,7 @@ static void __devinit atmel_init_port(
     \item \code{set_termios()}, change port parameters
   \item See the detailed description in
-    \code{Documentation/serial/driver}
+    \kerneldoc{serial/driver}
@@ -376,7 +376,7 @@ foo_uart_handle_transmit(port) {
       so that even if the system is locked, you can recover it.
     \item Through serial port: send a \code{BRK} character, send the
       character of the \code{Sysrq} command
-    \item See \code{Documentation/sysrq.txt}
+    \item See \kerneldoc{sysrq.txt}
   \item In the driver
diff --git a/slides/kernel-source-code-drivers/kernel-source-code-drivers.tex b/slides/kernel-source-code-drivers/kernel-source-code-drivers.tex
index dddf1ac..70abc43 100644
--- a/slides/kernel-source-code-drivers/kernel-source-code-drivers.tex
+++ b/slides/kernel-source-code-drivers/kernel-source-code-drivers.tex
@@ -94,7 +94,7 @@
     changes between two stable 2.6.x or 3.x releases. A stand-alone
     driver compiled for a given version may no longer compile or work
     on a more recent one. See
-    \code{Documentation/stable_api_nonsense.txt} in kernel sources for
+    \kerneldoc{stable_api_nonsense.txt} in kernel sources for
     reasons why.
   \item Of course, the external API must not change (system calls,
     \code{/proc}, \code{/sys}), as it could break existing
@@ -248,10 +248,8 @@
     \item Printer and scanner drivers (on top of generic parallel port
       or USB drivers)
     \item X drivers: low level kernel drivers + user space X drivers.
-    \item Userspace drivers based on UIO See
-      \href{http://free-electrons.com/kerneldoc/latest/DocBook/uio-howto/}
-      {\code{Documentation/DocBook/uio-howto}} in the kernel
-      documentation for details about UIO and the \emph{Using UIO on
+    \item Userspace drivers based on UIO. See \kerneldoc{DocBook/uio-howto}
+      in the kernel documentation for details about UIO and the \emph{Using UIO on
         an Embedded platform} talk at ELC 2008
diff --git a/slides/sysdev-block-filesystems/sysdev-block-filesystems.tex b/slides/sysdev-block-filesystems/sysdev-block-filesystems.tex
index 6166411..4e1f170 100644
--- a/slides/sysdev-block-filesystems/sysdev-block-filesystems.tex
+++ b/slides/sysdev-block-filesystems/sysdev-block-filesystems.tex
@@ -210,7 +210,7 @@ major minor #blocks name
     \code{mount -t tmpfs varrun /var/run}\\
     \code{mount -t tmpfs udev /dev}
-  See \code{Documentation/filesystems/tmpfs.txt} in kernel sources.
+  See \kerneldoc{filesystems/tmpfs.txt} in kernel sources.
diff --git a/slides/sysdev-linux-intro-cross-compilation/sysdev-linux-intro-cross-compilation.tex b/slides/sysdev-linux-intro-cross-compilation/sysdev-linux-intro-cross-compilation.tex
index 68cb2d9..ad46654 100644
--- a/slides/sysdev-linux-intro-cross-compilation/sysdev-linux-intro-cross-compilation.tex
+++ b/slides/sysdev-linux-intro-cross-compilation/sysdev-linux-intro-cross-compilation.tex
@@ -152,8 +152,8 @@
     \item It is very important for system configuration
     \item \code{root=} for the root filesystem (covered later)
     \item \code{console=} for the destination of kernel messages
-    \item and many more, documented in
-      \code{Documentation/kernel-parameters.txt} in the kernel sources
+    \item and many more, documented in \kerneldoc{kernel-parameters.txt}
+       in the kernel sources
   \item This kernel command line is either
diff --git a/slides/sysdev-realtime/sysdev-realtime.tex b/slides/sysdev-realtime/sysdev-realtime.tex
index 1c0ca1e..af65555 100644
--- a/slides/sysdev-realtime/sysdev-realtime.tex
+++ b/slides/sysdev-realtime/sysdev-realtime.tex
@@ -846,7 +846,7 @@ timer_delete(timer_t timerid)
   \item Developed by Steven Rostedt. Merged in 2.6.27. For earlier
     kernels, can be found from the PREEMPT\_RT patches.
-  \item Very well documented in \code{Documentation/ftrace.txt}
+  \item Very well documented in \kerneldoc{ftrace.txt}
   \item Negligible overhead when tracing is not enabled at run-time.
   \item Can be used to trace any kernel function!
   \item See our video of Steven's tutorial at OLS 2008:\\
diff --git a/slides/sysdev-root-filesystem-principles/sysdev-root-filesystem-principles.tex b/slides/sysdev-root-filesystem-principles/sysdev-root-filesystem-principles.tex
index bed6bb8..c24ad8c 100644
--- a/slides/sysdev-root-filesystem-principles/sysdev-root-filesystem-principles.tex
+++ b/slides/sysdev-root-filesystem-principles/sysdev-root-filesystem-principles.tex
@@ -257,7 +257,7 @@ Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)
   \item The kernel build process will automatically take the contents
     of the \code{CONFIG_INITRAMFS_SOURCE} option and integrate the
     root filesystem into the kernel image
-  \item \code{Documentation/filesystems/ramfs-rootfs-initramfs.txt}\\
-    \code{Documentation/early-userspace/README}
+  \item \kerneldoc{filesystems/ramfs-rootfs-initramfs.txt}\\
+    \kerneldoc{early-userspace/README}
diff --git a/slides/sysdev-root-filesystem-virtual-fs/sysdev-root-filesystem-virtual-fs.tex b/slides/sysdev-root-filesystem-virtual-fs/sysdev-root-filesystem-virtual-fs.tex
index a902d94..5b9f1d4 100644
--- a/slides/sysdev-root-filesystem-virtual-fs/sysdev-root-filesystem-virtual-fs.tex
+++ b/slides/sysdev-root-filesystem-virtual-fs/sysdev-root-filesystem-virtual-fs.tex
@@ -17,8 +17,7 @@
     without the \code{proc} filesystem
   \item Command to mount \code{/proc}:\\
     \code{mount -t proc nodev /proc}
-  \item \code{Documentation/filesystems/proc.txt} in the kernel
-    sources
+  \item \kerneldoc{filesystems/proc.txt} in the kernel sources
   \item \code{man proc}
@@ -40,8 +39,8 @@
   \item \code{/proc/sys} contains many files that can be written to to
     adjust kernel parameters
-    \item They are called {\em sysctl}. See
-      \code{Documentation/sysctl/} in kernel sources.
+    \item They are called {\em sysctl}. See \kerneldoc{/latest/sysctl/}
+      in kernel sources.
     \item Example\\
       \code{echo 3 > /proc/sys/vm/drop_caches}
diff --git a/slides/sysdev-udev/sysdev-udev.tex b/slides/sysdev-udev/sysdev-udev.tex
index 48309f2..c99fafb 100644
--- a/slides/sysdev-udev/sysdev-udev.tex
+++ b/slides/sysdev-udev/sysdev-udev.tex
@@ -314,7 +314,7 @@ UDEVD_EVENT=1
-  See \code{Documentation/firmware_class/} in the kernel sources for a
+  See \kerneldoc{firmware_class/} in the kernel sources for a
   nice overview

More information about the training-materials-updates mailing list