Diagnosys Setup

Tip This document explains what the Diagnosys patch provides as functionnalities and how to set up the system. If you’re new to Kernel compilation, you should find the steps described in this page sufficient to compile a vanilla kernel.

1. The Diagnosys runtime system

The kernel patch that provides support for Diagnosys modifies a limited set of files, included Kernel configuration file Kconfig, the implementation of Kexec and the Syscall_table, and adds the module components for Diagnosys.

Kernel version

The provided patch is for Kernel version 2.6.32, which is the kernel version of the current Long Term Support release of the popular Ubuntu Distribution as well as Debian. Nevertheless, the details on the patch contents below should allow anyone who wishes to adapt the patch for other kernel versions.

2. Patch contents

2.1. Kconfig

Diagnosys relies on Kexec to fast reboot without overwriting the reserved area of the RAM where the log is supposed to be stored.

To avoid inconsistency during execution, a dependancy is added between CONFIG_DLOG and CONFIG_KEXEC. We also select the configuration options for detecting hanged tasks and panicking if need be (DETECT_HUNG_TASK & BOOTPARAM_HUNG_TASK_PANIC).

2.2. Diagnosys logging primitive

The main Diagnosys component implements a logging mechanism using a circular buffer to write in a reserved area of the memory. This component exports some functions for use by other kernel modules, including out-of-tree kernel modules. These functions include the function Diagnosys_log which is called in all wrappers of the debugging interface.

2.3. Diagnosys system call

The reserved area of the memory must be indicated to the Diagnosys component. The relevant information beeing retrieved from the kernel boot command line (/proc/cmdline), it is transfered to the kernelspace through a dlog_set_memory syscall implemented by Diagnosys.

2.4. Dlog driver for displaying log

The log stored in the reserved area of the RAM is directly accessible through a virtual device (/dev/dlog). The Diagnosys patch implements a char device driver that can process commands for starting and stopping the logging process and for retrieving the log (with a simple cat command).

3. Quick Steps for Kernel Compilation (with Debian or Ubuntu)

To quickly compile a vanilla kernel and patch it to support Diagnosys, use the following steps :

  • Download a kernel source archive at kernel.org. In this case, download 2.6.32.

  • Bunzip and untar the kernel tar.bz2 file, and apply the patch (patch -p1 < 'path to Diagnosys_patch')

  • To avoid struggling with config options, copy your current configuration file in the vanilla kernel (cp /boot/config-$(uname -r) .config)

  • Enable Diagnosys by selecting CONFIG_DLOG with make menuconfig or make xconfig

  • Compile and create debian packages with make-kpkg --initrd --append-to-version=-custom kernel_image kernel_headers

  • Install the deb packages with dpkg -i 'deb file' for linux-image and linux-headers

  • Create the initial ram-based filesystem with update-initramfs

  • Update the grub

  • Reboot the kernel and choose the newly installed kernel

Tip Don’t forget to edit the command line to reserve memory using memmap. The commands memmap=255M@0M memmap=2G@256M leaves 255MB of memory to be mapped by the kernel, then leaves 1MB unmapped and maps 2GB starting at 256MB. It therefore allows to reserve 1MB of memory in the low memory area of RAM. You can directly add the boot command parameters in your kernel menu entry in grub configuration file. See more documentation on memmap here.