=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  File:      README
  Creator:   Matt Bogosian <mbogosian@usa.net>
  Copyright: (c)1998, Matt Bogosian. All rights reserved.
  Description: README for the kdbg device driver and related items.
  ID:        $Id: README,v 1.21 1998/06/05 19:11:47 mattb Exp $
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

NAME
	kdbg - device driver to define /dev/kdbg.
	kdbg.sh - shell script to provide a convenient command line
		interface to /dev/kdbg and /dev/dprintf.

SYNOPSIS
	kdbg.sh [ -0 | -1 ] [ -e -n ] ARGS ...

DESCRIPTION
	kdbg defines a device driver to be accessed at /dev/kdbg. The
	behavior of the device is quite simple. After opening the device
	reading and writing may occur.
	
	One byte can be read from the device at offset 0. This byte will
	have one of two values. If debugging output is currently turned
	off, the byte will have a value of 0x30 (the ASCII value of the
	character, '0'); if it is on, the byte will have a value of 0x31
	(the ASCII value of the character, '1'). These values can be
	verified by typing "echo `cat /dev/kdbg`".
	
	One byte can be written to the device at offset 0. Debugging
	output can be turned on or off depending on the value of this
	byte. If either 0x30 (the ASCII value of the character, '0') or
	0x00 is written to the device, debugging output will be turned
	off; if either 0x31 (the ASCII value of the character, '1') or
	0x01 is written to the device, debugging output will be turned
	on. This can be verified by typing "echo -n # >/dev/kdbg", where
	'#' represents either a 0 or 1.
	
	kdbg.sh is a convenient and user-friendly way of turning on and
	off debugging output. It also has the ability to send strings to
	the debugger via the /dev/dprintf device. kdbg.sh behaves
	similarly to the echo command line program with the addition of
	two options to enable/disable debugging output (see OPTIONS
	below).
	
	To make the device driver, just type "make". To install the items
	in the appropriate places, just type "make install". This copies
	the kdbg device driver to the ~/config/add-ons/kernel/drivers
	directory and the kdbg.sh shell script to the ~/config/bin
	directory.

OPTIONS
	-0
		Turn kernel debugging output off.
	
	-1
		Turn kernel debugging output on.
	
	-e
		Interpret various escaped characters when echoing to
		/dev/dprintf (a la echo -e).
	
	-n
		Don't add a newline when echoing to /dev/dprintf (a la
		echo -n).

EXAMPLES
	Turn off debugging output:
		kdbg.sh -0
	or:
		echo -n 1 >/dev/kdbg
	
	To turn on debugging output and output "I am" without a trailing
	newline:
		kdbg.sh -1 -n I am
	or:
		echo -n 1 >/dev/kdbg
		echo -n I am >/dev/dprintf
	
	To output only the ASCII character represented by the octal code
	'060':
		kdbg.sh -e -n \\060
	or:
		echo -e -n \\060 >/dev/dprintf

TEST NOTES
	The device driver and shell script were created and tested
	extensively with BeOS R3 on a PowerBase 180 with 24 MB of RAM.
	Stability was maintained after installing the driver. Rebooting
	the machine did not result in a decrease of stability.

FILES
	The following files are included:
		Makefile - makefile for kdbg.
		README - this file.
		kdbg.cpp - source file containing the hook functions for
			the kernel-loadable device driver.
		kdbg.sh - shell script to provide a convenient command
			line interface to /dev/kdbg and /dev/dprintf.

BUGS
	The device may get confused if other things are turning debugging
	output on and off, but there are no known destructive bugs.

DIAGNOSTICS
	The following list contains the exit codes and meanings for
	kdbg.sh.
		
	An exit status of 0 indicates a successful operation.
	
	An exit status of -1 a command line parsing error of some kind.
	
	An exit status of -2 indicates an execution error of some kind.
