General commands of uCsim

Some commands can be repeated by entering an empty command (just pressing ENTER if command console is interactive). This repeats the full command entered previously precisely including parameters of the command. Repeatable commands are signed with [Repeatable]

icon.

Some commands accept parameters which in most cases can be numbers. Numbers can be entered in C-style form. If the number begins whith 0x or 0X it is interpreted as a hexadecimal number. If it begins with 0 followed by digits it is interpreted as octal number. In other cases it is interpreted as decimal number.

Every command which changes content of ROM area such as l, dl or sc deletes result of code analyzer and causes to re-analyze the code.

show c|w

This command can be used to list licensing information. If c option has given, the license is listed. It is first 10 point of the version 2 of GNU Genral Public License. Using w parameter the command prints out last 2 point of the license ("NO WARRANTY" message). If you do not accept GPL simply do not use the program.

download,dl

Download command. It is same as load above but it reads information from command console which is standard input by default. This command stops read records when it detects an "END" record which is normaly the last record. This command has two equivalent forms download and dl.

$ s51 -V
ucsim 0.2.24, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> do
:03000000020003F8
:1000030075812078207600D8FC900000AE83AF8203
:100013009000001200416005E4F0A380F690009F79
:1000230012004A9000A312004A9000A712006890A1
:1000330000AD12006875D0001200B50200B3EF6581
:10004300827003EE658322E493F8740193F97402DA
:1000530093FE740393F5828E83E869700122E4931F
:10006300F6A30880F4E493FC740193FD740293FEF9
:10007300740393FF740493F8740593F582888312D1
:100083000041700122E493A3A883A9828C838D820B
:10009300F0A3AC83AD828883898280E3212100B5FC
:1000A300212100B5000000B500B5000000B500B582
:0200B30080FECD
:1000B5007520117501AA850120750102850120228F
:00000001FF
197 bytes loaded
>

quit

Quit. This command terminates actual console, it does not ask you to confirm your intention. Simulator always reads commands from a file so end of file condition finishes too. If command console is on standard input/output, pressing the CTRL-D will quit just like the quit command.

Note that if -Z option was used at invokation then the quit command does not terminate the simulator program. In this case kill command can be used to terminate the simulator. See for more information about using multiple consoles.

$ s51
ucsim 0.2.24, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> q
$

kill

This kommand terminates the simulator. It does not ask for confirmation. It doesn't matter how many consoles are used and what commands are running on them.

help,?

Help command. It prints out short description of the commands.

reset

Reset command. It resets the microcontroller. It has same effect as active signal on the RST pin.

$ s51 -V remoansi.hex
ucsim 0.2.24, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
58659 bytes read from remoansi.hex
> dr
000000 00 00 00 00 00 00 00 00 ........
000000 00 .  ACC= 0x00   0 .  B= 0x00   DPTR= 0x0000 @DPTR= 0x00   0 .
000000 00 .  PSW= 0x00 CY=0 AC=0 OV=0 P=0
   000000 02 01 60 LJMP  0160
> s 2
000000 00 00 00 00 00 00 00 00 ........
000000 00 .  ACC= 0x00   0 .  B= 0x00   DPTR= 0x0000 @DPTR= 0x00   0 .
000000 00 .  PSW= 0x00 CY=0 AC=0 OV=0 P=0
   000160 c2 90    CLR   P1.0
000000 00 00 00 00 00 00 00 00 ........
000000 00 .  ACC= 0x00   0 .  B= 0x00   DPTR= 0x0000 @DPTR= 0x00   0 .
000000 00 .  PSW= 0x00 CY=0 AC=0 OV=0 P=0
   000162 c2 97    CLR   P1.7
> res
> dr
000000 00 00 00 00 00 00 00 00 ........
000000 00 .  ACC= 0x00   0 .  B= 0x00   DPTR= 0x0000 @DPTR= 0x00   0 .
000000 00 .  PSW= 0x00 CY=0 AC=0 OV=0 P=0
   000000 02 01 60 LJMP  0160
>

wi,Wi string

Searching for specified string in internal RAM area. String is interpreted from first non-space sharacter until end of the command including spaces. wi command makes case insensitive search and Wi can be used to make case sensitive search. Result is a hexa dump of memory areas that match with specified string. Most of C-style escape sequences can be used in the string: \f, \n, \r, \t, \v, \a, \b, \0, and \0xxx where xxx is an octadecimal number of the code of the character.

$ s51 remoansi.hex
ucsim 0.2.24, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
58659 bytes read from remoansi.hex
> g
Simulation started, PC=0x000000

Stop at 00019c: (7) User stopped
F 00019c
> si 20 Dani DAni
000014 44 61 6e 69 44 41 6e 69                         DaniDAni
> wi dani
000014 44 61 6e 69             Dani
000018 44 41 6e 69             DAni
> Wi Dani
000014 44 61 6e 69             Dani
> wi dani\0
000018 44 41 6e 69 00          DAni.
>

wx,Wx string

Search commands. These commands are similar to wi, Wi commands the only difference is that wx,Wx are used to search for a string in external memory.

wc,Wc string

Search commands. These commands are similar to wi, Wi commands the only difference is that wx,Wx are used to search for a string in code memory area.

gopt [opt]

Get actual value of option(s). Some options can be set by sopt to modify behavior of the simulator. Using gopt you can get actual value of these options. If you use this command without parameter you get list of all options known by the program. In this way you can figure out which options can be used.

$ s51 -V
ucsim 0.2.24, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> gopt
verbose TRUE Verbose flag.
stopit FALSE Stop if interrupt accepted.
debug FALSE Debug flag.
> gopt stopit
stopit FALSE Stop if interrupt accepted.
>

This version of the simulator knows about three options. First element of the list is name of the option (verbose, debug and stopit). This name can be used to identify the option in gopt and sopt command. Second element of the list is the value of the option. In this case type of both options is boolean, their value can be TRUE or FALSE. Third element is a short description of the option.

verbose: ?
debug: Debug flag can be set by -V option of the program to TRUE otherwise its default value is FALSE. If it is TRUE, the simulator prints out short messages about important events.
stopit: Setting this option to TRUE (default value is FALSE) forces execution to stop every time when CPU accepts an interrupt. You do not have to use breakpoints to inspect interrupts.

sopt opt value

Set option value. Options described at previous command (gopt) can be set using this command. First parameter must be an option name and second the new value. Interpretation of the value depends on type of the option. Value for a boolean type of option interpreted as follows: if first character of the value is one of 1, t, T, y, Y then value will be TRUE otherwise it will be FALSE.

$ s51 -V
ucsim 0.2.24, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> gopt
verbose TRUE Verbose flag.
stopit FALSE Stop if interrupt accepted.
debug FALSE Debug messages appears on this console.
> sopt debug t
> gopt
verbose TRUE Verbose flag.
stopit FALSE Stop if interrupt accepted.
debug TRUE Debug messages appears on this console.
>

conf

This command prints out configuration of the simulator:

> conf
ucsim version 0.2.37
Type of microcontroller: 51 CMOS
Controller has 8 hardware element(s).
  timer0[0]
  timer1[1]
  uart[0]
  port[0]
  port[1]
  port[2]
  port[3]
  irq[0]
Memories:
  ROM  size= 0x010000 65536
  XRAM size= 0x010000 65536
  IRAM size= 0x000100 256
  SFR  size= 0x000100 256
>

First line contains version number of the program. Second line informs about type of the simulated microcontroller. Third line prints out how many hardware elements are simulated. Following lines contain information about memories. Note that size of the simulated memory segment can be bigger than size of addressable part of the memory as you see above SFR type of the memory has bigger simulated than addressable size.

state

State of the simulator and the simulated microcontroller:

> state
CPU state= OK PC= 0x004349 XTAL= 1.10592e+07
Total time since last reset= 0.614873 sec (6800004 clks)
Time in isr = 0.0144227 sec (159504 clks) 2.3%
Time in idle= 0 sec (0 clks)   0%
Max value of stack pointer= 0x000049, avg= 0x000026
>

The "CPU state" in the first line is an internal information. PC is value of the program counter. First line shows XTAL frequency too.

Following lines contain information about simulated time. First, full simulated time (elapsed from last reset) is printed out in seconds and number of clock periods then same data is printed out about time spent in interrupt service routines as well as in idle mode. Last data in lines of ISR and IDLE time shows ratio of ISRs, Idle times and main program.

Last line infroms about maximum value of the stack pointer and a "not very well" calculated average value of it.

file,load "FILE"

Loads file named FILE into the simulated code memory. File must contain data in Intel HEX format.

> file "../../remo.hex"
55470 words read from ../../remo.hex
>

Don't forget to enclose file name in quotes to make the parameter to be a string.

info

This command prints out information about different things which must be specified as paramater to the command. Following subcommands are known:

info breakpoints
info registers
info hardware

info breakpoints

This subcommand prints out information about breakpoints:

> b 12
Breakpoint 1 at 0x00000c: MOV   R7,A
> tb 43
Breakpoint 2 at 0x00002b: MOV   R7,A
> bse ws f 0x80
> i b
Num Type       Disp Hit   Cnt   Address  What
1   fetch      keep 1     1     0x00000c MOV   R7,A
2   fetch      del  1     1     0x00002b MOV   R7,A
1   event      keep 1     1     0x000080 ws
>

As you see above, the command can be shortened to "i b". The list of breakpoints contains 7 columns:

Num: Number of the breakpoint. Normal and event breakpoints are numbered separately.
Type: This column shows type of the breakpoint. It can be fetch for normal breakpoints or event for event breakpoints. First the normal breakpoints are listed and then the event breakpoints.
Disp: This shows if the breakpoint is temporary (del) or not (keep).
Hit: How many times the breakpoint must be hit before it really stops the program.
Cnt: Counter of breakpint hits. This counter decrements and the breakpoint is activated if it reaches zero.
Address: Address where the breakpoint is set.
What: For normal breakpoints this field contains disassembled instruction where the breakpoint is set. For event breakpoints it contains type of event.

info registers

This subcommand prints out full register set of the CPU. Output of this command depends of type of CPU.

Registers of MCS51 family

$ s51 remoansi.hex 
ucsim 0.2.12, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
58659 bytes read from remoansi.hex
> sopt stopit 1
> g
5
 * 000023 02 01 1c LJMP  011c
> i r
000000 18 02 16 ba 00 02 00 0a ........
000018 4a J  ACC= 0x0a  10 .  B= 0x00   DPTR= 0x16ba @DPTR= 0x00   0 .
000002 16 .  PSW= 0x00 CY=0 AC=0 OV=0 P=0
 * 000023 02 01 1c LJMP  011c
>

In first line the actual register bank is dumped out. Register banks reside in internal RAM, address at the begining of the line shows start address of actual register bank selected by RS0 and RS1 bits of PSW register.

Next two lines begin with value of indirectly addressed internal RAM cells. Second line shows IRAM cell pointed by R0 while third line shows IRAM addressed by R1.

Second line displays some important registers. First one is the accumulator. Its value dumped out in hexadecimal, decimal form and then the ASCII character of its value. It is followed by value of the B register which is dumped out in hexadecimal form only. Next is DPTR register in hexadecimal and then external RAM cell which is addressed by DPTR. This is dumped out in hexadecimal, decimal and ASCII too.

In third line you find program status word in hexadecimal and then some flag bits of PSW register. Last line is disassembled instruction at PC.

Registers of AVR family

$ savr test_arith.hex
ucsim 0.2.37, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> 83 words read from test_arith.hex
83 words read from test_arith.hex
> run

Stop at 0x000047: (105) User stopped
F 0x000047
> i r
000000 00 2c 21 23 20 35 19 14 03 00 00 00 00 00 00 00 .,!# 5..........
000010 00 01 1e 89 01 00 10 e2 14 00 01 10 00 00 00 00 ................
ITHSVNZC  SREG= 0x03   3 .
00000011  SP  = 0x000000
X= 0x1001 [X]= 0x00   0 .  Y= 0x0000 [Y]= 0x00   0 .  Z= 0x0000 [Z]= 0x00   0 .
 * 000047 940c 0047 jmp   0x000047
>

First two lines show first 32 bytes of internal RAM which is the register set of AVR controllers.

At the beginning of next two lines bits of status register are printed. These lines present hexadecimal, decimal and ASCII values of the status register too, and value of the stack pointer.

Following line shows indirect addressing registers X, Y, and Z as well as pointed memory values.

Last line is disassembled instruction ap PC.

info hardware|hw cathegory [id]

This subcommand prints out information about a unit of the controller. Cathegory can be:

timer
uart
port
pca
interrupt
wdt

Ouput format of this command depends on CPU family and type of the CPU too because requested unit can be different in different type of controller even in the same CPU family.

$ s51 -t 51
ucsim 0.2.36, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> i h t
timer0[0] 0x0000 13 bit timer OFF irq=0 dis prio=0
timer1[1] 0x0000 13 bit timer OFF irq=0 dis prio=0
>

Timer #2 differs a little bit from other timers of MCS51:

$ s51 -t 52
ucsim 0.2.36, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> i h t
timer0[0] 0x0000 13 bit timer OFF irq=0 dis prio=0
timer1[1] 0x0000 13 bit timer OFF irq=0 dis prio=0
timer2[2] 0x0000 reload 0x0000 timer OFF irq=0 dis prio=0
>

If the controller contains more than one unit of a cathegory, then optional id parameter can be used to select a specific one. If id is not used then information is printed about all units belonging to specified cathegory.

> i h t 1
timer1[1] 0x0000 13 bit timer OFF irq=0 dis prio=0
>

It is possible that there is no unit belonging to some cathegory. It is also possible that the specific unit exists but information command of that unit is not implemented, in this case you have to check SFRs of the unit...

> i h pca
>

Information you can get about units of MCS51 controllers:

$ s51 -t 251 
ucsim 0.2.37, Copyright (C) 1997 Daniel Drotos, Talker Bt.
ucsim comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
> g
Simulation started, PC=0x000000

Stop at 0x000023: (105) User stopped
F 0x000023
> i h t
timer0[0] 0xaa8d 16 bit timer ON irq=0 en prio=0
timer1[1] 0xfdff 8 bit autoreload timer ON irq=1 dis prio=0
timer2[2] 0x0000 reload 0x0000 timer OFF irq=0 dis prio=0
> i h u
uart[0] 8 bit UART timer clocked MultiProc=none irq=en prio=1
Receiver ON RB8=1 irq=0
Transmitter TB8=1 irq=1
> i h po
port[0]
P0    11111111 0xff 255 . (Value in SFR register)
Pin0  11111111 0xff 255 . (Output of outside circuits)
Port0 11111111 0xff 255 . (Value on the port pins)
port[1]
P1    11111111 0xff 255 . (Value in SFR register)
Pin1  11111111 0xff 255 . (Output of outside circuits)
Port1 11111111 0xff 255 . (Value on the port pins)
port[2]
P2    11111111 0xff 255 . (Value in SFR register)
Pin2  11111111 0xff 255 . (Output of outside circuits)
Port2 11111111 0xff 255 . (Value on the port pins)
port[3]
P3    11111111 0xff 255 . (Value in SFR register)
Pin3  11111111 0xff 255 . (Output of outside circuits)
Port3 11111111 0xff 255 . (Value on the port pins)
> i h i
Interrupts are enabled. Interrupt sources:
  Handler  En  Pr Req Act Name
  0x000003 en   1 no  act external #0
  0x00000b en   0 no  act timer #0
  0x000013 en   1 no  act external #1
  0x00001b dis  0 YES act timer #1
  0x000033 dis  0 no  act PCA counter
  0x000033 dis  0 no  act PCA module #0
  0x000033 dis  0 no  act PCA module #1
  0x000033 dis  0 no  act PCA module #2
  0x000033 dis  0 no  act PCA module #3
  0x000033 dis  0 no  act PCA module #4
  0x000023 en   1 YES act serial transmit
  0x000023 en   1 no  act serial receive
  0x00002b dis  0 no  act timer #2 TF2
  0x00002b dis  0 no  act timer #2 EXF2
Active interrupt service(s):
  Pr Handler  PC       Source
   1 0x000023 0x003672 serial transmit
>

timer a|d|g|r|s|v id [value]

Handling of timers. First parameter of timer command determines the operation which can be

add (or simply a): to create a new timer. New timers are turned ON by default and initialized to value 0.
del (or simply d): to remove a timer if you don't need it any more.
get (or simply g): to get value of timers. See comment below.
run (or simply r): to turn a timer ON.
stop (or simply s): to turn a timer OFF. It still exist but doesn't count xtal periods.
value (or simply v): to set value of the timer (number of xtal periods). `param' is the new value.

id can be a number or a string. Timers are numbered from 1. You can use any number greater than 0 to identify a timer. Or you can use a simbolic name, in this case simulator uses the first unused number to allocate a new timer:

> tim a 3
> tim g 0
timer #0("time") ON: 0.463255 sec (5123232 clks)
timer #0("isr") ON: 0.0051888 sec (57384 clks)
timer #3("unnamed") ON: 0 sec (0 clks)
> tim a "a"
> tim g 0
timer #0("time") ON: 0.463255 sec (5123232 clks)
timer #0("isr") ON: 0.0051888 sec (57384 clks)
timer #1("a") ON: 0 sec (0 clks)
timer #3("unnamed") ON: 0 sec (0 clks)
>

If you use 0 as timer id in "get" operation, simulator prints out value of all timers including predefined ones.