Starting DMON

In <DMON Installation directory> on a Windows system there is a batch file which will start DMON. When started with no arguments, DMON will attempt to connect to the target by UART and will not display a GUI. However, the batch file will accept any of the command line options and pass them to the DMON process.
On a Windows system it is convenient to create Desktop shortcuts with the options suitable for a particular target. The installation process will create a desktop shortcut which can be copied and modified. 
On a Linux system, or for use with Cygwin on windows, a bash script with similar functionality to the batch file is provided.
== Connecting to a Target ==
This section deals with SPARC targets. For ARM processors see ARM support. 
== Direct link to the target ==
DMON requires a debug link to connect to the target. This link can be configured using command line options. If DMON fails to connect with the command line options given, an attempt can be made to specify a different link after start-up, by specifying the command line option at the console. For a target which has multiple debug link interfaces, the debug link can be changed while connected to the target by specifying the appropriate command or using a GUI widget which is accessed using the “Connect” menu item. This permits setting the parameters for the link, if any.
== UART Debug Link ==
If no debug link option is specified, DMON will default to using the UART debug link, and will search for the first available UART on the machine. If it does not succeed in linking to a DSU on that port the available ports will be listed in the console.
The –uart command line option can be used to specify which of the available ports to use, e.g.
DMON –gui –uart /dev/ttyUSB0 
Note that on Linux, particularly if a USB to UART convertor is being used, access to a UART may require root privilege. DMON can be run using sudo. Some data is stored in a folder /UserData in the user’s home directory. If DMON is run using sudo this is /root. Therefore it is recommended to change the permissions on the device:
build@ubuntu:~/Desktop$ ls -asl /dev/ttyUSB0
0 crw-rw---- 1 root dialout 188, 0 Apr 19 03:39 /dev/ttyUSB0''
By using chmod to change the permissions you can avoid having to use sudo to run DMON on the UART.
build@ubuntu:~/Desktop$ sudo chmod 666 /dev/ttyUSB0
build@ubuntu:~/Desktop$ ls -asl /dev/ttyUSB0
0 crw-rw-rw- 1 root dialout 188, 0 Apr 19 03:39 /dev/ttyUSB0''
The debug baud rate can be set using:
 
-baud	 [integer] : nearest valid rate is used, current default 115200. 
Valid rates are 9600, 19200, 38400, 57600, 115200, 230400, 460800.
At run time, if a UART debug link has been found on the target, the uart command can be used to switch to that link. The uart command has a single optional argument – the port name. Note that the link will not be changed if DMON determines that the board ID read from the link is different to the board ID read on initial connection.
== Ethernet Debug Link ==
The Ethernet debug link uses a proprietary protocol over a UDP link. Note that if multiple target boards of the same type are on the same subnet, there may be a conflict because the MAC addresses are the same causing confusion. The MAC address and the IP address of the debug link can be configured and are generally reset to a known value.
-eth	<IP> : Debug link to ethernet, optional IP, default 192.168.0.51 or set using –ip option 
-ip	 [IP] : Set default IP address for use on ethernet EDCL debug link, default value 192.168.0.51. 
This option will be ignored if an IP address was specified using the –eth switch. Note that the default IP address will be read on start up from the EDCL device, if present. This option is therefore deprecated.
-udp	[int] : Default port to use with ethernet EDCL debug link, current value 8000. If DMON is unable to bind to this port, another port number will be autonomously chosen.
At run time, if an EDCL debug link has been found on the target, the eth command can be used to switch to that link if initially connected on a different link. 
The edcl command allows some of the configuration to be performed. 
CAUTION it is recommended not to use the edcl command except for display purposes when connected on the ETH link as you may change the parameters of the link, causing it to fail.
edcl Display EDCL configuration:
DMON > edcl
Link using Ethernet, target devices with EDCL:
	EDCL_0 	192.168.0.32	0xFF980000	enabled ETH	192.168.0.32
	EDCL_1 	192.168.0.16	0xFF940000	enabled
	DEFAULT	192.168.0.32
edcl IP <index>	Change the IP address of the EDCL.
If there is more than one EDCL on the board, change the once specified by index.
Index refers to the index displayed by the EDCL command; this is determined on start-up and may vary if the initial connection was via an ETH link.
edcl enable <index>	Enable the debug EDCL.
If there is more than one EDCL on the board, enable the once specified by index.
edcl enable <index>	Disable the debug EDCL.
If there is more than one EDCL on the board, disable the once specified by index.
If it is necessary to change the MAC address (because there are several boards of the same type being added on the same subnet) this can be done using the write command and the address of the register, or using the GUI widget for the GRETH device in use.
== USB Debug Link ==
-usb	use USB debug link
The USB debug link requires that libusb has been installed on the host system. On a Linux system, nothing further is required. At present the USB link is only supported in Windows versions up to Windows 7, as later versions require Microsoft approved device drivers.
After installing libusb on a Windows system, carry out the steps below:
•	Log in as a user with administrator privileges.
•	Download (https://sourceforge.net/projects/libusb-win32/files/) the latest device driver binary package (libusb-win32-bin-x.x.x.x.zip).
•	Extract it to a temporary directory.
•	Use the INF-Wizard program to generate the INF file (modify the vendor and product IDs, which is 1781:0aa0 for USBDCL.
•	Unplug the device(s) from the system. This is optional.
•	Reconnect the device(s) to the system.
•	When Windows asks for a driver, choose the inf-file(s) created above. Windows will warn that the driver is not 'digitally signed'. Ignore this message and continue with the installation. Since libusb version 1.2.0.0, a valid digital signature is embedded inside libusb0.sys for AMD/Intel x86_64 version of Windows so that the users can install the driver as well under 64bit x86_64 version of Windows Vista/7/2008/2008R2. Please read more about the Microsoft Kernel Mode Code Signing (KMCS) (http://www.microsoft.com/whdc/winlogo/drvsign/kmcs_walkthrough.mspx) policy for more information.
•	Open the Windows Device Manager to verify that the device is installed correctly. Run the test program (testlibusb-win.exe) from the 'bin directory'. It should print out the descriptors of your device(s).
•	A reboot isn't necessary.
•	Starting from libusb version 1.2.1.0, the inf-wizard.exe has embedded driver binaries and provide an option to install the driver at the end of the process
== JTAG Debug Links ==
If the JTAG debug link is implemented on the target then a JTAG connection can be used. Which connection options are used depends on what additional hardware is implemented to drive the JTAG interface, either in additional hardware or in an adapter which is part of the cable. Note that not every chip which has a JTAG interface implements an interface to the DSU which can be accessed via the JTAG interface. The JTAG clock speed must be less than one third the speed of the AHB bus for correct operation.
== FTDI Debug Link ==
If an FTDI cable is being used, then the appropriate D2XX drivers for the host system need to be downloaded from http://www.ftdichip.com/Drivers/D2XX.htm and installed according to the instructions there.
-ftdi	use ftdi JTAG link
-ftdilocid <ID>	Set location ID to connect to FTDI if more than one FTDI cable is connected to the PC. DMON will display available location IDs, but will connect to the first one found
 
-ftdispeed <INT>	Set user defined frequency passed in MHz. Should be set to less than or equal to 1/3 of AHB bus speed. By default DMON uses a speed of 1 MHz for the FTDI link.
-enablehispeed	Force FTDI operate at HI speed mode if a HI speed FTDI device is detected (default is LOW). 
Operation is more reliable at LOW speed, HI speed operation depends on the implementation of the board. In particular flash programming may be unreliable at high speed.
== Digilent JTAG Debug Link ==
-digilent	Use JTAG debug link with Digilent JTAG-HS1 cable
The Adept 2 runtime for the cable must have been installed, this can be downloaded from http://www.digilentinc.com
On Linux, libusb must be present for the Adept runtime to work. CAUTION: when the runtime is unpacked, the FTDI drivers must be installed before the Runtime (separate directory) in order for the runtime to work.
== Xilinx Platform USB Cable ==
DMON supports Xilinx connection using the DCL9 or DCL10 cables. DCL10 is the default, if DCL9 is being used the product ID must be passed as shown below. The appropriate driver libraries for the cable must be installed, and accessing the cable also requires libusb to be available.
Consult Xilinx documentation for you cable on how to install the correct drivers.
-xilinx <ProductId>	 Use Xilinx USB to JTAG link, <Specify Product ID of XILINX device>
-xilinxindex <index>	 Specify the index of Debug JTAG Interface, if JTAG Chain has more than one device. By default device 0 is assumed. DMON lists the devices found on start up.
== Remote Access ==
Embedded development boards are often expensive and a bottleneck. Projects often involve several partners, some of whom will be working remotely. This feature in DMON v2 facilitates the best use of an expensive hardware resource by allowing developers to effectively debug applications on the board remotely.
This feature is an additional feature – if remote communication is not required, there is no need to run both the DMON server and client on the same machine. DMON is installed as normal on the client and server machines, and started using the options described below. The communication between the client and server uses SSL, and only one client at a time may connect to a DMON server. There are also options to only allow connections from certain client IP addresses.
From the User point of view, the remote link appears as a special case of a debug link, and DMON operates as normal (although with some additional latency due to the network link). The GUI is available. This generates some requests across the network, and it may be preferable on a slow link to avoid using it. Some tasks are always run on the server – for example polling the board while a program is running.
 
-remote [IP] <port>	Configure DMON to act as a client connected to a DMON server that in turn is connected to the target SoC by a debug link. IP is the internet address or hostname of the server DMON. <port> specifies the port. This must be the same as that selected on the server. The default is 55555.
-server <IP|IP:port|port>	Start DMON as a server.
When starting as a server, DMON reports the IP address and port on which it expects to receive connections. The remote client must use these when it is connecting. By default, DMON will use and report the main IP address of the host computer, and use and report port 55555. Either or both of these default settings can be changed, but must be valid. 
A port number less than 49000 will be ignored; the default port will be used.
If the IP address cannot be used on the host then DMON will not start in server mode.
It must be possible for the remote client to connect when given these new settings. The -gui option will be ignored on the server.
-allowips [list]	Only connections from these IP addresses will be allowed.
[list] is a comma separated list of IP addresses or hostnames which can be resolved on the server.
–session [String]	Reconnect to the server with [String] as session identifier, see 3.2.2
-setdownloaddir	Server only: sets the sand box directory to which the client can “download” program files and script files.
Connection Sequence
<to do, list messages for trouble shooting >
Keeping the session after client disconnects
This can be done using the keepsession yes command, which can be cancelled using keepsession no.
This command causes the server to report a session identifier to the client, and to keep the current session active after the client shuts down. This identifier is a random five digit number, and is displayed on the server screen as well as on the client. 
To reconnect to an existing session, the client must be started with the -session switch giving the correct session identifier, e.g. –session 12345. 
On reconnection, the client screen will display ‘Reconnected to Session Id: xxxxx’ and the server will display ‘Reconnected to existing session xxxxx from remote client: …….’
If after reconnection the client again uses the keepsession yes command, the same session identifier is used, making it unnecessary to modify the –session switch argument.
If a session is not currently active on the server the –session switch on the client is ignored. Otherwise attempts to connect will fail unless the correct session identifier is given.
After a client disconnects output for it is queued on the server, and passed to it when the client reconnects. It is best to avoid generating a lot of output in a session while the client is disconnected.
== File Handling on the Server during remote access ==
Files accessible to the client user are stored in a specific directory on the server. This can be specified when starting the server using the command line option.
-setdownloaddir	Set directory on Server to keep downloaded files
If not set, it defaults to the folder DMON/remote in the home directory of the user who is running DMON.
The following commands are available to the client for file handling.
deldowndir [all|fileName] Delete all or the file fileName in Download Directory on The Server
download [filename]	Downloads a file to the remote server; it will be stored with the filename without path in the download directory.
getintlog [fileName]	Get Server's Internal Log and save to file on client.
getuserlog [logfileName][fileName]	Get Server's User Log (opened with rlog) and save to file locally. 
Note: this can be used to fetch any file in the download directory.
listdowndir List Download Directory on The Server. Shows a CRC32B checksum for the file also to allow comparison between files on client and server with different clocks.
rcheck [file]	Execute check command on the server. File must be present in the download directory. Any path specified will be ignored.
rload [file]	Load a program to the target from the download directory. Any path specified will be ignored, only the file name will be used.
rlog [file]	Open a log on the server. Any path specified will be ignored.
rlogoff	Close the last log opened on the server.
rscript [file] 	Execute script command on the server. Any path specified will be ignored.
Only DMON scripts are permitted, as running Tcl or Python scripts on the server would be a security risk.
== Other dedicated commands in client mode ==
A few commands can be prefixed with “r” to force execution on the server. Commands which interact a lot with the target – such as memset or write – are already executed on the server.
rexamine [address] <length>	Read and display memory from address. Default length 16 words.
rstop	execute stop command on the server
== Dedicated commands in server mode ==
The command console is available when DMON is being run as server. The available commands depend on the target hardware and can be listed by typing “help”.
There is one specific command, which allows a user at the server console to stop a client session.
 
endsession [sessionId]	end the identified session - for use on server only