After the list of flags is the beginning of a general discussion of
porting CDB to new systems and environments.

COMPILE TIME FLAGS
These are the compile-time flags that can be set to affect how CDB works.  
The value column shows the legal range of values.  The construct (a | b)
indicates that one of the set {a,b} is needed and that 'a' is the default
if left unspecified.  The value "--auto--" indictaes that the flag is
automatically derived from other values.

The lists for OS, CPU, MFG, etc. are in config.h.  If you need to add
something, let us know so it can be added to the master copy.

Name		Value(s)	Explanation
-------------	------------	--------------------------------------------
CDB_DEBUG	(0 | 1)		Used to #if certain pieces of code. (obsolete)
SYS		from SYS list	Unique name specifying a particular
				implementation.
OP_SYS		from OS list	Operating system CDB is running under.
REMOTE_OS	from OS list	OS for target. Defaults to OP_SYS.
ANY_BSD		--auto--	Indicates OS is a Berkely derivative.
CPU		from CPU list	Machine target is running on.
HOST_CPU	from CPU list	Machine CDB is running on. Defaults to CPU.
MFG		from MFG list	Manufacturer of Host/Remote system.
COMPILER	from list	Specifies compiler peculiarities (e.g. Green
				Hills register saving).
LANG_C		(1 | 0)		Include C language routines.
LANG_FORTRAN	(0 | 1)		Include FORTRAN language routines.


These two are used only in compiling "dummy.c"

REMOTE		(0 | 1)		Loaded with real remote routines, not dummies.
WINDOWS		(0 | 1)		Loaded with real window routines, not dummies.


These flags are normally set in the CPU default section in config.h.

BPT_INST	value		Breakpoint instruction.
BPT_BACKUP	(0 | 1)		PC must be backed up to point at BPT.
CALLEE_STACK_CLEANUP (0 | 1)	Calle does stack cleanup
FPISAP		(0 | 1)		Frame ptr and Argument ptr are the same.
LONGLONG	(0 | 1)		System has type (long long).
REGT		(unsigned int)	An unsigned type the same size as a register.
BYTE_SEX    byteSex{Little,Big}	E.g. Vax == Little, 68000 == Big
BIT_SEX      bitSex{Little,Big}	E.g. Vax == Little, 68000 == Big
ALIGNMENT	(0,1,3)		Alignment mask for 4 byte integers
				0 = On any byte address
				1 = On any EVEN address
				3 = On any FOUR BYTE address


These flags are highly system dependent.

INTEGER_OFFSETS	(0 | 1)		Param offsets in symtab are a little off.
V7_PRINTF	(0 | 1)		Host system printf does not support "%#x".
ADR_USER	(adrNil)	Base address of struct user in KERNEL space.
ADR_REG0	(adrNil)	Offset of register 0 from ADR_USER.
ADR_U_AR0	(adrNil)	Offset of u.u_ar0.
LOCAL_COMM_INIT	(0 | 1)		Local init/handshake for remote comm.
ADR_TEXT_BASE	0		Lowest address user programs are loaded at.
ADR_PROC_BASE	0		
CLEAR_FP	(1 | 0)		Set FP to 0 on creation of new child.
ADR_START_LOW	(adrNil)	First address of start frame.
ADR_START_HIGH	(adrNil)	Last address of start frame + 1.
TRAMPOLINE	(0 | 1)		Siganl handling uses trampoline code


These flags are defaulted based on OP_SYS. HOWEVER(!), they tend to be
*massively* system dependent.  You must have the correct definitions
for EXEC_F1,B1,E1 for CDB to work at all. EXEC_F2,B2,C2 allow you
to look at initialized globals when there is no child and no core.
The CORE values are necessary only if you can/want to look at core files.

EXEC_B1		Lowest text address
EXEC_E1		Highest text address + 1
EXEC_F1		File address of byte with address EXEC_B1
EXEC_B2		Lowest data address
EXEC_E2		Highest data address + 1
EXEC_F2		File address of byte with address EXEC_B2

CORE_B1		Lowest data address
CORE_E1		Highest data address + 1
CORE_F1		File address of byte with address CORE_B1
CORE_B2		Lowest stack address
CORE_E2		Highest stack address + 1
CORE_F2		File address of byte with address CORE_B2

TXTRNDSIZ
cbCodeOffset
cbStorageMax
INT_16
N_DATADDR
DEBUG


These flags are normally specified in the appropriate CPU module.
If one is DEFINED, then the corresponding routine will NOT be compiled
in the module "cpulib.c". 

If DEFINED			You have a special routine to
------------------		-----------------------------------------------
X_InitRegisters			Initialize register array.
X_InitSpecials			Initialize "system special" variables.
X_ListRegisters		  	List of register array.
X_GetByte			Get a byte.
X_PutByte			Put a byte.
X_GetBlock			Get a block.
X_PutBlock			Put a block.
X_GetReg			Get a register.
X_PutReg			Put a register.
X_ReadPc			Read the PC and setup magic values.
X_SetCntx			Create the pr->cntx record.
X_SaveState			Save register state.
X_RestoreState			Restore register state.
X_MoveBytes			High speed memory-to-memory block copy.
X_ValFReg			Get a typed register.
X_StoreReg			Put typed register.
X_ValFUser			Get a typed struct user field.
X_StoreUser			Put typed struct user field.
X_InstallBp			Install breakpoints.
X_RemoveBp			Remove breakpoints.
X_GetArgN			Get the Nth argument of a proc w/o symbols.
X_DispUnknown			Display the frame for a proc w/o symbols.
X_FixPc				Fix the PC after a breakpoint.
X_FinishCpu			Cleanup on debugger shutdown.
X_InitCpu			Setup the CPUR record.

These are used for procedure call from the command line.
If DEFINED			You have a special routine to
------------------		-----------------------------------------------
X_SavePcFp			Create magic frame on stack.
X_SetCallProc			Set all registers, push arguments.
X_CallProcedure			Actually do the call.
X_SeFReturn			Extract the return value from whereever.




Porting CDB should prove to be substantialy easier than porting other
debuggers.  This is largely due to the fact that it already has been
ported to over 50 systems.  These systems vary in minor and major ways.
Whenever we have encountered a difference, we have striven to understand
what the general solution was and recoded for that case.

The debugger is composed of 5 major subsections:

    1. The Central Debugger is that code that seems to be independent
	of everything else.
    2. The cpu modules contain code specific to a given architecture.
    3. The os modules contain code specfic to a given operating system.
    4. The communication method used to control the target process.
    5. The wait modules "wait" differently for single process and
	multiprocess situations.


Porting to a New System 

The best approach to bringing the debugger up in a new environement is to
look at the options currently available and pick those that are closest
to the new situation.  For example, when we did the NSC 32000 port, we
already had the VAX port done.  Since the 32000 is closer in many ways
to a VAX than it is to a 68000, we started with the cpuVax module and
hacked it from there.  We also started with the SYS.h info for a VAX and
modified as necessary to produce the SYS.h info for the 32000.


Tweaking an Existing Port

Given the growing number of machines that CDB already works with, it is
more likely that all the pieces you need are in place, but some of the
values (or equations) being used are not correct for your system.  For
example, I have yet to see two 68000 systems (either BSD or System V)
that have the same ADR_TEXT_BASE (the lowest address that user code
is normally loaded at).  Another value that seems to change a lot is
ADR_USER (the base address of "stuct user u" in the kernel).



