%Debugging
%Thadeu Cascardo

# Introduction

There are many debug infrastructure and support in Linux. We are going to look
at some of them, including:

* printk
* procfs
* debugfs

We are also going to point out at some documentation for other debug support.

# printk

printk adds messages to the kernel log system. It may be read by the syslog
syscall (klogctl in glibc). It's also present in /proc/kmsg and is usually read
by klogd.

The *dmesg* program may be used to read these log messages. It's usually asked
for in bug reports.

# printk log levels

dmesg may configure which levels are output to console. Those log levels are
also used by the syslog daemon to filter what messages go where.

/proc/sys/kernel/printk shows the current console loglevel, the default level
(for messages that miss the level), the minimum level and the boot time console
loglevel.

# Log levels

The following macros are used for log levels in printk:

* KERN\\_EMERG
* KERN\\_ALERT
* KERN\\_CRIT
* KERN\\_ERR
* KERN\\_WARNING
* KERN\\_NOTICE
* KERN\\_INFO
* KERN\\_DEBUG

# Rate limiting

You may limit the rate of the messages printed.

* printk\\_once
* You may test for printk\\_ratelimit
	- limits to *burst* messages in *interval* seconds
* Default burst is 10 times in 5 seconds
* /proc/sys/kernel/printk\\_ratelimit*
* printk\\_ratelimited uses only the default values

# printk macros

* pr\\_emerg
* pr\\_alert
* pr\\_crit
* pr\\_err
* pr\\_warning
* pr\\_notice
* pr\\_info
* pr\\_debug - only if DEBUG macro defined or with dynamic\\_debug
* pr\\_devel - only if DEBUG macro defined

# Printing from device drivers

* include linux/device.h
* dev\\_printk(level, device, fmt, ...)
* dev\\_*
* dev\\_warn and not dev\\_warning
* dev\\_dbg - only if DEBUG macro defined or with dynamic\\_debug

# Defining the DEBUG macro

Let's take a look at an example of defining the DEBUG macro for some code and
allowing the user to configure it.

* drivers/usb/core/Kconfig
* drivers/usb/core/Makefile

# Dynamic debug

* Allow developers or users to filter debug messages by subsystem, file and line
* CONFIG\\_DYNAMIC\\_DEBUG should be defined
* Depends on DEBUG\\_FS
* Documented in the Kconfig help at lib/Kconfig.debug
* Also documented at Documentation/dynamic-debug-howto.txt

# Proc filesystem

The proc filesystem has a use of its own, allowing user space to get
information about processes and other system configuration as well as to
change those configuration items.

However, it may be used for debugging too. In fact, developers usually
request information from /proc/, when trying to find a solution for a
reported bug.

# Creating a proc file

* include linux/proc\\_fs.h
* struct proc\\_dir\\_entry
	- proc\\_fops
	- data
* create\\_proc\\_entry(name, mode, parent) is racy
* Use NULL parent to create a file in the proc root
* proc\\_create(name, mode, parent, fops) is not racy
* proc\\_create\\_data(name, mode, parent, fops, data)

# Removing a proc file and creating directories

* remove\\_proc\\_entry(name, parent)
* proc\\_mkdir(name, parent)
* proc\\_mkdir\\_mode(name, mode, parent)

# seq\\_file