Program to link LC-3 asm files
This project is an assembler and linker for Little Computer 3 (LC-3)
The experience of using LC-3 subroutines can be improved by having each subroutine in its own compilable unit, making it possible for different programs to re-use the same subroutines. This approach requires a linker that assembles the code of each compilable unit and puts all the machine code into a single binary.
lc3linker is a simple linker that takes as parameters:
- the main asm file
- asm files corresponding to the subroutines needed by the main program
- name of the resulting object file
It also generates a symbol table with the same name as the object file but suffix .sym
Note: if only 1 asm file is passed as argument, there is no need to specify the object file (one with the same name as the asm file will be created by default)
lc3linker cannot be used to:
- link previously existing object files
- generate individual object files for each asm file provided as argument
As the code of the subroutines needs to be relocated, subroutine files cannot have .ORIG directives.
The main program, the one with .ORIG, must come first in the list of arguments
The code of the subroutines is relocated after the main program in the order in which they are provided in the list of arguments.
In case of long programs or having many subroutines, some PC-relative or base register-relative offsets can overflow. In such a case, manually rearranging the order of the subroutines in the list of arguments may fix the problem.
The folder src/test/resources contains a few asm programs and subroutines that can be used to practise.
Note: some of the examples have been borrowed from public sources to help improve the unit tests
The program day_of_week.asm calculates the day of the week of a given date by using Zeller's formula and depends on the following subroutines:
- multiplication_routine.asm
- division_routine.asm
- read_multi_digit_routine.asm
- ascii_to_binary_routine.asm
To assemble day_of_week.asm, we need to link it with all its subroutines and specify the object file containing the final version of the code.
The linker can be run in a docker image available in Docker Hub
To make the asm files available to the container, the local folder containing the asm files must be mounted on
the container's /data folder.
Assuming the docker command is run from the folder containing the asm files:
docker run --rm -v $(pwd):/data --name lc3linker fjab76/lc3linker:1.0.0 /data/day_of_week.asm /data/multiplication_routine.asm /data/division_routine.asm /data/read_multi_digit_routine.asm /data/ascii_to_binary_routine.asm /data/day_of_week.obj
For convenience, the script lc3linker.sh simplifies the call to the docker command:
lc3linker.sh day_of_week.asm multiplication_routine.asm division_routine.asm read_multi_digit_routine.asm ascii_to_binary_routine.asm day_of_week.obj
sbt run src/test/resources/day_of_week.asm src/test/resources/multiplication_routine.asm src/test/resources/division_routine.asm src/test/resources/read_multi_digit_routine.asm src/test/resources/ascii_to_binary_routine.asm src/test/resources/day_of_week.obj
The assembled/linked programs can be run in any of the multiple LC-3 emulators that can be found online:
- lc3tools contains several LC-3-related utilities, among them the emulator
lc3simthat also includes a debugger - this other emulator with a GUI is written in Java and supports video output
- and here's another LC-3 virtual machine written in C
The first two emulators require an OS to handle TRAP calls and
restrict access to different memory regions, whereas the last VM has that functionality built-in.
The assembler is implemented as specified by Introduction to Computing Systems: From bits and gates to C and beyond
In addition to the instructions described in the specification, the assembler implemented in this project also supports JMPT and RTT.
These instructions are a variant of JMP and RET, respectively, that have the additional effect of setting to zero the privilege bit in PS (Process Status Register).
Note: lc3sim does not support those instructions though.