Starting DMON

From dmon2
Jump to navigationJump to search

Overview

Before starting DMON the debug link to the target should be in place and the target SoC switched on.

A typical startup command might be

   dmon  -gui -ni -c myfile.txt -eth 192.168.0.95

This causes DMON to start the GUI, not initialize the target SoC, run a batch/script file, and connect through an Ethernet debug link to a target with the given IP address. The startup switches can be entered in any order.

If the target SoC has a plug-and-play area DMON reads this, reports the devices detected on the SoC, and loads the corresponding commands. If there is no plug-and-play DMON can read the rquired information from a configuration file.

Details of the startup options and associated switches can be found here.

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.

Connect.gif

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 1  (on windows this selects the COM port with index 1)

or

 DMON –gui –uart COM1  (on windows this selects the COM port by name)
 DMON –gui –uart /dev/ttyUSB0  (on Linux this selects a COM port implemented by a USB-COM port adapter)


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 number. 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.

Note that some combinations of CPU and BUS frequencies on the E698PM can cause intermittent connection problems on the DSU UART. If observed use a different baud rate to connect to the target.

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

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 disable <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


SpaceWire Debug Link

-spw	<IP address | port> <port> use a SpaceWire debug link

This provides support for the SpaceWire link and debug protocol used with the AGGA-4 chip. Please note that this protocol is not the same as RMAP. A different start-up switch (-rmap) can be used to create a debug link based on RMAP.

Connection to a target SoC over a SpaceWire debug link is done via an external converter. This accepts TCP/IP packets from a PC or workstation, converts these to SpaceWire packets, and passes them on over SpaceWire. Similarly in the reverse direction for SpaceWire packets originating on the target SoC.

The parameters allow the converter's IP address and TCP port be specified. If there is only one parameter and this is not a valid IP address DMON will attempt to evaluate this as a port. If parameters are omitted or invalid default values are used.

DMON supports the AGGA-4 SpaceWire debug port using the Shimafuji STANDALONE SpaceWire to Gigabit Ethernet router/bridge as the TCP/IP to SpaceWire converter. Other converter types may be added in the future.

The default IP is 192.168.1.100. The default TCP port is 10029.


RMAP Debug Link

-rmap	<IP address:port> | <IP address> | <port> | <destination route > | <destination route # command source route>

This causes DMON to connect to the target using the remote memory access protocol (RMAP) available with some SpaceWire links.

Connection to a target SoC over a RMAP debug link is done via an external converter. This accepts TCP/IP packets from a PC or workstation, converts these to SpaceWire packets, and passes them on over SpaceWire. Similarly in the reverse direction for SpaceWire packets originating in the target SoC.

The RMAP protocol allows the target node in a SpaceWire network be identified using a destination route. This is made up of one or more node identifiers in the range 0 to 31, separated by spaces or commas. The RMAP route back to the source of the command, i.e. to the converter, is similar but restricted to no more than 12 nodes.

The TCP/IP address and port are used to access the converter. Some converters with multiple SpaceWire connections use the TCP port to determine which connection should be used. If a TCP port is not given, DMON uses the first node of the destination path to select the appropriate TCP port (or ports), and ensures that the last node of the source path corresponds, depending on the converter type. If both TCP port and destination route are given the first node of the destination route takes precedence over the TCP port.

DMON supports RMAP with the Shimafuji STANDALONE SpaceWire to Gigabit Ethernet router/bridge being used as the TCP/IP to SpaceWire converter. Other converter types may be added in the future.

For the STANDALONE the default IP is 192.168.1.100 and the default TCP port is 10029, corresponding to the SpW1 SpaceWire connection on the converter.

Examples (assuming the STANDALONE and the above defaults)

-rmap                                SpaceWire SpW1 link      TCP connection 192.168.1.100:10029  (default)
-rmap 3                              SpaceWire SpW3 link      TCP connection 192.168.1.100:10031
-rmap 2,0,5,#,3,6                    SpaceWire SpW2 link      TCP connection 192.168.1.100:10030
-rmap 192.168.1.100:10032            SpaceWire SpW4 link      TCP connection 192.168.1.100:10032
-rmap 192.168.1.100:10032 3,#,7      SpaceWire SpW3 link      TCP connection 192.168.1.100:10031  (given node overrides given TCP port)


Each node in the SpaceWire network, including the converter, has a logical address. This should be in the range 32 (0x20) to 254 (0xfe). Logical addresses may be the same when routes are relied upon, often the default value 254 (0xfe) is used.

-rmaplogicals converter_logical_address target_logical_address : allows the logical address of the converter and of the target be set


Each node in the SpaceWire network has a built-in key in the range 0 to 255. A RMAP command with a key that does not match the target key is rejected. An RMAP response that does not match the converter key is also rejected.

-rmapkeys converter_key target_key : allows the keys of the converter and of the target be set

The defaults are

 Shimafuji Standalone key: 2     Target key: 0


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.


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.


Installing the D2XX shared library and static library for FTDI Link

libftd2xx-x86_64-1.4.6.tgz for x86_64

libftd2xx-i386-1.4.6.tgz for x32


1. tar xfvz libftd2xx-x86_64-1.4.6.tgz

This unpacks the archive, creating the following directory structure:

   build
       libftd2xx        (re-linkable objects)
       libusb           (re-linkable objects)
       libftd2xx.a      (static library)
       libftd2xx.so.1.4.6   (dynamic library)
       libftd2xx.txt    (platform-specific information)
   examples
   libusb               (source code)
   ftd2xx.h
   WinTypes.h

2. Change directory to build

cd build

3. Switch superuser

sudo -s 

or, if sudo is not available on your system: su

Promotes you to super-user, with installation privileges. If you're already root, then step 3 (and step 7) is not necessary.

4. Copy the libraries to a central location.

cp libftd2xx.* /lib

5. Allows non-root access to the shared object.

chmod 0755 /lib/libftd2xx.so.1.4.6

6. Creates a symbolic link to the 1.4.6 version of the shared object.

ln -sf /lib/libftd2xx.so.1.4.6 /lib/libftd2xx.so

7. Enter command to list modules:

sudo lsmod

If "ftdi_sio" is listed:

Unload it (and its helper module, usbserial), as follows.

sudo rmmod ftdi_sio
sudo rmmod usbserial

And prevent from loading after reboot by adding exclusion to black list:

Create blacklist-ftdi-sio.conf
Add this line as it is : blacklist ftdi_sio usbserial
Save and copy to /etc/modprobe.d in your Linux system

8. Enter command to identify the VendorID and ProductID of of your usb(ftdi) device.

lsusb -vvv

(Find VendorID and ProductID with the name "Future Technology Devices Internetional")

9. Add permissions to USBtoFTDI cable :

- Use command "lsusb" to find cable vendor and product IDs 
- Create file 10-local.rules
- Add these two line as it is : 
     SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", GROUP="plugdev", MODE="0666"
     SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", GROUP="plugdev", MODE="0666"
- Copy file 10-local.rules  to /etc/udev/rules.d
- Edit /etc/udev/rules.d/10-local.rules as admin to modify vendor and product IDs for your cable taken using lsusb or add new line in that file   
SUBSYSTEMS=="usb", ATTRS{idVendor}=="idVendor", ATTRS{idProduct}=="idProduct", GROUP="plugdev", MODE="0666"

(Example: SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", GROUP="plugdev", MODE="0666")

9. Restart machine

11. All done!

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

Target systems can be in short supply, and access for software developers can be a bottleneck, particularly when developers are at different sites. A target system itself may be in an environment not suitable for software debugging activities.

To help address this DMON can be used in a client-server configuration, with the target system connected directly to a DMON server, and a client DMON connected to this server over the Internet via an SSL secured link. A server option allows the client connection be restricted to certain client IP addresses only, or be left open to any DMON client. All connection activities are displayed on the server console and can be logged. No license need be present for the client DMON, the license is needed only for the server DMON.

The user on the DMON client is able to carry out all the functions available when connected directly to the target. Programs can be downloaded directly to the target as usual or to a sandbox on the server for subsequent loading into the target by the same or another client.

The user can ask for a session to be kept alive, and then shut down the client. This session then continues on the DMON server, and can be re-connected to later by any allowed client by giving the session-id.

In most cases the client DMON is started with the -gui option as usual, and the user will not detect any difference in performance compared to a direct connection with the target. If the additional latency due to the network link does become apparent, it may be better not to use the -gui startup switch and work just with the DMON console as this involves less network traffic.

The server DMON should be started before any client connection is attempted. It connects to the target and reports the server IP and port that should be used by the client when connecting. It then waits for a client connection. DMON server always starts in console mode. All interactions with a client are displayed on the server console and can be logged. A command allows the connection be terminated at the server, which then reverts to waiting for a connection.

To use DMON client server, local network settings and firewalls must be configured to allow the connection.

DMON server and DMON client are standard DMON installations, the client-server mode is selected by using startup switches as described below.


Remote.gif

-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 to connect. 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. The -gui option is ignored if used.

-allowips [list]	Server only, restrict connections to these IP addresses.

[list] is a comma separated list of IP addresses, or hostnames which can be resolved on the server.

-setdownloaddir [flepath]	Server only, sets the sandbox directory to which the client can “download” program and script files.
-remote [IP] <port>	Starts DMON as a client connected to a DMON server, to which it sets up a TCP/IP link secured with SSL.

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 port is 55555.

–session [String]	Client only, reconnect to the server with [String] as session identifier, see below.

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 reconnect, 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 reconnect 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

The client can download files to a specific directory on the server. This directory can be specified when starting the server using the command line option -setdownloaddir. If this is not used, the directory defaults to the folder DMON/remote in the home directory of the user who started the DMON server.

The following commands are available to the client for file handling.

listdowndir  List Download Directory on The Server.

Also shows a CRC32B checksum for the files to allow comparison between files on client and server with different clocks.

deldowndir [filename|all]   Delete file filename or all files in download directory on the server
download [filename]	Downloads a file to the remote server.

The file will be stored with the filename without path in the download directory.

rload [file]	Load a program to the target from the download directory.

Any path specified is ignored, only the file name is used.

rcheck [file]	Execute check command on the server. File must be present in the download directory.

Any path specified is ignored, only the file name will be used.

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.

rlog [file]	Open a log on the server.  Any path specified will be ignored.
rlogoff	Close the last log opened on the server.
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.

getintlog [fileName]	Get Server's Internal Log and save to file on client.


Other dedicated commands in client mode

Many commands issued on the client are actually executed on the server, in particular those commands that have a lot of interaction with the target. Examples include run, write, memset and various others. Some commands can be executed either on the client or on the server, to be executed on the server these should be prefixed with r. Examples are load filepath which loads an executable file from the client file system into target memory, and rload filename which loads an executable file from the download directory on the server into target memory as described above. Other examples:

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

Startup commands

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.