Merge branch 'devel-stable' into devel

   may be configured as a kernel built-in or a kernel loadable module.

   You can only make use of <constant>kgdbwait</constant> and early

   debugging if you build kgdboc into the kernel as a built-in.

   <para>Optionally you can elect to activate kms (Kernel Mode

   Setting) integration.  When you use kms with kgdboc and you have a

   video driver that has atomic mode setting hooks, it is possible to

   enter the debugger on the graphics console.  When the kernel

   execution is resumed, the previous graphics mode will be restored.

   This integration can serve as a useful tool to aid in diagnosing

   crashes or doing analysis of memory with kdb while allowing the

   full graphics console applications to run.

   </para>

   </para>

   <sect2 id="kgdbocArgs">

   <title>kgdboc arguments</title>

   <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para>

   <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para>

   <para>The order listed above must be observed if you use any of the

   optional configurations together.

   </para>

   <para>Abbreviations:

   <itemizedlist>

   <listitem><para>kms = Kernel Mode Setting</para></listitem>

   <listitem><para>kbd = Keyboard</para></listitem>

   </itemizedlist>

   </para>

   <para>You can configure kgdboc to use the keyboard, and or a serial

   device depending on if you are using kdb and or kgdb, in one of the

   following scenarios.  The order listed above must be observed if

   you use any of the optional configurations together.  Using kms +

   only gdb is generally not a useful combination.</para>

   <sect3 id="kgdbocArgs1">

   <title>Using loadable module or built-in</title>

   <para>

   <listitem>

   <para>As a kernel loadable module:</para>

   <para>Use the command: <constant>modprobe kgdboc kgdboc=&lt;tty-device&gt;,[baud]</constant></para>

   <para>Here are two examples of how you might formate the kgdboc

   <para>Here are two examples of how you might format the kgdboc

   string. The first is for an x86 target using the first serial port.

   The second example is for the ARM Versatile AB using the second

   serial port.

   </sect3>

   <sect3 id="kgdbocArgs3">

   <title>More examples</title>

   <para>You can configure kgdboc to use the keyboard, and or a serial

   device depending on if you are using kdb and or kgdb, in one of the

   following scenarios.</para>

   <para>You can configure kgdboc to use the keyboard, and or a serial device

   depending on if you are using kdb and or kgdb, in one of the

   following scenarios.

   <listitem><para>kdb with a keyboard</para>

   <para><constant>kgdboc=kbd</constant></para>

   </listitem>

   <listitem><para>kdb with kernel mode setting</para>

   <para><constant>kgdboc=kms,kbd</constant></para>

   </listitem>

   <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para>

   <para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para>

   </listitem>

   </orderedlist>

   </para>

   </sect3>

      <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>

      <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>

      <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem>

      <listitem><para>The structures and callback API for atomic kernel mode setting.</para>

      <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem>

      </itemizedlist>

      </para>

      </listitem>

  </sect1>

  <sect1 id="kgdbocDesign">

  <title>kgdboc internals</title>

  <sect2>

  <title>kgdboc and uarts</title>

  <para>

  The kgdboc driver is actually a very thin driver that relies on the

  underlying low level to the hardware driver having "polling hooks"

  low level UART hook for doing polled mode reading and writing of a

  single character while in an atomic context.  When kgdb makes an I/O

  request to the debugger, kgdboc invokes a callback in the serial

  core which in turn uses the call back in the UART driver.  It is

  certainly possible to extend kgdboc to work with non-UART based

  consoles in the future.

  </para>

  core which in turn uses the callback in the UART driver.</para>

  <para>

  When using kgdboc with a UART, the UART driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>

#ifdef CONFIG_CONSOLE_POLL

  that they can be called from an atomic context and have to restore

  the state of the UART chip on return such that the system can return

  to normal when the debugger detaches.  You need to be very careful

  with any kind of lock you consider, because failing here is most

  with any kind of lock you consider, because failing here is most likely

  going to mean pressing the reset button.

  </para>

  </sect2>

  <sect2 id="kgdbocKbd">

  <title>kgdboc and keyboards</title>

  <para>The kgdboc driver contains logic to configure communications

  with an attached keyboard.  The keyboard infrastructure is only

  compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the

  kernel configuration.</para>

  <para>The core polled keyboard driver driver for PS/2 type keyboards

  is in drivers/char/kdb_keyboard.c.  This driver is hooked into the

  debug core when kgdboc populates the callback in the array

  called <constant>kdb_poll_funcs[]</constant>.  The

  kdb_get_kbd_char() is the top-level function which polls hardware

  for single character input.

  </para>

  </sect2>

  <sect2 id="kgdbocKms">

  <title>kgdboc and kms</title>

  <para>The kgdboc driver contains logic to request the graphics

  display to switch to a text context when you are using

  "kgdboc=kms,kbd", provided that you have a video driver which has a

  frame buffer console and atomic kernel mode setting support.</para>

  <para>

  Every time the kernel

  debugger is entered it calls kgdboc_pre_exp_handler() which in turn

  calls con_debug_enter() in the virtual console layer.  On resuming kernel

  execution, the kernel debugger calls kgdboc_post_exp_handler() which

  in turn calls con_debug_leave().</para>

  <para>Any video driver that wants to be compatible with the kernel

  debugger and the atomic kms callbacks must implement the

  mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations.

  For the fb_debug_enter and fb_debug_leave the option exists to use

  the generic drm fb helper functions or implement something custom for

  the hardware.  The following example shows the initialization of the

  .mode_set_base_atomic operation in

  drivers/gpu/drm/i915/intel_display.c:

  <informalexample>

  <programlisting>

static const struct drm_crtc_helper_funcs intel_helper_funcs = {

[...]

        .mode_set_base_atomic = intel_pipe_set_base_atomic,

[...]

};

  </programlisting>

  </informalexample>

  </para>

  <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in

  drivers/gpu/drm/i915/intel_fb.c:

  <informalexample>

  <programlisting>

static struct fb_ops intelfb_ops = {

[...]

       .fb_debug_enter = drm_fb_helper_debug_enter,

       .fb_debug_leave = drm_fb_helper_debug_leave,

[...]

};

  </programlisting>

  </informalexample>

  </para>

  </sect2>

  </sect1>

  </chapter>

  <chapter id="credits">

<param name="callout.graphics">0</param>

<!-- <param name="paper.type">A4</param> -->

<param name="generate.section.toc.level">2</param>

<param name="use.id.as.filename">1</param>

</stylesheet>

Last Updated May 2, 2002

September 2003: Updated I/O Scheduler portions

	Nick Piggin <piggin@cyberone.com.au>

	Nick Piggin <npiggin@kernel.dk>

Introduction:

Copyright 2010 Nicolas Palix <npalix@diku.dk>

Copyright 2010 Julia Lawall <julia@diku.dk>

Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr>

 Getting Coccinelle

~~~~~~~~~~~~~~~~~~~~

The semantic patches included in the kernel use the 'virtual rule'

feature which was introduced in Coccinelle version 0.1.11.

Coccinelle (>=0.2.0) is available through the package manager

of many distributions, e.g. :

 - Debian (>=squeeze)

 - Fedora (>=13)

 - Ubuntu (>=10.04 Lucid Lynx)

 - OpenSUSE

 - Arch Linux

 - NetBSD

 - FreeBSD

You can get the latest version released from the Coccinelle homepage at

http://coccinelle.lip6.fr/

Once you have it, run the following command:

     	./configure

        make

as a regular user, and install it with

        sudo make install

 Using Coccinelle on the Linux kernel

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Coccinelle-specific target is defined in the top level

Makefile. This target is named 'coccicheck' and calls the 'coccicheck'

front-end in the 'scripts' directory.

Four modes are defined: report, patch, context, and org. The mode to

use is specified by setting the MODE variable with 'MODE=<mode>'.

'report' generates a list in the following format:

  file:line:column-column: message

'patch' proposes a fix, when possible.

'context' highlights lines of interest and their context in a

diff-like style.Lines of interest are indicated with '-'.

'org' generates a report in the Org mode format of Emacs.

Note that not all semantic patches implement all modes.

To make a report for every semantic patch, run the following command:

	make coccicheck MODE=report

NB: The 'report' mode is the default one.

To produce patches, run:

	make coccicheck MODE=patch

The coccicheck target applies every semantic patch available in the

subdirectories of 'scripts/coccinelle' to the entire Linux kernel.

For each semantic patch, a changelog message is proposed.  It gives a

description of the problem being checked by the semantic patch, and

includes a reference to Coccinelle.

As any static code analyzer, Coccinelle produces false

positives. Thus, reports must be carefully checked, and patches

reviewed.

 Using Coccinelle with a single semantic patch

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The optional make variable COCCI can be used to check a single

semantic patch. In that case, the variable must be initialized with

the name of the semantic patch to apply.

For instance:

	make coccicheck COCCI=<my_SP.cocci> MODE=patch

or

	make coccicheck COCCI=<my_SP.cocci> MODE=report

 Proposing new semantic patches

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

New semantic patches can be proposed and submitted by kernel

developers. For sake of clarity, they should be organized in the

subdirectories of 'scripts/coccinelle/'.

 Detailed description of the 'report' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'report' generates a list in the following format:

  file:line:column-column: message

Example:

Running

	make coccicheck MODE=report COCCI=scripts/coccinelle/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@r depends on !context && !patch && (org || report)@

expression x;

position p;

@@

 ERR_PTR@p(PTR_ERR(x))

@script:python depends on report@

p << r.p;

x << r.x;

@@

msg="ERR_CAST can be used with %s" % (x)

coccilib.report.print_report(p[0], msg)

</smpl>

This SmPL excerpt generates entries on the standard output, as

illustrated below:

/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg

/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth

/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg

 Detailed description of the 'patch' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When the 'patch' mode is available, it proposes a fix for each problem

identified.

Example:

Running

	make coccicheck MODE=patch COCCI=scripts/coccinelle/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@ depends on !context && patch && !org && !report @

expression x;

@@

- ERR_PTR(PTR_ERR(x))

+ ERR_CAST(x)

</smpl>

This SmPL excerpt generates patch hunks on the standard output, as

illustrated below:

diff -u -p a/crypto/ctr.c b/crypto/ctr.c

--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200

+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200

@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct

 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,

 				  CRYPTO_ALG_TYPE_MASK);

 	if (IS_ERR(alg))

-		return ERR_PTR(PTR_ERR(alg));

+		return ERR_CAST(alg);

 	/* Block size must be >= 4 bytes. */

 	err = -EINVAL;

 Detailed description of the 'context' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'context' highlights lines of interest and their context

in a diff-like style.

NOTE: The diff-like output generated is NOT an applicable patch. The

      intent of the 'context' mode is to highlight the important lines

      (annotated with minus, '-') and gives some surrounding context

      lines around. This output can be used with the diff mode of

      Emacs to review the code.

Example:

Running

	make coccicheck MODE=context COCCI=scripts/coccinelle/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@ depends on context && !patch && !org && !report@

expression x;

@@

* ERR_PTR(PTR_ERR(x))

</smpl>

This SmPL excerpt generates diff hunks on the standard output, as

illustrated below:

diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing

--- /home/user/linux/crypto/ctr.c	2010-05-26 10:49:38.000000000 +0200

+++ /tmp/nothing

@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct

 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,

 				  CRYPTO_ALG_TYPE_MASK);

 	if (IS_ERR(alg))

-		return ERR_PTR(PTR_ERR(alg));

 	/* Block size must be >= 4 bytes. */

 	err = -EINVAL;

 Detailed description of the 'org' mode

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'org' generates a report in the Org mode format of Emacs.

Example:

Running

	make coccicheck MODE=org COCCI=scripts/coccinelle/err_cast.cocci

will execute the following part of the SmPL script.

<smpl>

@r depends on !context && !patch && (org || report)@

expression x;

position p;

@@

 ERR_PTR@p(PTR_ERR(x))

@script:python depends on org@

p << r.p;

x << r.x;

@@

msg="ERR_CAST can be used with %s" % (x)

msg_safe=msg.replace("[","@(").replace("]",")")

coccilib.org.print_todo(p[0], msg_safe)

</smpl>

This SmPL excerpt generates Org entries on the standard output, as

illustrated below:

* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]

* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]

* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]

KAFLAGS

--------------------------------------------------

Additional options to the assembler.

Additional options to the assembler (for built-in and modules).

AFLAGS_MODULE

--------------------------------------------------

Addtional module specific options to use for $(AS).

AFLAGS_KERNEL

--------------------------------------------------

Addtional options for $(AS) when used for assembler

code for code that is compiled as built-in.

KCFLAGS

--------------------------------------------------

Additional options to the C compiler.

Additional options to the C compiler (for built-in and modules).

CFLAGS_KERNEL

--------------------------------------------------

Addtional options for $(CC) when used to compile

code that is compiled as built-in.

CFLAGS_MODULE

--------------------------------------------------

Addtional module specific options to use for $(CC).

LDFLAGS_MODULE

--------------------------------------------------

Additional options used for $(LD) when linking modules.

KBUILD_VERBOSE

--------------------------------------------------

modules.

The directory can be specified in several ways:

1) Use "M=..." on the command line

2) Environmnet variable KBUILD_EXTMOD

3) Environmnet variable SUBDIRS

2) Environment variable KBUILD_EXTMOD

3) Environment variable SUBDIRS

The possibilities are listed in the order they take precedence.

Using "M=..." will always override the others.

KBUILD_OUTPUT

--------------------------------------------------

Specify the output directory when building the kernel.

The output directory can also be specificed using "O=...".

The output directory can also be specified using "O=...".

Setting "O=..." takes precedence over KBUILD_OUTPUT.

ARCH

    $3 - kernel map file

    $4 - default install path (use root directory if blank)

The implmentation of "make install" is architecture specific

The implementation of "make install" is architecture specific

and it may differ from the above.

INSTALLKERNEL is provided to enable the possibility to