'\"macro stdmacro
.TH dgInitComm 3p
.SH NAME
dgInitComm\- connects host side diagnostic to target system.
.SH DEFINITION
This function sets up the connection between the host side application (the
diagnostic) and the debug monitor running on the target system.  Requests to
read and write the target system's memory may then be issued with the 
.I dgWriteMem()  
or
.I dgReadMem()  
function calls.
.P
.I dgInitComm()
initializes the data structures used internally
by the libdg library (where the dgXXX routines reside), so that a 
connection between the host side diagnostic & the debugger running on the
target system can be made.  Depending on the communication type parameter
specified by the caller, different types of target system communication
may be set up.
.P
Communication links may be established between the host side diagnostic and:
.nf

the "rmon" debugger thread of the running application,
a verilog simulation of the target system,
a tiny debug monitor resident in one of {PIF, IMEM, DMEM, or RDRAM}.
.fi
.P
We can use the standard debugger thread "rmon", by establishing a
socket connection between the host side diagnostic and the host side debugger 
daemon "dbgif", whenever the first read or write request from the diagnostic
comes is made.  Thereafter, the existing socket interface will be used so that
"dbgif" may transfer messages to, and receive messages from, the target side 
debugger monitor thread "rmon".
.P
This debugging monitor thread on the target system will ultimately be part
of any application running on the target system that bundles in the
debugger. In the event that the application hangs (but the debugger thread 
is still active), we may be able to run some simple diagnostics to dump out 
the state of the system using the rmon thread of the (running) application.
.P
Prior to bringup, we will utilize the dbgif protocol & talk to a debugging
agent that knows how to make I/O requests to and from the verilog model of the
RSP, simv.ipc.
.P
For initial bringup, we will utilize a tiny monitor and bypass the dbgif
server alltogether; dgInitComm will reset the system, download the monitor,
and release reset (at which point the monitor program will bootstrap itself
from GIO ramrom into the location specified by the global ide variable 
.I commtype.
.P
.I commtype 
may be set from the ide command line to one of the following values 
(as defined in dbg_comm.h):
.nf

 1	DG_VERILOG		(simulation with verilog host model)
 2	DG_TINYMON_PIF	(tiny monitor resident in PIF rom)
 3	DG_TINYMON_IMEM	(tiny monitor resident in RSP's IMEM)
 4	DG_TINYMON_DMEM	(tiny monitor resident in RSP's DMEM)
 5	DG_TINYMON_RDRAM(tiny monitor resides in RDRAM)
 6	DG_RMON		('rmon' debugger is presumed loaded)
 7	DG_RMON_RESET	('rmon' debugger is loaded on your behalf)
.fi
.P
Note that you cannot use symbolic constants when setting the ide variable; use
the numeric values in the left most column from the table above when setting
the 
.I commtype 
variable.
.P
The current default value for 
.I commtype 
is DG_VERILOG.
.P
Only the DG_TINYMON communication types will cause 
.I dgInitComm()
to reset the target system and download the debugging monitor.
.P
For DG_VERILOG, the user must start up the three host side processes
simv.ipc, dbgif, and vermon (in that order) prior to running the diagnostic.
.SH C SPECIFICATION
.nf
int dgInitComm()
.fi
.RS
.SH PARAMETERS
none.
.SH VALUE RETURNED
1 if an error occurred; 0 otherwise.
.SH INCLUDES
.nf
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <unistd.h>
#include <netinet/in.h>
#include <bstring.h>
#include <dbg_comm.h>
.fi