-------------------------------------------------------------------------------
Description
===========

The RDP (Remote Debug Protocol) assumes that the communications
channel has some form of hardware flow control. The host will send
multi-byte packets to the C-Demon debug target without any
acknowledgement processing between the bytes. If the C-Demon is being
ported to a system that uses serial communications for the debug
channel, and hardware flow-control is NOT available then care must be
taken to ensure that the C-Demon target is always ready to accept
bytes from the host to avoid overflow. At its simplest this is
achieved by ensuring that the baud rate is sufficiently slow for both
ends to respond to and process a character before the next arrives.

-------------------------------------------------------------------------------
Source and build structure
==========================

The source is constructed quite simply at the moment. All the generic
C-Demon source is at the top, with sub-directories being used to hold
the target specific source and header files.

Each target should provide at LEAST the following files:

	driver.c
	  This is the main C-Demon debug channel support file. It
	  should provide the routines described in the "Functions"
	  section below (as used by the generic C-Demon source),
	  aswell as any target specific support routines,
	  e.g. interrupt handlers, MMU initialisation, etc.

	driver.h
	  This header file should provide any declarations required to
	  support the "driver.c" sourcefile.

	driver_h.s
	  Should provide the standard MACROs (described below) aswell
	  as the following manifests:
	    ARMVSN	ARM processor version number for hardware
            BOARD	textual description of the hardware
	    NUMIRQS     number of individual IRQ sources
	    NUMFIQS	number of individual FIQ sources

If required the Makefile can be updated to add other target specific
files held in the relevant sub-directory to the build for that target.

-------------------------------------------------------------------------------
Functions
=========

const char *ResetDriver(void)
	This is the main communications channel initialisation
	routine. It should initialise the target hardware such that
	subsequent calls to GetByte, AnyByte and PutByte will work.

void DriverSpeed(int baud)
	This routine should accept a standard RDP baud rate
	descriptor, and change the debug channel baud rate
	accordingly. If the debug channel does not have the concept of
	a baud rate then this function need do nothing.

unsigned char GetByte(void)
	Get a byte from the debug host. This routine will block
	(i.e. poll) until a byte is available.

int AnyByte(void)
	Check if a byte from the debug host is available. A suitable
	boolean is returned depending on the availability of a
	character.

void PutByte(unsigned char c)
	Block, writing the given character to the debug host.

void SetLEDs(char LED)
	If the target hardware supports some debug LEDs, then reflect
	the bitmask status of the given value on the LEDs.

-------------------------------------------------------------------------------
MACROs
======

The following assembler macros are used within the exception
(including SWI) handling and breakpoint support code parts of
C-Demon. They allow the lo-level code to control the interrupt used by
the host debugger ctrl-C event (whilst the target application is
executing). They are provided in the target/hardware specific
assembler header file "driver_h.s", since different architectures may
choose to implement different parts of the set:

	STARTUPCODE
		This macro is placed at the start of the generic
		C-Demon initialisation code. It should deal with any
		target specific startup requirements. e.g. mapping RAM
		to address zero, initialising memory access hardware,
		etc.

	INITMMU
		This macro should perform any MMU initialisation
		required (if any) for the target hardware. Normally
		this will just perform a call to a target specific
		function that will perform the necessary setup.

	INITTIMER
		This macro should perform the timer initialisation
		required to ensure that a 10mS timer interrupt can be
		provided to C-Demon if it requires.

	IRQVECTORS
		This macro is used to introduce the table of IRQ
		interrupt handlers provided by the base C-Demon
		code. The number of table entries should reflect the
		NUMIRQS number of individual IRQ sources on the board.

	FIQVECTORS
		This macro performs the same job as the IRQVECTORS
		macro for the NUMFIQS sources provided for the FIQ
		vector on the target hardware.

	PRIVATEINTERRUPTS
		A holding place for system specific assembler
		interrupt handlers referenced from the IRQVECTORS or
		FIQVECTORS tables. This just allows target specific
		assembler functions to be added into the C-Demon
		interrupt support world.

	getIRQsource
		This macro is referenced from the generic C-Demon
		interrupt handling. It should return the target
		specific value to be used by the decodeIRQ macro to
		identify a particular IRQ source to be
		processed. Note: If multiple IRQ sources are active
		then the decodeIRQ macro should perform some form of
		interrupt prioritisation.

	decodeIRQ
		Used in conjunction with the getIRQsource macro to
		find and decode the active IRQ source for the given
		hardware system. The result of this macro should be an
		index into the IRQ vector table declared in the
		IRQVECTORS macro.

	getFIQsource
	decodeFIQ
		These macros provide the same functionality for FIQ as
		the getIRQsource and decodeIRQ macros described above.

	stopCTRLC
		This macro stops the RDP channel from generating an
		interrupt. When C-Demon has control the communications
		are polled across, and the target architecture debug
		channel interrupts are not enabled. However to allow
		ctrl-C to be used asynchronously when the target
		application is executing requires an interrupt.

	allowCTRLC
		This macro provides the other side to "stopCTRL", in
		that it enables the RDP debug channel interrupt.

	dropRTS
		This allows the SWI and breakpoint code to de-assert
		RTS to stop the host debugger transmitting any more
		RDP bytes, until the C-Demon RDP handling system is
		ready.

-------------------------------------------------------------------------------
