Tcl/Python Scripts

From dmon2
Jump to navigationJump to search

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.

Gui-tclio.gif

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')

Gui-pythonexec.gif

• Using the Python edit window in the GUI.

Gui-pythonedit.gif

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


Gui-pythonexample.gif

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.

Gui-pythonexample2a.gif

Gui-pythonexample2b.gif

Gui-pythonexample2c.gif

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.

Gui-scriptflowchart.gif

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.

Gui-scripttasks.gif