Dakotah Lambert

teddy(1)

Name

teddy - URSA software simulator and debugger

Synopsis

teddy [-hqrv?] [-d size] [-t size] [prefix]

Description

The teddy utility provides an interactive environment for simulating and debugging programs written for the URSA architecture. If the prefix is specified, then an attempt is made to read each of “prefix.lcode” for the program code in the text segment, “prefix.ldata” for the initial data memory in the data segment, and “prefix.map” for the symbol table. If at least one of the first two is successful, then a program is considered to have been loaded; missing segments are zero-filled with a warning. If “prefix.map” does not exist or cannot be read, no warning is emitted. Inside the interactive environment, the commands are as follows.

breakpoint delete index

Permanently deactivate the breakpoint with the given index. Breakpoints and watchpoints are tracked together, so this also handles watchpoints

breakpoint list

Enumerate active breakpoints and watchpoints by index and target location.

breakpoint set location

Configure the system to stop the program when the specified location in instruction memory is reached, before executing the instruction there. Reports the index of the created breakpoint.

continue

Run until halt, defined as successful execution of either a conditional branch with displacement zero or a conditional move from pc to itself. Only a breakpoint or watchpoint will pause execution.

disassemble [location [size]]

Display a human-readable code listing for a region of instruction memory. The location determines where to start disassembly and defaults to the beginning of the current function, if found, else the current location. The size determines how many instructions to emit and defaults to the size of the current function, if found, else ten.

dump region location size

Show memory as a hex dump. The region may be either text for instruction memory or data for data memory. The location is the address from which to begin reading. The size is the number of bytes to include in the output.

help [command]

List commands, or, if a command is specified, give details about that command.

load prefix

Read a program from the given prefix as if it were specified on the command line.

map

Display a list of symbols and their locations.

memory read format location

Display a value in memory per the format.

byte	Unsigned 8-bit decimal value
hword	Unsigned 16-bit decimal value
word	Unsigned 32-bit decimal value
sbyte	Signed 8-bit decimal value
shword	Signed 16-bit decimal value
sword	Signed 32-bit decimal value
xbyte	8-bit hexadecimal value
xhword	16-bit hexadecimal value
xword	32-bit hexadecimal value

For 16- and 32-bit values, the location is masked for appropriate alignment. In all cases, the actual location used is reported alongside the result.

memory write format location value

Update a value in data memory per the format.

byte	8 bits
hword	16 bits
word	32 bits

For 16- and 32-bit values, the location is masked for appropriate alignment. Values are written in little-endian order.

next

Execute instructions until the next instruction in memory is reached or the program halts. If the current instruction is a subroutine call, this runs that subroutine. Execution will pause early if a breakpoint or watchpoint is triggered.

out

Execute instructions until the program counter matches the current value of rp. In a subroutine, this typically means to run until return.

quit

Exit the simulation.

register read [name …]

For each given name, display the contents of the register so named. Registers may be specified in their decimal forms (r0–r15), their hexadecimal forms (ra–rf), or their usage-based forms (rT, fp, sp, rp, pc, and sr). All forms are case-insensitive. Also accepted are ‘*’ for “all registers” or ‘!’ for “all nonzero general-purpose registers”.

register write name value

Overwrite the register of the given name with the given value. The register may be specified in decimal form (r0–r15), in hexadecimal form (ra–rf), or in usage-based form (rT, fp, sp, rp, pc, or sr). All forms are case-insensitive.

reset

Set all registers to zero. To redo initialization of data memory, load the program again.

step

Execute a single instruction.

to location

Run until reaching the given location. Execution will pause early if a breakpoint or watchpoint is triggered.

version

Print the program version.

watchpoint delete index

Permanently deactivate the watchpoint with the given index. Watchpoints and breakpoints are tracked together, so this also handles breakpoints.

watchpoint list

Enumerate active watchpoints and breakpoints by index and target location.

watchpoint set location

Configure the system to stop the program after the specified location in data memory is written to. Reports the index of the created watchpoint.

Anywhere that a location is required, its value may be specified in any of the following forms.

• name
  The symbol by the given name. If multiple such symbols exist, it must be disambiguated by also naming the object file, like file:name.
• number
  An integer value.
• name + number
  A symbol with positive displacement. The spaces around the operator are necessary.
• name - number
  A symbol with negative displacement. The spaces around the operator are necessary.

Only the second is possible without a symbol table.

Options

The following flags may be specified in any order.

-d size

Use data memory of size bytes. The suffixes ‘K’, ‘M’, and ‘G’ multiply by successive powers of 1024, to supply sizes in kibibytes, mebibytes, or gibibytes. The size must be a power of two less than four gibibytes.

-h, -?

Print a brief help message and exit.

-q

Quit the simulator and print any nonzero register values when the program halts.

-r

If a prefix is specified on the command line and it references a program that is successfully loaded, run that program at startup without awaiting a command.

-t size

Use instruction memory of size bytes. The suffixes ‘K’, ‘M’, and ‘G’ multiply by successive powers of 1024, to supply sizes in kibibytes, mebibytes, or gibibytes. The size must be a power of two less than four gibibytes.

-v

Print the version of the program and exit.

Exit Status

The teddy utility exits 0 on success, and >0 if an error occurs.

See Also

aster(1), starlink(1)