kdb: Add kdb kernel module sample

Add an example of how to add a dynamic kdb shell command via a kernel
module.

Signed-off-by: Jason Wessel <[e-mail]>

Documentation/DocBook/kgdb.tmpl

···
         <listitem><para>A simple shell</para></listitem>
         <listitem><para>The kdb core command set</para></listitem>
         <listitem><para>A registration API to register additional kdb shell commands.</para>
-        <para>A good example of a self-contained kdb module is the "ftdump" command for dumping the ftrace buffer.  See: kernel/trace/trace_kdb.c</para></listitem>
+	<itemizedlist>
+        <listitem><para>A good example of a self-contained kdb module
+        is the "ftdump" command for dumping the ftrace buffer.  See:
+        kernel/trace/trace_kdb.c</para></listitem>
+        <listitem><para>For an example of how to dynamically register
+        a new kdb command you can build the kdb_hello.ko kernel module
+        from samples/kdb/kdb_hello.c.  To build this example you can
+        set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
+        config.  Later run "modprobe kdb_hello" and the next time you
+        enter the kdb shell, you can run the "hello"
+        command.</para></listitem>
+	</itemizedlist></listitem>
         <listitem><para>The implementation for kdb_printf() which
         emits messages directly to I/O drivers, bypassing the kernel
         log.</para></listitem>

samples/Kconfig

···
 
 	  If in doubt, say "N" here.
 
+config SAMPLE_KDB
+	tristate "Build kdb command exmaple -- loadable modules only"
+	depends on KGDB_KDB && m
+	help
+	  Build an example of how to dynamically add the hello
+	  command to the kdb shell.
+
 endif # SAMPLES

samples/Makefile

···
 # Makefile for Linux samples code
 
 obj-$(CONFIG_SAMPLES)	+= kobject/ kprobes/ tracepoints/ trace_events/ \
-			   hw_breakpoint/ kfifo/
+			   hw_breakpoint/ kfifo/ kdb/

samples/kdb/Makefile

···
+obj-$(CONFIG_SAMPLE_KDB) += kdb_hello.o

samples/kdb/kdb_hello.c

···
+/*
+ * Created by: Jason Wessel <[e-mail]>
+ *
+ * Copyright (c) 2010 Wind River Systems, Inc.  All Rights Reserved.
+ *
+ * This file is licensed under the terms of the GNU General Public
+ * License version 2. This program is licensed "as is" without any
+ * warranty of any kind, whether express or implied.
+ */
+
+#include <linux/module.h>
+#include <linux/kdb.h>
+
+/*
+ * All kdb shell command call backs receive argc and argv, where
+ * argv[0] is the command the end user typed
+ */
+static int kdb_hello_cmd(int argc, const char **argv)
+{
+	if (argc > 1)
+		return KDB_ARGCOUNT;
+
+	if (argc)
+		kdb_printf("Hello %s.\n", argv[1]);
+	else
+		kdb_printf("Hello world!\n");
+
+	return 0;
+}
+
+
+static int __init kdb_hello_cmd_init(void)
+{
+	/*
+	 * Registration of a dynamically added kdb command is done with
+	 * kdb_register() with the arguments being:
+	 *   1: The name of the shell command
+	 *   2: The function that processes the command
+	 *   3: Description of the usage of any arguments
+	 *   4: Descriptive text when you run help
+	 *   5: Number of characters to complete the command
+	 *      0 == type the whole command
+	 *      1 == match both "g" and "go" for example
+	 */
+	kdb_register("hello", kdb_hello_cmd, "[string]",
+		     "Say Hello World or Hello [string]", 0);
+	return 0;
+}
+
+static void __exit kdb_hello_cmd_exit(void)
+{
+	kdb_unregister("hello");
+}
+
+module_init(kdb_hello_cmd_init);
+module_exit(kdb_hello_cmd_exit);
+
+MODULE_AUTHOR("WindRiver");
+MODULE_DESCRIPTION("KDB example to add a hello command");
+MODULE_LICENSE("GPL");