Documentation of the protected mode debugger

Introduction

Features and Capabilities

• Is bootable from a floppy into protected mode.
• The user can load his program from a floppy or can directly key in the hex code.
• It allows one to trace or run a program.
• It catches exceptions and faults thrown by the processor while running the user code, this helps in debugging greatly.A register dump is provided telling the user where exactly the fault occured.
• It provides a person with an interface similar to the debug dos program and has similar commands like to change registers,dump them,dump or fill memory , trace and run till a specified instruction.For a detailed listing , click here
• Implements scrolling , ie a person can scroll the screen to know past history.

System Requirements

Starting up the debugger

• In Linux dd if=<pathToImage> of=/dev/fd0 bs=1.
• In Windows: You can use the freely available RawWrite program to do this.(More instructions on how to use it can be found on its site.)

Usage guidelines and a brief tutorial

Design and Implementation overview

Development Environment and Languages Used

• C code is a lot more readable , easy to understand and maintain than asm .
• I do not use any libraries , even printf and scanf that I use are my own , so there is absolutely no overhead , no dependencies involved. The code uses pure ANSI C .
• Since a large part of the code , sets up appropriate data structures , I have used C because it is easier to interpret that as a struct , whereas in asm , it will look like some meaningless moving of bytes here and there.

Concepts involved

• Protected mode intel 386 programming
  The authoritative source for this would be Volume 3 of the intel 386 manual(Download).For a list of comprehensive online references , check out this
• Assembly coding , I have used nasm . For those who do not know , nasm is a linux clone for the Microsoft assembler , masm , available on dos systems.
• Periphral specific drivers information
  • PIC: Or the programmable interrupt controller, This is useful to understand how interrupts are controlled .
  • intel FDC controller : To understand how the floppy driver can be written.
  • intel 8042 , keyboard controller

Module Description

1. Boot Up Module
2. Kernel Proper
3. Device Drivers
4. Debugger Module

Bootup Module details

• bootsect.s : This is executed in real mode , and is found on the first sector of the floppy image ,It is placed by the bios at memory location 0x7c00 .It proceeds to load the kernel into the main memory using bios routines to read the floppy. It then transfers control to the setup routine , which prepares the system for switch to protected mode.
• setup.s : The setup code , sets up the initial gdt ,idt and enables the A20 gate to go into protected mode . The pic is then reprogrammed to shift the irq's to after the processor interrupts. The switch to protected mode is done by setting the 0th bit in CR0 register , then doing a far jump to reload the segment registers with appropriate protected mode values. Interrupts are disables , and the pic is asked to mask all interrupts .It then jumps to the kernel entry point , which is the Main function found in main.c .

Kernel Proper module details

• main.c : This is the kernel entry point , it sets up the IDT,GDT,LDT, Sets up the memory manager , initializes keyboard,console , floppy driver and other functions like printk etc which require initialization. The pic is then told to allow only keyboard interrupts , other interrupts like floppy and timer (pit) are enabled and disabled as needed. Also it initializes the kernel TSS . (which will be used later to transfer control to the kernel by the debugger interrupt). After doing all this , interrupts are enabled and the control is passed on to the debugger .
• descriptor.c , idt.c ,tss.c : Initialization and helper routines for accessing the GDT,TSS,IDT .
• alloc.c : the kernel page based memory manager , it handles dynamic allocation of memory in units of a page size (4k).
• printk.c : Implements the printk ,scanf and gets functions which are used thruout for console I/O .
• int.s : This contains the various interrupt routines for floppy , debugger, keyboard , timer.
• asm.s : This file contains all the low level assembly code neccessary for interfacing with the various devices and the processor.Again inline assembly was not used for reasons of portability , although that would have been faster.

Device drivers module

• Save State
• Switch to kernel ds ,cs
• Call the main interrupt routine handler of that particular device , eg : doDebuggerInt() or the doKeyboardInterrupt() .
• Send an EOI to the pic , to unmask that interrupt
• Restore state and do an iret.

• Keyboard Driver :In file keyboard.c The keyboard driver is a simple circular queue , where when a key is pressed , the keyboard interrupt handler calls the enque method , and to retrieve a key , I just deque it.
• Console Driver : In file console.c , It does the following :
  
  • Keeps track of the cursor position and scrolls if neccessary , it also keeps updating the cursor position in the video controller .
  • The string to be printed is just put into the video memory starting at the current cursor location
  • Also maintains a history of four pages and implements scrolling , by acting the ctrl+U ,ctrl+D keys
• Floppy Driver : In file floppy.c , It does the following :
  • Sets up dma for data transfer
  • enables the floppy interrupt
  • recalibrates the drive if neccessary
  • Sends commands to the disk controller to read/write a sector
  • Handles floppy driver errors , like wrong seeking etc , by retrying

Details on the debugger implementation

• Command Input Loop : This essentially waits for user command by calling a gets function to the console driver and then acts on the command . It calls functions like run(),loadProgram(),setTraps(),setBreakPoint() etc , in response to the commands .
• Int 1 : Interrupt 1 is the debug exception interrupt that the processor raises in response to trace or when a breakpoint is reached ,It's code is contained in int.s
  Int 3 : Interrupt 3 on the other hand is raised in case of a software breakpoint (the int 3 instruction or the one byte opcode 0xCC) .Whenever a processor finds this opcode as the first byte of the currently decoded instruction , this handler is invoked. Infact this has how the debugger invokes the runTill command, it just replaces the first byte of the instruction to run till to with the opcode 0xCC , the int 3 handler is invoked and in addition to the following steps , replaces the saved original byte that existed.
  Both the debugging interrupt handlers are pretty similar and this is what is exactly done :
  • Saves State on state
  • Moves to the kernel ds and cs
  • Saves the linear address of ss:esp into a variable , this then points to the saved state of the user program on the stack. And can later be used for modifying his registers .
  • Calls a function doDebuggerInt
  • Pops (restores) state followed by an iret.
• A note on the saved state The thread state is initially stored in its task state segment , later when a interrupt occurs (for example the int 1) ,all the registers including the segment selectors are saved on the stack(except the eip,cs,ss,sp,eflags) .These four registers are not saved by us , as they are already saved by the 386 when an interrupt occurs , however the complications are :
  • If a stack switch does not occur ss and esp (original stack's) are not stored
  • Some interrupts push a error code , so the exact of offsets of the saved eip,cs,ss,eflags,sp is dependant on which interrupt occured and whether a stack switch occured.
  A stack switch will occur if the cpl of the running program was not equal to 0(the kernel priv level). For the error codes , we simply know which interrupts give error codes and hence can go ahead and calculate the offsets of these ss,esp,eip,cs,eflags.The funx doing this is called doFullSaveState in debugger.c.
  Also note that initially when a program is launched it takes its values from those stored in its TSS, whereas otherwise when an interrupt occurs it takes the values stored in the ring 0 stack as detailed above.For this purpose we need a variable which can tell us wether we are returning from an interrupt handler or have yet to launch the user program , this variable is called fromThread and is set in the doFullSaveState function.
• DoDebuggerRoutine This routine is contained in debugger.c . It switches the processor back to the kernel state , ie switches to the kernel , the details of this operation are described later.
  
  

• The program is read from the specified floppy location
• Memory is allocated for the program's stack ,code,data .
• 16k is allocated for each of the code/data/stack and 64k for the extended data segment(eds) .Segment Selectors for these point into the LDT where the descriptors for these segments are created.
• Once all the memory is allocated , the TSS of the program is created , in which the registers are initialized to 0 ,the esp to the highest address in the user stack segment.
• The TSS descriptor is created in the GDT , and is made to point to the TSS structure created above. Note that we allocate one PAGE_SIZE ( 4k ) bytes for the TSS structure , however the tss struct occupies only 104 bytes , so we use the lower part of this memory as a ring 0 stack ( this is the stack , the cpu will switch to this stack if an interrupt occurs) , this explains why the esp0 is set to (PAGE_SIZE).Hence the ring0 stack to which which the cpu switches in case of interrupt is specified in the tss .
• To run the program , we simply do a task switch specifying this program TSS created above. This way the cpu automatically stores the kernel context (useful later )

Compiling it from the source

• tar zxf vXX.tar.gz : where vXX.tar.gz is the name of the downloaded archieve.This would create a directory called prodebug in your current directory.
• cd prodebug:Enter the prodebug directory
• make