Dakotah Lambert

About

The URSA RISC System Architecture is a 32-bit CPU architecture designed specifically for exploration and experimentation in a classroom setting. The key competing design goals are simplicity and utility. It should be feasible to implement the processor in a circuit simulator within a single semester, but it should be powerful enough to handle real-world problems. A reference implementation is provided in software, as well as some build tools: an assembler and a static link editor.

Documentation

The primary documentation for the system is the book URSA RISC System Architecture, available in print in hardcover and paperback. For each of the software components, its online documentation is replicated here.

• aster(1) - assembler for the URSA architecture
• starlink(1) - static link editor for the URSA architecture
• teddy(1) - URSA software simulator and debugger
• aster(5) - assembly language for the URSA architecture

Installation

The tools are distributed in source form via git. See the included README.md for full details.

Prerequisites

• Git, to check out the sources
• Any C compiler supporting at least C99 (Clang, GCC, MSVC)
• GNU Make (or, on Microsoft Windows, NMAKE)

These are all generally preinstalled on modern Unix-like systems (like macOS, Linux, the various BSDs, Solaris, and Haiku). If they are not preinstalled, they should be available from the system package manager.

On Unix-Like Systems

git clone https://github.com/vvulpes0/ursatools.git
cd ursatools
make && sudo make install

Installation is to /usr/local by default.

On Microsoft Windows

Run the following in a Developer Command Prompt with access to cl and link from MSVC, to nmake, and to git.

git clone https://github.com/vvulpes0/ursatools.git
cd ursatools
nmake /f windows.mak
.\install.bat

This installs to %LocalAppData%\URSA but does not place this directory in your system path. You can temporarily add it within a given command session with the following command.

path %path%;%LocalAppData%\URSA

This does not persist. For persistence, you must edit the registry.

Example

To get a feel for the basics of the tools, save the following into a text file named sum256.s.

.text
.p2align 1
.global main
.function
main:   clr   r0, r0
        clr   r1, r1
        ior   r1, 256
.L0:    add   r0, r1
        subs  r1, 1
        bnz   .L0
.size main, . - main
        b     .

An assembly-language source file such as this contains human-readable names for actual CPU instructions. The job of the assembler is to transform this assembly-language source code into an object file, which represents the actual machine code. Run the following command to accomplish this.

aster -o sum256.o sum256.s

The result is a new file, sum256.o. This is a relocatable ELF object file. ELF is the file format. It is relocatable in that the function main has not been assigned a concrete location in memory yet. That is the job of the linker: it lays out a collection of one or more object files, finalizing their content and linking up any references between them. Run the following command to finalize the program.

starlink -mo sum256 sum256.o

This produces three new files: sum256.lcode with machine code, sum256.ldata with initialized data, and sum256.map. The last of these is a “symbol map” that details where various things are in the output.

Finally, you can run the following command to simulate the program in the software simulator and display any nonzero registers.

teddy -rq sum256

The output should be as follows.

loaded "sum256"
        r0     0x00008080         32896          32896
        pc     0x0000000c            12             12

This means that the sum, in register r0, is 32,896, and that the program stopped at location 12. By omitting the -rq options, you can enter a fully interactive “debugger” environment. See the manual for full details.