Complx

Introduction
Complx pronounced Complex but spelled without the e is an alternative to simpl (an old lc3 simulator).
The goal of complx is to provide a simulator with more debugging features and make assembly
programming with the C3 much easier. !nother goal of complx is to enforce the rules when writing
assembly programs.
"creenshot
#hen complx is started up you will get a screen similar to this.
The console window allows the user to see the output of the program and any warnings their code
generated. ($ote% It may be minimi&ed when the program starts)
The main program view shows a view of the C3 memory the registers and the 'C. It also allows the
user to step through their program and change values(instructions in memory and registers on the fly.
)ow to use (! #alkthrough)
"hown below is the main view of Complx.
*. This is a view of the C+3 memory you may see all of the addresses and what value it is in
many bases. It also shows what symbol exists at that address and the disassembled instruction
,. -or the C+3 we express hexadecimal numbers preceding them with .ust an x (lowercase x).
/ou may type hexadecimal numbers here and you will modify the address.
3. -or the C+3 we express decimal numbers preceding them with either 0 or nothing. I chose to
display the decimal numbers without the 0 sign.
1. -or the C+3 there is no way (as far as I know) to express a number as binary however you
should not need to use binary. )owever for complx you can express binary in this column.
2. )ere you can type a symbol for the location.
3. The Instruction column shows you what the instruction disassembles to. /ou may change the
level that complx disassembles to in menu 4iew 5 6isassemble. /ou can also type an C+3
instruction here and it will assemble it for you Quick Fix.
7. )ere is the play area the buttons are explained as follows
a. 8un 9 8uns your code until it )!Ts. If it appears your code is going into an infinite
loop you can stop it by hitting the button again.
b. 8un -or 9 8uns your code for at most : instructions; enter a negative number to undo at
most : instructions
c. "tep 9 8uns only one instruction.
d. <ack 9 =ndoes the actions of one instruction
e. $ext ine 9 8uns one line in the program (If the line happens to be a subroutine call
then it will not step into it)
f. 'revious ine 9 <ack steps one line in the program (If the line happens to be a
subroutine call then it will not step into it)
g. -inish 9 -inishes the current subroutine you are in ("tep >ut of the subroutine)
h. 8ewind 9 =ndoes all of the instructions in the undo stack
?. 8egister 4iew. )ere you can see all of the registers including the CC register and the 'C here.
/ou can also edit the register@s values on the fly.
Tip% 6ouble click on the text box for a given register and you will change the base it
displays.
Tip% you may also enter expressions when editing a registers value ex. 8A B 8* B 'C 9
CDCEx3AAAF (!dd 8A and 8* and the 'C subtracted by what@s in memory address
x3AAA)
G. Dxecutions. This shows you how many instructions your code executed before it )!Ted
*A. #arnings. This shows how many warnings your code generated (/our code must not produce
any warnings).
Cenus
*. -ile Cenu
8andomi&e and oad 9 8andomi&es memory and loads an assembly file
8andomi&e and 8eload 9 8andomi&es memory are loads the last assembly file
oad 9 oads an assembly file and reinitiali&es the machine.
8eload 9 oads the last assembly file loaded and reinitiali&es the machine.
oad >ver 9 oads an assembly file over the machines current state.
8eload >ver 9 oads the last assembly file loaded over the machines current state.
oad Cachine 9 oads a machine state file.
8eload Cachine 9 8eloads the last machine state file loaded.
Huit 9 Dxits the program.
,. 4iew Cenu
$ew 4iew 9 Creates a new memory view.
Ioto !ddress 9 Jumps an address in memory
Tip% /ou can enter an expression
6isassemble 9 Ddits the disassembling options
<asic 9 6oes a straight disassemble without symbol table information.
$ormal 9 6isassembles with symbol table information.
)igh evel 9 6isassembles into something C+ike.
Instruction )ighlighting 9 )ighlights different portions of the instruction.
=nsigned 6ecimal 9 6isplay decimal values as unsigned.
3. "tate
Control 9 'lays through or rewind instructions.
"tep (-,) 9 'lays one instruction
<ack ("hift B -,) 9 =ndoes one instruction
$ext ine (-3) 9 'lays one line (does not step into subroutines; traps; or interrupt
handlers)
'revious ine ("hift B -3) 9 =ndoes one line (does not step into subroutines;
traps; or interrupt handlers)
8un (-1) 9 8uns until it halts
8un -or (Ctrl B -1) 9 8uns for : instructions until it halts (asking everytime)
8un !gain (Ctrl B "pace) 9 8uns for : instructions until it halts (asking once)
8ewind ("hift B -1) 9 =ndoes all instructions in the undo buffer
-inish ("hift B -2) 9 "teps out of a subroutine; trap; or interrupt handler
8andomi&e 9 8andomi&es memory and registers.
8einitiali&e 9 8esets memory to an initial state.
True Traps 9 Dnables true trap handling.
Interrupts 9 Caster interrupt switch allows devices to generate interrupts
Clear Console 9 Clears the C+3 console.
Clear Console Input 9 Clears all of the input waiting in the console
1. 6ebug
=ndo "tack 9 "ets the undo stack; how many instructions you can go back. (The default
is 32233 instructions).
<reakpoints and #atchpoints 9 4iews all break points and watch points entered.
!dd Temporary <reakpoint 9 !dds a one time breakpoint.
!dd <reakpoint 9 !dds a permanent breakpoint.
!dd #atchpoint 9 !dds a watch point on a memory address or register.
!dd !dvanced <reakpoint 9 !dds a conditional breakpoint.
!dd <lackbox 9 !dds a blackbox (you will never step into something thats blackboxKd)
2. Test
8un Tests 9 8uns an lc3test xml file
8erun Tests 9 8uns the last test file to be loaded
3. )elp
6ocumentation 9 6isplays this file you are reading.
C+3 I"! 9 6isplays the C+3 I"! document.
!bout 9 6isplays information about this application.
6ebugging
The debugging menu is Complx@s prime feature. It allows the user to set various breakpoints and
watchpoints in memory so that they can find a bug more easily. )ere are the menu options and relevant
menus and how to effectively use them.
*. !dd Temporary <reakpoint 9 "hortcut -?
a. !dds a temporary breakpoint what this means is that when the breakpoint has been triggered it
disappears. This is useful if you want to run code until a certain point in your program.
,. !dd <reakpoint 9 "hortcut -G
a. !dds a breakpoint unlike the temporary breakpoint once it has been triggered it does not
disappear. #hen the code reaches this point it will stop your code.
3. !dd <lackbox 9 "hortcut -2
a. /ou can add a blackbox to a subroutine; trap; or interrupt handler
here. ! blackbox will automatically completely execute the thing
that is blackboxKd when it is encountered.
1. !dd #atchpoint 9 "hortcut -**
a. !dds a watchpoint. ! watchpoint is a special type of breakpoint
that activates only when a value is written to memory; in this case
memory or a register.
b. 'arameters are as follows%
i. Name 9 #atchpoint name. )as no effect on its operation
ii. Target 9 #atchpoint target. Can be an address or a register.
iii. Condition 9 ! <oolean expression that is evaluated when
the target is written to. If the result is A it does not activate
the watchpoint if the result is not A then the watchpoint
activates and stops execution. Dxample CDCEAx3AAAF 5 ,2.
iv. Times 9 The number of times the watchpoint needs to be
triggered before it is deleted. (+* means permanent)
v. Hits 9 ets you know how many times the watchpoint has
been activated.
vi. Enabled? 9 6isables or enables the watchpoint.
2. !dd !dvanced <reakpoint 9 "hortcut -*,
a. !dds an advanced breakpoint. /ou can modify many different
parameters of the breakpoint here.
b. 'arameters are as follows%
i. Name 9 <reakpoint name. )as no effect on its operation.
ii. Address 9 !ddress where the breakpoint sits.
iii. Condition 9 ! <oolean expression that is evaluated when the
code reaches the breakpoint. If the result is A it does not
activate the breakpoint if the result is not A then the
breakpoint activates and stops execution. Dxample 8A 5 ,2.
iv. Times 9 The number of times the breakpoint needs to be
triggered before it is deleted. (+* means permanent).
v. Hits ets you know how many times the breakpoint has
been activated.
vi. Enabled 6isables or enables the breakpoint.
3. <reakpoints and #atchpoints 9 "hortcut -7
a. 4iews all breakpoints and watchpoints that are currently created
b. )ere you can add additional breakpoints(watchpoints; edit; or delete them.
Testing
The testing menu was added as of Complx 1. This menu has similar gui based functionality as the
textual based program lc3test introduced >ctober ,A*,. This menu can be accessed by selecting 8un
Tests and giving it an xml file that contains the test cases. !fterward you will get a screen similar to
this.
In the left widget a control is present to show you all of the tests and conditions that are present within
the test file in a hierarchical structure. To the right is a panel that shows information about the item that
is selected from the left control.
6efinitions you should know is that there are three things you can select from the tree structure to your
left.
! Test Suite which contains many tests.
! Test which specifies the pre and post conditions for the test and other features about how the state of
the lc3 should be when the test is ran.
!nd Postconditions which are conditions which must be true after the test has completed.
The buttons on the bottom do the following
*. Test 8eport. Iives a report about how a particular test went. $ote that a test must be selected
in order for the report to be generated.
,. -ull 8eport. Iives a report about the entire Test "uite.
3. 8un Test. 8uns a single test. $ote that a test must be selected for this to work
1. 8un Tests. 8uns all of the tests in the test suite.
)ere since the file (testLtest.xml; a Test "uite) was selected it will show information about the stats
about everything in the test suite%
*. #hether or not you passed the entire test suite.
,. The number of tests you completely passed
3. The number of post conditions you have passed (as a total)
1. !nd all of the tests associated with the test suite.
#hen a test is selected the screen on the right changes to show the stats for the test that was selected.
/ou should get a screen similar to the following.
)ere the following is displayed
*. The name of the test case Dxhaustive pointer in this case.
,. The number of post condition checks that passed
3. The number of instructions that was executed before the machine halted.
1. 'arameters about the states environment that will be true when the test is ran.
2. The preconditions of this test. Cemory address x7AA, will be set to x3AAA.
3. The post conditions that will be checked after the test is ran.
#hen a post condition is selected from the control on the left the screen on the right changes to show
stats about the post condition.
)ere the following information is displayed
*. #hether or not youKve passed the post condition.
,. ! textual string representing the condition that needs to be passed.
3. The expected value or right hand side of the condition.
1. The actual value your code produced or the left hand side of the condition.