DMON Features

== The command console ==
DMON can be run without a GUI. This is the default, for backwards compatibility with DMON v1.0. Some functionality will not be available; however commands and scripts are available. Certain commands will create new GUI windows; for example if tracing is enabled and the callgraph command is issued.
The Menu bar is available with the functionality outlined in this section.
== Expressions and symbols ==
DMON allows symbols to be used as parameters and commands, and allows these symbols to be combined in expressions using the usual operators.
This section needs to be completed.
== GUI ==
DMON has a rich GUI, divided into several regions.
There is a menu at the top
•	File: opens a file selection dialog, selected file will be copied to the command line. 
•	Edit: allows copy and paste from the console. This can also be done using the mouse and the usual short cuts.
•	Connect: connection dialog.
•	Monitor: Data Monitor menu.
•	Tasks: allows configuration of various automated tasks.
•	RTEMS: RTEMS Thread display (available only once an RTEMS application has been loaded).
•	Statistics: LEON4 Statistics module configuration and display.
•	Language: Allows selecting the scripting language for DMON.
•	Help: provides information about DMON
•	List available DMON commands
Below the menu there are some buttons which control the running of programs, setting of breakpoints etc.
Below that is a row of widgets, one for each device identified on the target.
There are two tabbed panels below the widgets; on the left the default view shows the command console (which is also shown if no GUI is present); this panel also has tabs to show the internal log; and three tabs which act as scratchpads with syntax highlighting for Tcl, Python or plain DMON scripts. The right hand panel has 4 tabs. The Layout tab shows the configuration of the SoC. The UART Loopback tab separates the characters read from each UART loped back UART and permits enabling and disabling UART loopback for each one. The SYSTrace and ITrace panels are refreshed with the latest trace information after a program halts. These are only shown if the associated hardware is available on the target. 
Each of these GUI elements is described along with the associated functionality elsewhere in this document.
=== Layout Panel ===
When the board configuration is established on start up a graph of the devices and the buses to which they are attached is calculated and displayed in the tabbed panel on the right. This display can be scrolled and can also be made a floating window.
Clicking on any of the nodes in the graph brings the associated device widget to the foreground in the device widget display where it is highlighted.
=== Device Widgets ===
A widget is added to the display on top of the DMON window for each device identified on the board; in addition there is a composite CPU widget which pulls together the different processor cores, allowing them to be activated.
These widgets are tiled in a line across the top of the DMON window, filling the available spaces, and then stacking. A double click on the “+” symbol on any widget will open it as a floating window.
If the mouse is brought close to a stack a drop down list of which devices are in the stack is displayed and one can be selected to be brought to the foreground.
In a multiprocessor system there is a summary widget for the CPUs. The “active” CPU preselects a CPU for commands, see the “cpu” command; and as the buttons on this widget issue commands, they apply to the active CPU only.
Only one CPU can be selected as “active”. If a CPU is not enabled it cannot be started by an application running on the target. 
The colour of the CPU icon changes according to the status.
Powered down Running Debug Error Halted
Each CPU has its own widget, varying slightly according to the CPU. The diagram shows a LEON 4 widget. 
The buttons open a further widget to deal with the specific item. The register displays are also clickable and display register details as is done for other widgets.
The standard widget for each device shows three buttons, and if there are registers in a device, a drop down list of those registers.
The init button calls the init method on the device – in many cases this is an empty operation but for some widgets it will reset registers. The init method is also called after board initialisation.
The info button prints the information that applies to this device in the “info sys” command output. At a minimum it shows that Name, version and address ranges.
The reg command will print the registers associated with the device, if any, to the DMON console.
The drop down list allows the user to select a register in the device to be displayed in a dialog which has greater detail and permits modifying the register.
=== Register Dialog ===
Each register in each device can be edited and displayed via a GUI element similar to the one below:
•	The title of the widget shows the register name according to documentation
•	The register value is shown as a 32 bit hexadecimal value
•	Each field in the register is displayed
:o	Read only fields are not editable
:o	A single bit field will be displayed as a drop down list with the active value selected
:o	Multi bit fields may be treated as integers or as enumerations; in the case of integers an offset and/or scale may be applied in the display – for example TCAS Delay above.
::-	Integers can be changed by typing a new value in the editable window; the human readable value is shown to the left, with units as appropriate. 
::-	Enumerated values can be chosen from the drop down list.	
:o	On the right of the widget the bits are displayed; clicking on a bit toggles its value and this will be reflected in the rest of the display.
:o	The register value on the board is polled in the background. Changes made in the dialog are not applied to the board until the “Apply” button at the bottom is pressed. To facilitate changing fields, the “Pause Sync” button can be pressed, then the value will no longer be read from the board. The button will become a “Resume Sync” button; values can be read again from the board by pressing it.
:o	A literal value for the whole register can be entered in the dialog window in the same row as the buttons.
:o	“Apply” applies the edited value to the hardware register
:o	“Cancel” closes the dialog without making any changes
== Scripting ==
DMON allows scripts to be used to run a sequence of commands. If only DMON commands are used, then no logic structures are available; however if commands which run an application on the board are included in the script then the next command will not be executed until the target has stopped.
=== Tcl ===
Tcl support has been added to DMON by integrating the jTcl interpreter version 2.7.0. This supports Tcl commands. Further information on jTCl is available from https://jtcl-project.github.io/jtcl/
 
Tcl commands can be entered in several ways
•	At the DMON console
•	Using the DMON script command: commands in the file will be interpreted line by line
•	Using the Tcl source command to read in a whole file of Tcl code.
•	Using the Tcl edit window in the GUI.
DMON can be started in tcl mode using the –tcl command line option, or the command tcl can be entered at the console to enter Tcl mode. Any symbols previously available to DMON scripts are available as Tcl variables. That is, the symbol should be prefixed with “$” to identify it as a variable.
DMON commands can be used as usual in a tcl script – however some commands may be shadowed by Tcl procedures or keywords. Prefixing these commands with “d.” forces them to be interpreted as DMON commands.
There are a number of DMON commands for interacting with the target which are specific to Tcl/Python mode and return objects rather than outputting to the console:
Option	Description
	getb [Address] [count]		read [count] bytes from address.
	getb [Address]		read a byte from address.
	getw [Address] [count]		read [count] 32 bit words starting from address.
	getw [Address]		read a 32 bit word from address.
	getstate		returns 1 if the target is running and 0 if it is stopped
	-tcl 		Set console language to Tcl
	dmon 		Use only DMON commands. Ignored if already in DMON mode
	shell		In a startup script activate the language specified by command line option. Otherwise, display the language in use.
	tcl 		Interpret command input as Tcl commands. Ignored if in Tcl mode
The STDOUT, STDERR and STDIN streams of the Tcl interpreter are attached to the DMON console. STDIN will be used for Tcl commands such as “get” and “read”. If the Tcl interpreter is waiting for input on STDIN an “Input” prompt as shown below is shown. If the command is entered on multiple lines (as determined by the Tcl interpreter) a continuation prompt will be shown while more input is expected for the command.
=== Python ===
Python support has been added to DMON by integrating the jython interpreter version 2.7.0 which supports Python 2.7. Further information on Jython is available from http://www.jython.org/.
Python commands can be entered in several ways
•	At the DMON console
:o	DMON commands entered at the console work as before.
:o	Prefixing a command with “d.” forces it to be evaluated as a DMON command.	
•	By importing a python script.
:o	execfile('./python/PythonScript.py')
	
•	Using the Python edit window in the GUI.
Because Python is a block oriented language and cannot be processed line by line as DMON and Tcl are, the DMON script command is not available in python mode. The python method to process a script must be used; and the API which is provided to run DMON commands must be used for DMON commands. The API provides a run method for the DMON command; the method returns an object corresponding to the returned object; for most DMON commands this is a Boolean which is true for success; the side effects of the commands will normally be information printed on the console. There are some dedicated commands which return a specific value.
Command	Description	Return type
	getb [Address] [count]		read [count] bytes from address.		List of integers
	getb [Address]		read a byte from address.		Integer
	getw [Address] [count]		read [count] 32 bit words starting from address.		List of integers
	getw [Address]		read a 32 bit word from address.		Integer
	getstate		returns 1 if the target is running and 0 if it is stopped		Integer
	
				
The example shown uses the getb command to read 10 bytes and print them.
Note: The python interpreter loads some libraries at start up, and this can be a slow process. The libraries can be preloaded in parallel to DMON start up using the –preload switch. This is not required if DMON is started in –python mode.
Option	Description
	-preload		Load python libraries before first use
	-python		Set console language to python
	dmon 		Use only DMON commands. Ignored if already in DMON mode
	python		Interpret command input as Python commands. Ignored if in Python mode
	shell		In a startup script activate the language specified by command line option. Otherwise, display the language in use.
The Python builtin function “raw_input” can be used to read a string from the DMON console.
When the “raw_input” function is encountered, the prompt – if specified – is printed to the DMON console and the Input: prompt shown.
return causes the string to be read into the specified variable.
=== Scripts run on particular events ===
==== Scripts while running programs ====
Multiple scripts can be specified to be run during execution of the run/go command to start a program or during the continue/step command.
Only one script can be specified to be run during execution of a program.
Note that the scripts files are read once when added to the lists and stored as an array of strings. This means that if the file is changed on disk it must be removed and added again to the list.
	precont [filename]		append a script to the user scripts executed before continuing/stepping a program
	precont insert [index] [filename]		insert a script at [index] in the user scripts executed before continuing/stepping a program
	precont list		list the user scripts executed before continuing/stepping a program
all]		remove the script at [index] in the user scripts or all scripts executed before continuing/stepping a program
	prerun [filename]		append a script to the user scripts executed before starting a program
	prerun insert [index] [filename]		insert a script at [index] in the user scripts executed before starting a program
	prerun list		list the user scripts executed before starting a program
all]		remove the script at [index] in the user scripts or all scripts executed before starting a program
	runscript [filename]		set the user script executed during program execution
	runscript list		list the user script executed during program execution
	runscript remove		clear the user script executed during program execution
Scripts may be DMON, Tcl or Python. Note that scripts are executed one line at a time; if Tcl or Python scripting is required it would be better to use the source <file> command in Tcl to load a script, or the exec <file> command in Python. Note however that these are atomic commands from DMONs point of view (so the script will not be stopped by DMON).
The script being run during program execution will be stopped when the program stops (for example at a breakpoint). If the script ends while the program is still running it will be started again.
CAUTION: if the script contains a command which cannot be interrupted, it will not be stopped until that command completes. This is especially the case for Python and Tcl scripts.
==== Triggered Scripts ====
DMON provides a function which allows the user to monitor an address and to run a script when that address changes. The foreseen scenario is for use with interrupt processors; therefore a bit can be monitored and the facility to clear and mask the monitored bit is provided.
It is the user’s responsibility, if an application is running on the board, to ensure that the application does not handle the interrupt, or at least does not clear it, as this will interfere with the handling of it by DMON.
The flowchart above summarises the operation.
	mon [addr] [script] <bit>		Runs script every time addr value changes. If a bit is specified, runs the script when that bit has changed, and clears it.
	mon [pen][clr][msk][script][b]		pen, clr and msk are addresses; b is a bit offset. (1)Bit b in msk is set (2) Bit b in pen is polled, If it is set, script is run (3) Bit b in clr is set (4) Polling resumes (Ctrl-C or mon stop will stop the operation).
	mon stop		stops monitoring if running
As well as the commands described above, there is a GUI element to set up the scripts. Select the tasks option from the top menu to manage triggered scripts. Similar GUI elements exist for tracing and other scripts.
== Data Monitoring ==
DMON allows the user to monitor addresses on the board by periodically sampling them. The user can configure a start condition, a stop condition and a number of addresses to poll. The user can also choose to display the data as it is polled in several formats. The data can also be stored in a file.
The top level menu shown in the figure above offers a number of options
1.	Configure Variable Set: opens a dialog window to configure the current variable set which is being prepared. 
2.	Load Variable Set: load a variable set from an XML file which describes a Variable Set to be monitored. Performs validation and reports any errors to the user.
3.	Save Variable Set: save the current variable set to an XML file.
4.	Export XML schema: exports the XML Schema which is used to define the legal XML for a variable set.
5.	Start Monitoring: Start monitoring the data set. This first performs some additional validity checks on the data set and then starts the polling of data at 100 ms. Start and Stop Conditions are applied.
 
=== Monitoring Operation ===
Once start monitoring is chosen the monitoring state machine shown below becomes operational after the variable set has been validated. Variable set validation ensures that all required items are defined, and that any program symbols used can be resolved. There are a number of options which affect the polling:
•	pollWhenNotRunning: If this flag is set, polling starts immediately, otherwise data will only be polled when an application program is running and is being monitored by DMON.
•	The optional start and stop triggers must be enabled. Start and Stop trigger are independent.
•	Once started polling continues until it is stopped by
o	The “Stop Monitoring” item on the menu which replaces the “Start Monitoring”
o	The user interrupts DMON operation using the stop command or Ctrl-C
o	CAUTION: closing a display window will stop that window displaying data but does not affect polling.
 
Figure 8 9 Data Monitor State Machine
 
=== Data Configuration Menu ===
==== Dialog Elements ====
•	Name: a name for the data set. This is for documentation purposes in the XML.
•	Start Trigger: see below
•	Stop Trigger: see below
•	Store in file: Boolean flag. If set data will be stored as sampled in the file specified. The format is Date, Time, Subsecond time, Item name, Value(s) as 32 bit hex. For examples see below.
•	Filename: name of file in which to store data
•	pollWhenNotRunning: If this flag is set, polling starts immediately, otherwise data will only be polled when an application program is running and is being monitored by DMON.
•	Configure Display Sets: see below
•	Configure Data Items: see below
==== Start/Stop Trigger ====
The following items may be configured for the start or stop trigger. Either trigger is optional and will be ignored if not defined or if it is not enabled. 
Item	Type 	Description
Address	String	Address to poll; may use an expression using ELF symbols. This will be evaluated when polling is started by the user and must be valid at that point.
Mask	32 bit integer	Value read from address will be compared with the mask using the condition operator described below.
Note: Mask will be stored as a string in XML but must be a valid Long integer in Hex, Decimal or Octal format.
It is entered as a hex value in the dialog.
Condition	enumeration
	Condition applied to value read and mask to determine whether the condition is met. For bitwise conditions the condition is met if the result of applying it to the value read and the mask is non zero. All comparisons are on the basis of unsigned integers.
One of
•	Bitwise and
•	Bitwise or
•	Bitwise xor
•	Less than
•	Greater than
•	Less than or equal
•	Greater than or equal
•	Exactly Equal
enabled	Boolean	Whether to apply the trigger
=== Configure Display Sets ===
Each Data Item may belong to a Display set. If a display set is in used by a Data Item it is not possible to remove it.
The configure dialog permit setting the parameters for each graph type. The “max samples” option is the upper limit for the number of samples displayed on the graph. Older samples are discarded.
Other parameters govern the scaling and labelling of axes. The screenshots below show how to configure data items and display sets.
 
Figure 8 11 Data Monitor Configuration Menu (2)
 
Figure 8 12 Data Monitor Configuration Menu (3)
 
Figure 8 13Configure a display set
 
Figure 8 14 Data Set Display, showing the options
 
=== Data Item Configuration ===
 	Data Items are defined by
•	A name; must be unique in the Data Set
•	An Address; may use ELF symbols and expressions. If a program has been loaded symbols will be presented in a drop down list for selection.
•	Length in words to sample.
•	Whether to display the item. If the display option is chosen a drop down list of available display sets is shown.
•	The “Parameters” button is used to further configure display, by assigning a colour for example. It depends on the display set chosen.
=== Output File Examples ===
This shows several data items being polled, with 5 values being polled from one of the addresses:
2015-06-02, 15:31:50,756000000,x,0x00000219,
2015-06-02, 15:31:50,803000000,beat,0x00000327,
2015-06-02, 15:31:50,804000000,y,0x00000373,0x000003e8,0x00000327,0x400921fb,0x54442d18,
2015-06-02, 15:31:50,868000000,y2,0x000003e8,
2015-06-02, 15:31:50,884000000,x,0x00000219,
2015-06-02, 15:31:50,980000000,beat,0x00000327,
2015-06-02, 15:31:50,981000000,y,0x00000373,0x000003e8,0x00000327,0x400921fb,0x54442d18,
2015-06-02, 15:31:51,39000000,y2,0x000003e8,
=== Console commands ===
There are console commands which allow some of the functionality above to be used.
	datamon load [filename]		load a DataSet from an xml file
	datamon save [filename]		save the current DataSet to an xml file
	datamon start		Validate the current DataSet. If successful, start monitoring
	datamon stop		stop monitoring
	datamon xsd [filename]		save schema for DataSet to the specified file
			
== RTEMS Thread Support ==
DMON will poll on request the thread table of RTEMS, parsing the structures described below. This functionality requires that some ELF symbols are defined for the program loaded:
•	RTEMS Version is read from _RTEMS_version
•	Threads tables are searched for in the following locations:
 
:o	_RTEMS_tasks_Information
:o	_Thread_Internal_information
•	The currently Executing thread control block is read from *_Thread_Executing
•	The start and end of ram determined during memory probing are used to sanity check the values read from the tables in order to avoid attempting to read invalid memory addresses.
NOTE: loading an RTEMS application may not initialise the memory for the thread tables. In that case running the RTEMS command from the console or GUI before starting the program will give incorrect results.
This functionality is only supported for RTEMS versions which are identified in the version string as compiled for SPARC. The version string found is shown on starting monitoring (GUI) or when the command is run. If the version is not one of the supported versions polling will be attempted anyway with the defined structures; the user is warned.
There are two commands available from the console:
rtems Read current RTEMS thread information (if available)
rtems dump Dump structures used to read RTEMS thread information
Once an RTEMS application has been loaded at least once during the session, and the GUI is active, a GUI menu is available:
 
If “Start Monitoring” is selected, the Thread tables will be polled at the specified interval – by default once per second. The results are shown in a GUI window. This window cannot be closed while polling is active, regardless of whether the application is running or not. Polling can be stopped from the menu. Once started, the “Start Monitoring” menu point becomes a “Stop Monitoring” menu point.
The following are read from each thread structure:
	Name		C variable		Type		Offset : Size
	API		the_api		Objects_APIs	0 : 4
	Max. Index		maximum		unsigned short int	16 : 2
	Table		local_table		Objects_Control **	28 : 4
							
Each Thread control block has the following data read from it:
	Name		C variable		Type		Offset : Size
	Name		Object.name		Objects_Name		12 : 4
	ID		Object.id		Objects_Id		8 : 4
	Priority		current_priority		Priority_Control		20 : 4
	Entry Point		Start.entry_point		Thread_Entry		156 : 4
	Current PC		Registers.o7		uint32_t		340 : 4
	Running time		cpu_time_used		struct timespec		132 : 8
	State		current_state		long unsigned int		16 : 4
							
Example output for console command:
rtems-4.10.1(SPARC/w/FPU/leon3)
 TA1 CLASSIC 0x0a010002 1 0x40001420 (Test_task) 0x40016bfc (_Thread_Dispatch + 0xd8) 0:00:00,960459000 0x00000008 (Delaying) 
* TA2 CLASSIC 0x0a010003 1 0x40001420 (Test_task) 0x4000a194 (apbuart_outbyte_polled + 0xc) 0:00:00,374664000 0x00000000 (Ready) 
 TA3 CLASSIC 0x0a010004 1 0x40001420 (Test_task) 0x40016bfc (_Thread_Dispatch + 0xd8) 0:00:00,254531000 0x00000008 (Delaying) 
 IDLE INTERNAL 0x09010001 255 0x40009e10 (bsp_idle_thread) 0x40016bfc (_Thread_Dispatch + 0xd8) 0:04:38,710598000 0x00000000 (Ready)
== Adding a device driver to DMON ==
=== Introduction ===
The target system to which DMON is connected may include special purpose devices developed by the user. An example is an SOC implemented on an FPGA, which is likely to contain user defined devices. In what follows we will refer to such devices as ‘user defined devices‘, ‘user defined Intellectual property’, ‘user defined IP’, or sometimes just ‘IP’. Using standard DMON commands the user can interact with these devices, and can provide support for them by creating batch files of DMON commands or scripts in TCL or Python. It is also possible for a user to add support for a user defined device to DMON itself, extending DMON’s built-in commands and other features.
DMON API will allow user to add Custom Devices and Commands associated with these devices to DMON. This feature applies only to SPARC based systems which comply with the convention of Vendor and Device ID, and where the required address and IRQ information is available either in a configuration file or in the plug and play memory of the device. 
Note on matching devices to drivers: Devices found in the Plug and Play area are matched based on the triplet of Vendor ID, Device Id and core revision. If no exact match is found but Vendor ID and Device ID is matched, the driver loaded will be that for the next lowest core revision; if no lower match is found the next highest revision will be matched.
Use Cases:
:•	Developer is adding a completely new IP core with a possibly new Vendor 
:•	Developer is adding a new revision of an existing core 
:•	Developer is adding a new IP core which is a customisation of an existing IP core, but where the Vendor ID is going to be changed to reflect this fact. 
In each case the developer must provide all required driver functionality.
 
Note: the Developer will not be able to add a GUI element for the device; instead a basic GUI Device element will be created with limited functionality.
=== Technical background ===
DMON is written in Java, and adding an extension to it requires knowledge of the Java programming language.
Each type of device on the target is represented by a Java class. This provides constants such as register offsets, device specific command definitions and associated methods, symbol definitions, and information about this device class for display purposes.
There may be many devices of the same type on a target. Each one corresponds to a Java object, an instance of the Java class for that device type. Each device instance involves one or more addresses on the internal target bus (typically some version of the AMBA bus).
 
When DMON connects to the target SOC it determines the devices present either by reading the plug and play data on the target or by reading a configuration file on the host. Only the classes needed to support the devices present and the associated symbols and commands are loaded. If a device is not present, the symbols and commands specific to it will not be available.
At present DMON only supports the LEON plug and play form of device type identifier, three numbers that give the Vendor Id, Device Id, and Version Number followed by numbers giving the device’s base address or addresses. It is possible to register meaningful names corresponding to the Vendor, Device and Version numbers. 
If the target does not contain a plug and play area, or it is desired to add support for devices not recorded in the plug and play, a target configuration file on the host is used. Each record in the file corresponds to a device and gives the device type identifier and the base address or addresses for the device. DMON only accepts a record format similar to that used in the plug and play.
=== Getting Started ===
Follow the steps below to add support to DMON for a user-defined device:
:1.	Modify sample MyVendor_MyNewDevice.java file located in ThirdParty folder in DMON install directory.
:2.	This class must extend UdipDevice.java. If java IDE is used then ThirdParty.jar should be added to this project class path. In other scenario -cp thirdpartyapi.jar should be passed to java compiler.
:3.	A class following the template of MyVendor_MyNewDevice.java must be created for each different device type.
:4.	If the THIRD_PARTY.jar is to be created in the DMON installation directory then the doUDIP batch file or shell script must be run with the correct privilege level. If the code is independently compiled it is important that the java compiler (javac) and archiver (jar) supplied with DMON is used in order to ensure byte code compatability.
:5.	The batch file will create THIRD_PARTY.jar using the same java compiler as was used to compile DMON.
:6.	Start DMON with –udip switch. This will force DMON to load THIRD_PARTY.jar. DMON will look first in the directory in which DMON was started (shown as initialisation directory on start-up) and then in the “ThirdParty” directory of the DMON installation.
 
=== API ===
The third party API provides the methods below to be used in the java code for a device driver. Methods are available either in the API class or in the UdipDevice class which the third party device must extend.
Each device class in the ThirdParty jar MUST extend the UdipDevice class and MUST provide a static “register” method which handles registering the device, and the Vendor if necessary. If the “register” method is missing the class will not be loaded.
	Method		Description
	boolean Api.registerVendor(int VendorId, String Name)		Register a name for the vendor represented by Vendor ID and add to the list of known Vendors. This will replace any existing entry for this Vendor ID. Should be called from the register method of the device class. This method returns true if the Vendor name could be registered. It will return false and no Vendor will be registered if Vendor ID is outside the range [1,255].
	boolean Api.registerDevice(int vendorId, int deviceId, int revision,String className, String descriptiveName)		Register a device handler. Should be called from the register method of the device class. This method returns true if the device could be registered. It will return false and no device will be registered if (1) Vendor ID is outside the range [1,255] or does not correspond to a known Vendor ID (2) Device ID is outside the range [1,4095] (3)Revision is outside the range [0,255] (4)Class name or descriptive name is NULL. (5)Note that while class name is not checked at this point, if it is invalid then it will not be possible to load when needed, leading to an error message at that point. This method is called by DMON start up before establishing the target configuration. Any errors which occur during start-up will be printed to the DMON console and are also logged in the internal log file.
	boolean Api.registerCommand(String commandName,String commandMethodName,Class<?> className,String helpString)		Register a command. The method commandMethodName in the Class className will be called if a string starting with commandName is entered at the console or in a script. The string helpString will be added to the online help. This method returns true if the command could be registered. It will return false and no command will be registered if (1)commandName is in use already (2)either className is null or the method commandMethodName cannot be invoked on className This method should only be called in the “addCommand” method of a Third Party device. This method is called by DMON start up while establishing the target configuration. Any errors which occur during start-up will be printed to the DMON console and are also logged in the internal log file.
	void Api.display(String message)		Display message on the DMON console, is the console is active. If logging is active the message will also be logged.
	void Api.log(String message)		Print message to the internal log with level WARN
			
There are a number of methods to read and write memory; these methods vary as to whether the arguments are long/int or Strings. Methods which take String arguments allow these arguments to be expressions which can be evaluated, see 7.1.1. Such expressions might be passed in from a command on the console to a User Defined command handler. Note also that long is used for target word values because Java int is always signed but target data may be interpreted as signed or unsigned; using long values allows calculations to be carried out in Java without unintended sign extension.
	Method		Description
	byte[] Api.readBytes(
long address, 
long count)
byte[] Api.readBytes(
String address, 
String count)		Read count bytes starting from address
Returns NULL if there was an error either in reading the target or in evaluating string expressions.
The cause of the error will be logged in the internal log and an error message will be displayed in the console.
Returns an array of bytes if successful.
	long[] Api.readWords(
long address,
long count)
long[] Api.readWords(
String address,
String count)		Read count 32 bit words starting from address
Returns NULL if there was an error either in reading the target or in evaluating string expressions.
The cause of the error will be logged in the internal log and an error message will be displayed in the console.
Returns an array of longs if successful – but note that it is the low 32 bits of these longs that represent the target data.
	long Api.readWord(
long address)
long Api.readWord(
String address)		Read one 32 bit word at address
Returns -1 if there was an error either in reading the target or in evaluating string expressions.
The cause of the error will be logged in the internal log and an error message will be displayed in the console.
Returns a long if successful – but note that it is the low 32 bits of this long that represents the target data.
	boolean Api.writeWord(
long address,
long data)
boolean Api.writeWord(
String address,
String data)		Write the low 32 bits of data to address
Returns false if there was an error either in writing the target or in evaluating string expressions.
The cause of the error will be logged in the internal log. 
Returns true if successful
	boolean Api.writeBytes(
long address,
byte[] data)
boolean Api.writeBytes(
String address,
byte[] data)		Write data to the target starting at address.
Note: the debug link is usually 32 bits wide; non-aligned addresses will be modified using read-modify-write.
Returns false if there was an error either in writing the target or in evaluating string expressions.
The cause of the error will be logged in the internal log. 
Returns true if successful.
	boolean Api.writeWords(
long address,
long[] data)
boolean Api.writeWords(
String address,
long[] data)		Write data to the target starting at address.
The low 32 bits of each long will be written.
Returns false if there was an error either in writing the target or in evaluating string expressions.
The cause of the error will be logged in the internal log. 
Returns true if successful.
	void Api.showInfoReg(
long address, 
String name)		Utility method which will display the contents of address on the console using name as a description.
Format will be the same as that used for “printreg” command.
			
==== Data and methods provided by UdipDevice superclass ====
 The Third party device driver extends the UdipDevice class and therefore has access to some data and methods in that class.
	Method / Item		Description		Default
	long baseAPBAddress		Convenience variable, used in example to hold the base address on the APB bus.		Not Initialised
	long baseAHBAddress		Convenience variable, used in example to hold the base address on the AHB bus.		Not Initialised
	public UdipDevice(String className)		Super constructor. Must be called with the same string as was used to register the driver in Api.registerDevice; otherwise the methods described here will not be available. This is used to retrieve the device configuration. It will call the addCommand method – this method should be implemented to register commands using Api.registerCommand.		N/A
	void initialise()		Called by DMON main code when target is being initialised on start-up or due to “init” command. Override if it is necessary to reset registers in the device.		Empty method
	void addCommand()		Called by super constructor. Override if adding commands.		Empty method
	int getNumberOfInstances()		Not used by DMON code, exists for compatibility with similar code in DMON, where it returns the number of instances of a particular device.		Returns zero.
	ArrayList<String> getDefaultInfoSys()		Returns formatted strings representing basic information about the device which has been read from the Plug and Play or configuration – Vendor ID, Device ID, Version, Description, IRQ and addresses used if appropriate.		N/A
	ArrayList<String> getInfoSys()		Called by DMON to display information about a device, for example when the “info sys” command is galled, or the “info” button on the widget is pressed. The array of strings returned will be displayed. See also getDefaultInfoSys.		Returns getDefaultInfoSys()
	void getInfoReg()		Called by DMON to display the registers in a device on the console. See also Api.showInfoReg. That method should be used to ensure consistent formatting.		Empty method
	ArrayList<?> getDeviceList()		Not used by DMON code, exists for compatibility with similar code in DMON, where it returns the array of instances of a particular device.		Returns null
	Long getAhbStartAddress(int index)		Returns the start address on the AHB read from the plug and play area/configuration. Each device can have up to three banks on the AHB; unused banks will have start and end addresses 0. Index must be in the range [0,2] or NULL will be returned.		N/A
	Long getAhbEndAddress(int index)		Returns the end address on the AHB read from the plug and play area/configuration. Each device can have up to three banks on the AHB; unused banks will have start and end addresses 0. Index must be in the range [0,2] or NULL will be returned.		N/A
	long getApbStartAddress()		Returns the start address on the APB read from the plug and play area/configuration. Each device can have one banks on the APB; unused banks will have start and end addresses 0.		N/A
	long getApbEndAddress()		Returns the end address on the APB read from the plug and play area/configuration. Each device can have one banks on the APB; unused banks will have start and end addresses 0.		N/A
=== Example code ===
There is a commented example of how to construct a Third Party device class in <DMON installation directory>/ThirdParty.
== GDB Remote Target ==
GDB is a standard command line debugger. It needs to be ported to a particular gcc tool chain and also needs to be aware of the operating system (if any). Programmes compiled as a Bare-C or using RTEMS use sparc-rtems-gdb. Programmes compiled using sparc-elf-gcc will use sparc-elf-gdb. 
For complete details on GDB functionality, refer to the GDB Manual, available online at the following URL https://sourceware.org/gdb/current/onlinedocs/gdb/ (Note that this is for the latest version, and the versions used are typically older
GDB provides a remote protocol for communication between GDB and a target. The GDB server component of DMON supports this protocol.
DMON must be listening for GDB connections. This is done by issuing the “gdb” command at the DMON console. This takes a TCP port as an optional argument. The default port is 1234. 
GDB needs to connect to DMON. This is done by issuing the following command at the gdb prompt.
:target extended-remote <ip address/hostname of machine running DMON>:<port>
If both DMON and GDB are run on the same machine “localhost” or simply “:port” can be used.
GDB operation is then as normal. It is possible to issue any DMON command through GDB and the output of these commands is visible on the GDB console. These commands need to be prefixed with the keyword “monitor”. Note that using commands which start or stop the program will interfere with GDB knowledge of the program and will lead to errors. Break and watchpoints should only be set using GDB and run and continue should only be issued through GDB.
After loading the program, it should be started with the “run” command to ensure correct initialisation, “continue” should only be used after a breakpoint has been hit.
Note that is typically necessary to reload an RTEMS application that has been run already before running it again – this is because loading the program correctly initialises data tables used by RTEMS. 
Note that GDB will timeout after about 2 seconds if it does not receive any input from DMON. To avoid this happening an empty string is sent to GDB every 1.5 seconds when a long running command is running. This prevents the timeout but does not affect what a human user sees. It may affect what is seen in a GDB scripted session.
The user can modify the GDB Timeout by issuing the following GDB cli option or command before connecting to DMON:
:-l timeout Sets the timeout (in seconds) of any communication used by GDB for remote debugging. 
At the GDB prompt it is possible to issue the command “set remotetimeout num” which sets the timeout limit to wait for the remote target to respond to num seconds. The default is 2 seconds. If connections are causing problems it is recommended to increase this timeout.
DMON supports setting Software Breakpoints, Hardware Breakpoints and Read/Write and Access Watchpoints through GDB. There are several limitations on this; see below.
The DMON GDB Server only allows one GDB connection at a time. It will continue listening for GDB connections and serving them until either the “gdb detach” command is executed or CTRL-C is pressed for DMON. CTRL-C works as though the GDB detach command had been issued first.
There are limitations around the use of data watchpoints and hardware breakpoints:
:1.	HW Breakpoints and watchpoints are set on all CPUs in a multiple cpu system if requested by GDB. 
:2.	If GDB requests more than the number of watchpoints/hardware breakpoints that are supported by the board, DMON will return an error code. The behaviour seen by the GDB user is that GDB reports a message such as “Cannot remove breakpoints because program is no longer writable.”
If a problem is observed in conjunction with the GDB tool additional helpful information can be gained from the communications log in GDB. To get such a log, issue the command “set remotelogfile <filename>” before connecting to DMON with “target extended-remote”
== Trace Buffer and Call Graph Support ==
DMON allows a complete instruction trace to be obtained from a running application. Profile information is presented graphically and a file with each executed instruction is produced for offline analysis. This is in addition to the profile command, which samples the program counter periodically and therefore is only an estimate. 
The itrace enable command initiates the instruction trace capture. This command will only work on processors with an instruction trace capability, and the command will not be available unless the hardware support is. It will significantly slow down operation as the instruction trace buffer can only be read when the processor is stopped – therefore the processor is stopped each time the buffer is full. Note also that this feature uses the hardware breakpoint functionality, and may conflict with hardware breakpoints set by the user. It is recommended not to use HW breakpoints when using itrace.
Part of a sample profile is shown below. The vertical axis shows the function names executed, taken from the ELF symbols. The horizontal axis shows the number of times the function has been called. Different colours on the bars indicate which CPUs executed the function.
Note that the graph functionality requires ELF symbols. If there are none available then the instructions will be logged but the graph will be empty.
The detailed instruction trace data is written into the folder C:\Users\<username>\DMON\UserData on Windows or /home/<username>/DMON/UserData on Linux with the name iTraceLogDD-MM-YYYY_HHMMSS.txt. A new log file is started once 50 MB of data has been accumulated; the files from the same program run are labelled with the same time stamp but part_0, part_1 etc. in sequence. The file initially created will be renamed to part_0. An example of the start of a trace file is shown below. These files contains every instruction executed during the run and may be used for offline analysis.
 
## LOGGING STARTED 10-05-2016_143029
00470298310 cpu0 40002AD8 sethi %hi(0xa5a5a400), %g2 [A5A5A400]
00470298310 cpu3 40002278 cmp %g2, 0xc [FFFFFFF9]
00470298311 cpu0 40002ADC bset 0x1a5, %g2 [A5A5A5A5]
00470298311 cpu3 4000227C ld [%fp + 0x68], %g2 [13483119]
00470298319 cpu0 40002ADC bset 0x1a5, %g2 [A5A5A5A5]
00470298320 cpu0 40002AE0 st %g2, [%l0 + 0x3c] [410800BC]
00470298321 cpu0 40002AE4 mov 0x1, %g2 [00000001]
00470298327 cpu0 40002AE8 st %g2, [%l0 + %g0] [41080080]
00470298328 cpu0 40002AEC cmp %g1, 0x0 [00000002]
00470298329 cpu0 40002AF0 be giveToCpu + 0x104 [00000000]
00470298330 cpu0 40002AF4 sethi %hi(0x380b0000), %g1 [380B0000]
00470298333 cpu0 40002AF8 bset %g1, %i0 [380B0004]
00470298334 cpu0 40002AFC sethi %hi(0x80000000), %g1 [80000000]
00470298335 cpu0 40002B00 bset 0x210, %g1 [80000210]
00470298339 cpu3 4000227C ld [%fp + 0x68], %g2 [00000000]
00470298341 cpu0 40002B04 st %i0, [%g1 + %g0] [80000210]
00470298341 cpu3 40002280 st %g2, [%fp - 0x8] [67FFFE98]
00470298342 cpu0 40002B08 ret [40002B08]
00470298343 cpu0 40002B0C restore [00000000]
00470298343 cpu3 40002284 ld [%fp + 0x70], %g2 [00000000]
00470298349 cpu3 40002288 st %g2, [%fp - 0x4] [67FFFE9C]
00470298350 cpu3 4000228C mov %i1, %g1 [0000000A]
 
== LEON4 Statistics Module ==
If the Leon 4 statistics module is present on the target it can be configured either graphically or using commands.
It is outside the scope of this document to give a full description of the LEON4 Statistics module; the user should consult the document supplied with their particular hardware.
It should however be noted that a single device will be present on two buses, and the user should choose the interface through which the device is controlled to minimise impact on their testing.
TODO