From e3e2aaf7dc0d82a055e084cfd48b9257c0c66b68 Mon Sep 17 00:00:00 2001 From: Jason Wessel Date: Thu, 20 Mar 2008 13:43:45 -0500 Subject: [PATCH] kgdb: add documentation Add in the kgdb documentation for kgdb. Signed-off-by: Jason Wessel Signed-off-by: Ingo Molnar --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/kgdb.tmpl | 435 ++++++++++++++++++++++++++++++++ MAINTAINERS | 6 + include/linux/kgdb.h | 52 ++-- 4 files changed, 473 insertions(+), 22 deletions(-) create mode 100644 Documentation/DocBook/kgdb.tmpl diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 300e1707893f..e471bc466a7e 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -9,7 +9,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ procfs-guide.xml writing_usb_driver.xml networking.xml \ - kernel-api.xml filesystems.xml lsm.xml usb.xml \ + kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl new file mode 100644 index 000000000000..95e5f84cbf56 --- /dev/null +++ b/Documentation/DocBook/kgdb.tmpl @@ -0,0 +1,435 @@ + + + + + + Using kgdb and the kgdb Internals + + + + Jason + Wessel + +
+ jason.wessel@windriver.com +
+ + + + + + + Tom + Rini + +
+ trini@kernel.crashing.org +
+ + + + + + + Amit S. + Kale + +
+ amitkale@linsyssoft.com +
+ + + + + + 2008 + Wind River Systems, Inc. + + + 2004-2005 + MontaVista Software, Inc. + + + 2004 + Amit S. Kale + + + + + 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. + + + + + + + + Introduction + + kgdb is a source level debugger for linux kernel. It is used along + with gdb to debug a linux kernel. The expectation is that gdb can + be used to "break in" to the kernel to inspect memory, variables + and look through a cal stack information similar to what an + application developer would use gdb for. It is possible to place + breakpoints in kernel code and perform some limited execution + stepping. + + + Two machines are required for using kgdb. One of these machines is a + development machine and the other is a test machine. The kernel + to be debugged runs on the test machine. The development machine + runs an instance of gdb against the vmlinux file which contains + the symbols (not boot image such as bzImage, zImage, uImage...). + In gdb the developer specifies the connection parameters and + connects to kgdb. Depending on which kgdb I/O modules exist in + the kernel for a given architecture, it may be possible to debug + the test machine's kernel with the development machine using a + rs232 or ethernet connection. + + + + Compiling a kernel + + To enable CONFIG_KGDB, look under the "Kernel debugging" + and then select "KGDB: kernel debugging with remote gdb". + + + Next you should choose one of more I/O drivers to interconnect debugging + host and debugged target. Early boot debugging requires a KGDB + I/O driver that supports early debugging and the driver must be + built into the kernel directly. Kgdb I/O driver configuration + takes place via kernel or module parameters, see following + chapter. + + + The kgdb test compile options are described in the kgdb test suite chapter. + + + + + Enable kgdb for debugging + + In order to use kgdb you must activate it by passing configuration + information to one of the kgdb I/O drivers. If you do not pass any + configuration information kgdb will not do anything at all. Kgdb + will only actively hook up to the kernel trap hooks if a kgdb I/O + driver is loaded and configured. If you unconfigure a kgdb I/O + driver, kgdb will unregister all the kernel hook points. + + + All drivers can be reconfigured at run time, if + CONFIG_SYSFS and CONFIG_MODULES + are enabled, by echo'ing a new config string to + /sys/module/<driver>/parameter/<option>. + The driver can be unconfigured by passing an empty string. You cannot + change the configuration while the debugger is attached. Make sure + to detach the debugger with the detach command + prior to trying unconfigure a kgdb I/O driver. + + + Kernel parameter: kgdbwait + + The Kernel command line option kgdbwait makes + kgdb wait for a debugger connection during booting of a kernel. You + can only use this option you compiled a kgdb I/O driver into the + kernel and you specified the I/O driver configuration as a kernel + command line option. The kgdbwait parameter should always follow the + configuration parameter for the kgdb I/O driver in the kernel + command line else the I/O driver will not be configured prior to + asking the kernel to use it to wait. + + + The kernel will stop and wait as early as the I/O driver and + architecture will allow when you use this option. If you build the + kgdb I/O driver as a kernel module kgdbwait will not do anything. + + + + Kernel parameter: kgdboc + + The kgdboc driver was originally an abbreviation meant to stand for + "kgdb over console". Kgdboc is designed to work with a single + serial port as example, and it was meant to cover the circumstance + where you wanted to use a serial console as your primary console as + well as using it to perform kernel debugging. + + + Using kgdboc + + You can configure kgdboc via sysfs or a module or kernel boot line + parameter depending on if you build with CONFIG_KGDBOC as a module + or built-in. + + From the module load or build-in + kgdboc=<tty-device>,[baud] + + The example here would be if your console port was typically ttyS0, you would use something like kgdboc=ttyS0,115200 or on the ARM Versatile AB you would likely use kgdboc=ttyAMA0,115200 + + + From sysfs + echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc + + + + + NOTE: Kgdboc does not support interrupting the target via the + gdb remote protocol. You must manually send a sysrq-g unless you + have a proxy that splits console output to a terminal problem and + has a separate port for the debugger to connect to that sends the + sysrq-g for you. + + When using kgdboc with no debugger proxy, you can end up + connecting the debugger for one of two entry points. If an + exception occurs after you have loaded kgdboc a message should print + on the console stating it is waiting for the debugger. In case you + disconnect your terminal program and then connect the debugger in + its place. If you want to interrupt the target system and forcibly + enter a debug session you have to issue a Sysrq sequence and then + type the letter g. Then you disconnect the + terminal session and connect gdb. Your options if you don't like + this are to hack gdb to send the sysrq-g for you as well as on the + initial connect, or to use a debugger proxy that allows an + unmodified gdb to do the debugging. + + + + kgdboc internals + + The kgdboc driver is actually a very thin driver that relies on the + underlying low level to the hardware driver having "polling hooks" + which the to which the tty driver is attached. In the initial + implementation of kgdboc it the serial_core was changed to expose a + 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 call back 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. + + + When using kgdboc with a uart, the uart driver must implement two callbacks in the struct uart_ops. Example from drivers/8250.c: +#ifdef CONFIG_CONSOLE_POLL + .poll_get_char = serial8250_get_poll_char, + .poll_put_char = serial8250_put_poll_char, +#endif + + Any implementation specifics around creating a polling driver use the + #ifdef CONFIG_CONSOLE_POLL, as shown above. + Keep in mind that polling hooks have to be implemented in such a way + 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 + going to mean pressing the reset button. + + + + + Kernel parameter: kgdbcon + + Kgdb supports using the gdb serial protocol to send console messages + to the debugger when the debugger is connected and running. There + are two ways to activate this feature. + + Activate with the kernel command line option: + kgdbcon + + Use sysfs before configuring an io driver + + echo 1 > /sys/module/kgdb/parameters/kgdb_use_con + + + NOTE: If you do this after you configure the kgdb I/O driver, the + setting will not take effect until the next point the I/O is + reconfigured. + + + + + + IMPORTANT NOTE: Using this option with kgdb over the console + (kgdboc) or kgdb over ethernet (kgdboe) is not supported. + + + + + Connecting gdb + + If you are using kgdboc, you need to have used kgdbwait as a boot + argument, issued a sysrq-g, or the system you are going to debug + has already taken an exception and is waiting for the debugger to + attach before you can connect gdb. + + + If you are not using different kgdb I/O driver other than kgdboc, + you should be able to connect and the target will automatically + respond. + + + Example (using a serial port): + + + % gdb ./vmlinux + (gdb) set remotebaud 115200 + (gdb) target remote /dev/ttyS0 + + + Example (kgdb to a terminal server): + + + % gdb ./vmlinux + (gdb) target remote udp:192.168.2.2:6443 + + + Example (kgdb over ethernet): + + + % gdb ./vmlinux + (gdb) target remote udp:192.168.2.2:6443 + + + Once connected, you can debug a kernel the way you would debug an + application program. + + + If you are having problems connecting or something is going + seriously wrong while debugging, it will most often be the case + that you want to enable gdb to be verbose about its target + communications. You do this prior to issuing the target + remote command by typing in: set remote debug 1 + + + + kgdb Test Suite + + When kgdb is enabled in the kernel config you can also elect to + enable the config parameter KGDB_TESTS. Turning this on will + enable a special kgdb I/O module which is designed to test the + kgdb internal functions. + + + The kgdb tests are mainly intended for developers to test the kgdb + internals as well as a tool for developing a new kgdb architecture + specific implementation. These tests are not really for end users + of the Linux kernel. The primary source of documentation would be + to look in the drivers/misc/kgdbts.c file. + + + The kgdb test suite can also be configured at compile time to run + the core set of tests by setting the kernel config parameter + KGDB_TESTS_ON_BOOT. This particular option is aimed at automated + regression testing and does not require modifying the kernel boot + config arguments. If this is turned on, the kgdb test suite can + be disabled by specifying "kgdbts=" as a kernel boot argument. + + + + Architecture Specifics + + Kgdb is organized into three basic components: + + kgdb core + + The kgdb core is found in kernel/kgdb.c. It contains: + + All the logic to implement the gdb serial protocol + A generic OS exception handler which includes sync'ing the processors into a stopped state on an multi cpu system. + The API to talk to the kgdb I/O drivers + The API to make calls to the arch specific kgdb implementation + The logic to perform safe memory reads and writes to memory while using the debugger + A full implementation for software breakpoints unless overridden by the arch + + + + kgdb arch specific implementation + + This implementation is generally found in arch/*/kernel/kgdb.c. + As an example, arch/x86/kernel/kgdb.c contains the specifics to + implement HW breakpoint as well as the initialization to + dynamically register and unregister for the trap handlers on + this architecture. The arch specific portion implements: + + contains an arch specific trap catcher which + invokes kgdb_handle_exception() to start kgdb about doing its + work + translation to and from gdb specific packet format to pt_regs + Registration and unregistration of architecture specific trap hooks + Any special exception handling and cleanup + NMI exception handling and cleanup + (optional)HW breakpoints + + + + kgdb I/O driver + + Each kgdb I/O driver has to provide an configuration + initialization, and cleanup handler for when it + unloads/unconfigures. Any given kgdb I/O driver has to operate + very closely with the hardware and must do it in such a way that + does not enable interrupts or change other parts of the system + context without completely restoring them. Every kgdb I/O + driver must provide a read and write character interface. The + kgdb core will repeatedly "poll" a kgdb I/O driver for characters + when it needs input. The I/O driver is expected to return + immediately if there is no data available. Doing so allows for + the future possibility to touch watch dog hardware in such a way + as to have a target system not reset when these are enabled. + + + + + + If you are intent on adding kgdb architecture specific support + for a new architecture, the architecture should define + HAVE_ARCH_KGDB in the architecture specific + Kconfig file. This will enable kgdb for the architecture, and + at that point you must create an architecture specific kgdb + implementation. + + + There are a few flags which must be set on every architecture in + their <asm/kgdb.h> file. These are: + + + + NUMREGBYTES: The size in bytes of all of the registers, so + that we can ensure they will all fit into a packet. + + + BUFMAX: The size in bytes of the buffer GDB will read into. + This must be larger than NUMREGBYTES. + + + CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call + flush_cache_range or flush_icache_range. On some architectures, + these functions may not be safe to call on SMP since we keep other + CPUs in a holding pattern. + + + + + + There are also the following functions for the common backend, + found in kernel/kgdb.c, that must be supplied by the + architecture-specific backend unless marked as (optional), in + which case a default function maybe used if the architecture + does not need to provide a specific implementation. + +!Iinclude/linux/kgdb.h + + + Credits + + The following people have contributed to this document: + + Amit Kaleamitkale@linsyssoft.com + Tom Rinitrini@kernel.crashing.org + Jason Wesseljason.wessel@windriver.com + + + + + diff --git a/MAINTAINERS b/MAINTAINERS index e46775868019..3eceebb48c92 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2319,6 +2319,12 @@ L: linux-kernel@vger.kernel.org L: kexec@lists.infradead.org S: Maintained +KGDB +P: Jason Wessel +M: jason.wessel@windriver.com +L: kgdb-bugreport@lists.sourceforge.net +S: Maintained + KPROBES P: Ananth N Mavinakayanahalli M: ananth@in.ibm.com diff --git a/include/linux/kgdb.h b/include/linux/kgdb.h index b0985b79b638..9757b1a6d9dc 100644 --- a/include/linux/kgdb.h +++ b/include/linux/kgdb.h @@ -22,31 +22,34 @@ struct pt_regs; -/* - * kgdb_skipexception - Bail out of KGDB when we've been triggered. +/** + * kgdb_skipexception - (optional) exit kgdb_handle_exception early * @exception: Exception vector number * @regs: Current &struct pt_regs. * - * On some architectures we need to skip a breakpoint exception when - * it occurs after a breakpoint has been removed. + * On some architectures it is required to skip a breakpoint + * exception when it occurs after a breakpoint has been removed. + * This can be implemented in the architecture specific portion of + * for kgdb. */ extern int kgdb_skipexception(int exception, struct pt_regs *regs); -/* - * kgdb_post_primary_code - Save error vector/code numbers. +/** + * kgdb_post_primary_code - (optional) Save error vector/code numbers. * @regs: Original pt_regs. * @e_vector: Original error vector. * @err_code: Original error code. * - * This is needed on architectures which support SMP and KGDB. - * This function is called after all the secondary cpus have been put - * to a know spin state and the primary CPU has control over KGDB. + * This is usually needed on architectures which support SMP and + * KGDB. This function is called after all the secondary cpus have + * been put to a know spin state and the primary CPU has control over + * KGDB. */ extern void kgdb_post_primary_code(struct pt_regs *regs, int e_vector, int err_code); -/* - * kgdb_disable_hw_debug - Disable hardware debugging while we in kgdb. +/** + * kgdb_disable_hw_debug - (optional) Disable hardware debugging hook * @regs: Current &struct pt_regs. * * This function will be called if the particular architecture must @@ -59,7 +62,14 @@ struct tasklet_struct; struct task_struct; struct uart_port; -/* To enter the debugger explicitly. */ +/** + * kgdb_breakpoint - compiled in breakpoint + * + * This will be impelmented a static inline per architecture. This + * function is called by the kgdb core to execute an architecture + * specific trap to cause kgdb to enter the exception processing. + * + */ void kgdb_breakpoint(void); extern int kgdb_connected; @@ -102,7 +112,7 @@ struct kgdb_bkpt { * Functions each KGDB-supporting architecture must provide: */ -/* +/** * kgdb_arch_init - Perform any architecture specific initalization. * * This function will handle the initalization of any architecture @@ -110,7 +120,7 @@ struct kgdb_bkpt { */ extern int kgdb_arch_init(void); -/* +/** * kgdb_arch_exit - Perform any architecture specific uninitalization. * * This function will handle the uninitalization of any architecture @@ -118,7 +128,7 @@ extern int kgdb_arch_init(void); */ extern void kgdb_arch_exit(void); -/* +/** * pt_regs_to_gdb_regs - Convert ptrace regs to GDB regs * @gdb_regs: A pointer to hold the registers in the order GDB wants. * @regs: The &struct pt_regs of the current process. @@ -128,7 +138,7 @@ extern void kgdb_arch_exit(void); */ extern void pt_regs_to_gdb_regs(unsigned long *gdb_regs, struct pt_regs *regs); -/* +/** * sleeping_thread_to_gdb_regs - Convert ptrace regs to GDB regs * @gdb_regs: A pointer to hold the registers in the order GDB wants. * @p: The &struct task_struct of the desired process. @@ -143,7 +153,7 @@ extern void pt_regs_to_gdb_regs(unsigned long *gdb_regs, struct pt_regs *regs); extern void sleeping_thread_to_gdb_regs(unsigned long *gdb_regs, struct task_struct *p); -/* +/** * gdb_regs_to_pt_regs - Convert GDB regs to ptrace regs. * @gdb_regs: A pointer to hold the registers we've received from GDB. * @regs: A pointer to a &struct pt_regs to hold these values in. @@ -153,7 +163,7 @@ sleeping_thread_to_gdb_regs(unsigned long *gdb_regs, struct task_struct *p); */ extern void gdb_regs_to_pt_regs(unsigned long *gdb_regs, struct pt_regs *regs); -/* +/** * kgdb_arch_handle_exception - Handle architecture specific GDB packets. * @vector: The error vector of the exception that happened. * @signo: The signal number of the exception that happened. @@ -175,7 +185,7 @@ kgdb_arch_handle_exception(int vector, int signo, int err_code, char *remcom_out_buffer, struct pt_regs *regs); -/* +/** * kgdb_roundup_cpus - Get other CPUs into a holding pattern * @flags: Current IRQ state * @@ -198,7 +208,7 @@ extern int kgdb_validate_break_address(unsigned long addr); extern int kgdb_arch_set_breakpoint(unsigned long addr, char *saved_instr); extern int kgdb_arch_remove_breakpoint(unsigned long addr, char *bundle); -/* +/** * struct kgdb_arch - Describe architecture specific values. * @gdb_bpt_instr: The instruction to trigger a breakpoint. * @flags: Flags for the breakpoint, currently just %KGDB_HW_BREAKPOINT. @@ -227,7 +237,7 @@ struct kgdb_arch { void (*correct_hw_break)(void); }; -/* +/** * struct kgdb_io - Describe the interface for an I/O driver to talk with KGDB. * @name: Name of the I/O driver. * @read_char: Pointer to a function that will return one char. -- 2.34.1