## General commands of uCsim

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

### show

Show command can be used to display different kind of information. It must be followed by a subcommand. Subcommands are:

show copying
show warranty

#### show copying

This command can be used to list licensing information. It is first 10 point of the version 2 of GNU Genral Public License. If you do not accept GPL simply do not use the program.

#### show warranty

This command prints out last 2 point of the license ("NO WARRANTY" message).

### 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 [command]

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

If a command name is given as parameter then uCsim prints out all command that has the same name.

If parameter is unique name of a command then long description of the command is printed out.

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

### where,Where memory_type data...

Searching for some data in memory. First parameter specifies memory. Class name of the memory must be used, it can be checked using conf command which lists size and class name of all available memories.

Other parameters can be mixed list of strings (characters between " and ") and numbers. Strings can contain escape sequencies. Ucsim merges all parameters together and will search for megred list of values in specified memory.

where command do case unsensitive search while Where command is for case sensitive search.

Search is done in whole memory and all matches are dumped out.

    $ /s51
    ucsim 0.2.38-pre2, 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.
    > set mem x 20 "Dani d ani D ani dani Dani"
    0x0014 44 61 6e 69 20 64 20 61 Dani d a
    0x001c 6e 69 20 44 20 61 6e 69 ni D ani
    0x0024 20 64 61 6e 69 20 44 61  dani Da
    0x002c 6e 69                   ni
    > where x "dani"
    0x0014 44 61 6e 69             Dani
    0x0025 64 61 6e 69             dani
    0x002a 44 61 6e 69             Dani
    > Where x "d ani"
    0x0019 64 20 61 6e 69          d ani
    >

### 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 width=  8 class= "rom"
      XRAM size= 0x010000  65536 width=  8 class= "xram"
      IRAM size= 0x000100    256 width=  8 class= "iram"
      SFR  size= 0x000100    256 width=  8 class= "sfr"
    >

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 identifier

This subcommand prints out information about a unit of the controller. identifier specifies hardware element. One form of it is a name. Names of hardware elements can be checked by conf command. This form is accepted only when name is unique. If more than one element exists with the same name then name must be followed by id number is squere brackets in same form as it is listed by conf command.

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.38-pre2, 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.
    > conf
    ucsim version 0.2.38-pre2
    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 width=  8 class= "rom"
      XRAM size= 0x010000  65536 width=  8 class= "xram"
      IRAM size= 0x000100    256 width=  8 class= "iram"
      SFR  size= 0x000100    256 width=  8 class= "sfr"
    > i h port[2]
    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)
    > i h t[0]
    timer0[0] 0x0000 13 bit timer OFF irq=0 dis prio=0
    > i h u
    uart[0] Shift, fixed clock MultiProc=none irq=dis prio=0
    Receiver OFF RB8=0 irq=0
    Transmitter TB8=0 irq=0
    >

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

    $ s51 -t 52
    ucsim 0.2.38-pre2, 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 timer0
    timer0[0] 0x0000 13 bit timer OFF irq=0 dis prio=0
    > i h t[2]
    timer2[2] 0x0000 reload 0x0000 timer OFF irq=0 dis prio=0
    >

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

### set

This command can be used to set various kind of things. It requires a subcommand to specify what is going to be set. Known subcommands are:

set memory
set bit
set port
set option

#### set memory memory_type address data...

This command can be used to modify content of any simulated memory. First parameter must be a class name to specify type of memory. Class names can de checked by conf command.

Second parameter specifies start address of the modification.

Remaining parameters will be written into the memory starting at address specified by second parameter. Data list can include numbers as well as strings. See syntax for more details. q

Modified memory locations are dumped out.

    $ s51
    ucsim 0.2.38-pre2, 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.
    > set mem x 1 "ab\tcd\0ef\012ghq" 2 "ABC"
    0x0001 61 62 09 63 64 00 65 66 ab.cd.ef
    0x0009 0a 67 68 71 02 41 42 43 .ghq.ABC
    > set mem sfr pcon 0x34
    0x87 34                      4
    >

#### set bit address 0|1

Set one bit to 0 or 1. First parameter specifies the bit. It can be the address of the bit (number or syqmbolic name) or it can be specified in address.bitnumber format where address addresses SFR area and bitnumber is number of bit in specified SFR location. Using this syntax any SFR (and 8051's internal RAM) location can be modified it need not be really bit addressable.

Second parameter interpreted as 1 if it is not zero.

Modified memory location is dumped out.

    $ s51
    ucsim 0.2.38-pre2, 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.
    > set bit tf1 1
    0x88 80 .
    > set bit 130 0
    0x80 fb .
    > set bit pcon.2 1
    0x87 04 .
    > set bit 10.7 1
    0x0a 80 .
    >

#### set port hardware_id data

This command can be used to set value of external circuits which connected to ports of simulated controller. First parameter specifies port number. It can be an array which specifies a hardware element or simply a number.

    > set port 0 12
    > i h po[0]
    port[0]
    P0    11111111 0xff 255 . (Value in SFR register)
    Pin0  00001100 0x0c  12 . (Output of outside circuits)
    Port0 00001100 0x0c  12 . (Value on the port pins)
    > set port port[0] 23
    > i h po[0]
    port[0]
    P0    11111111 0xff 255 . (Value in SFR register)
    Pin0  00010111 0x17  23 . (Output of outside circuits)
    Port0 00010111 0x17  23 . (Value on the port pins)
    >

#### set option name value

Set option value. Options described at (get option) command 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.38, 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.
    > get opt
    verbose TRUE Verbose flag.
    stopit FALSE Stop if interrupt accepted.
    debug FALSE Debug messages appears on this console.
    > set opt debug t
    > get opt
    verbose TRUE Verbose flag.
    stopit FALSE Stop if interrupt accepted.
    debug TRUE Debug messages appears on this console.
    >

### get

This command can be used to get value of various kind of things. It requires a subcommand to specify what is going to be set. Known subcommands are:

get sfr
get option

#### get sfr address...

This command can be used to check values of SFR location(s) if SFR exists in simulated memory. Note that dump memory or ds can be used as well.

Parameters are interpreted as SFR names or addresses and values of addressed locations are dumped out.

    $ s51
    ucsim 0.2.38-pre2, 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.
    > get sfr pcon p1 0 0x80 kahd scon
    0x87 00 .
    0x90 ff .
    0x00 00 .
    0x80 ff .
    Warning: Invalid address kahd
    0x98 00 .
    >

#### get option name

Get actual value of option(s). Some options can be set by set option to modify behavior of the simulator. Using get option 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.38, 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.
    > get opt
    verbose TRUE Verbose flag.
    stopit FALSE Stop if interrupt accepted.
    debug FALSE Debug flag.
    > get opt 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 set option 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.

### fill memory_type start end data

Fill memory region with specified data. First parameter specifies memory. Class name of the memory must be used, it can be checked using conf command which lists size and class name of all available memories.

start and end parameters specify first and last address of the memory region to be filled.

data parameter specifies the data which is used to fill the memory region.

    $ s51
    ucsim 0.2.38-pre2, 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.
    > fill x 12 0x12 0x56
    > dump x 0 0x20
    0x0000 00 00 00 00 00 00 00 00 ........
    0x0008 00 00 00 00 56 56 56 56 ....VVVV
    0x0010 56 56 56 00 00 00 00 00 VVV.....
    0x0018 00 00 00 00 00 00 00 00 ........
    0x0020 00                      .
    >