Ant-8 3.1.

0b
Assembly Language Tutorial

May 16, 2002

ii

Copyright 1996-2002 by the President and Fellows of Harvard College.

Contents

Preface v

1 An Ant-8 Tutorial 1
1.1 What is Assembly Language? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Getting Started with Ant-8 Assembly: add.asm . . . . . . . . . . . . . . . . . . . . 1
1.2.1 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.2 Commenting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.3 Finding the Right Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.4 Completing the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.5 The Format of Ant-8 Assembly Programs . . . . . . . . . . . . . . . . . . . 4
1.2.6 Running Ant-8 Assembly Language Programs . . . . . . . . . . . . . . . . . 4
1.3 Reading and Printing: add2.asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Branches, Jumps, and Conditional Execution: larger.asm . . . . . . . . . . . . . . 7
1.4.1 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.2 Branching Using Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.5 Looping: loop.asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.6 Strings: hello.asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.7 Character I/O: echo.asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.8 Bit Operations: shout.asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.9 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2 The Ant-8 Instruction Set and Assembly Language 17

2.1 Ant-8 Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.1 Ant-8 Peripherals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3 The Ant-8 Assembler Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.2 The data Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.3 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.4 Symbolic Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.3.5 The .byte Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

iii
iv CONTENTS
Preface

This document is a brief tutorial for Ant-8 assembly language programming, and a description of
the Ant-8 architecture.
Ant-8 is a small and simple RISC architecture that was created as a teaching tool for students
in introductory computer programming and computer architecture courses. It is simple enough so
that the entire architecture can be learned and understood in a few hours by a novice programmer
and small enough so that the entire state of the machine can be displayed on a single 24-by-80
text screen. The Ant-8 architecture is also realistic enough, however, to give students a real
understanding of computer architecture and how their programs are executed.
The first chapter gives a tutorial for Ant-8 assembly language programming. After reading
this chapter, students should be able to write simple Ant-8 assembly language programs.
The second chapter gives an overview specification of the Ant-8 architecture. After reading this
chapter, students should be able to create their own implementation of the Ant-8 (as a software
simulation, or as hardware). More advanced students should also be able to write Ant-8 debugging
tools or even their own assembler for Ant-8 assembly language after reading this chapter.

v
vi PREFACE
Chapter 1

An Ant-8 Tutorial

This section is a tutorial for Ant-8 assembly language programming and the Ant-8 environment.
This chapter covers the basics of Ant-8 assembly language, including arithmetic operations, simple
I/O, conditionals, loops, and accessing memory.

1.1 What is Assembly Language?

Computer instructions are represented, in a computer, as sequences of bits. Generally, this is the
lowest possible level of representation for a program– each instruction is equivalent to a single,
indivisible action of the CPU. This representation is called machine language, and it is the only
form that can be “understood” directly by the computer.
A slightly higher-level representation (and one that is much easier for humans to use) is called
assembly language. Assembly language is very closely related to machine language, and there is
usually a straightforward way to translate programs written in assembly language into machine
language. (This translation is usually implemented by a program called an assembler.) Assem-
bly language is usually a direct translation of the machine language; one instruction in assembly
language corresponds to one instruction in the machine language.
Because of the close relationship between machine and assembly languages, each different ma-
chine architecture usually has its own assembly language (in fact, a particular architecture may
have several), and each is unique.

1.2 Getting Started with Ant-8 Assembly: add.asm

To get our feet wet, we’ll write an assembly language program named add.asm that computes the
sum of 1 and 2. Although this task is simple, in order to accomplish it we will need to explore
several key concepts in Ant-8 assembly language programming.

1
2 CHAPTER 1. AN ANT-8 TUTORIAL

1.2.1 Registers
Like many modern CPU architectures, the Ant-8 CPU can only operate directly on data that
is stored in special locations called registers. The Ant-8 architecture has 16 registers, named r0
through r15. Each of these registers can hold a single value. Two of these registers have special
purposes: register zero (r0) always contains the value zero, and register one (r1) is used to hold
useful values computed as part of the most recently executed instruction.
While most modern computers have many megabytes of memory, it is unusual for a computer
to have more than a few dozen registers. Since most computer programs use much more data than
can fit into these registers, it is usually necessary to juggle the data back and forth between memory
and the registers, where it can be operated upon by the CPU. (The first few programs that we
write will only use registers, but in section 1.6 the use of memory is introduced.)

1.2.2 Commenting
Before we start to write the executable statements of our program, however, we’ll need to write a
comment that describes what the program is supposed to do. In the Ant-8 assembly language, any
text between a pound sign (#) and the subsequent newline is considered to be a comment, and is
ignored by the assembler. Good comments are absolutely essential! Assembly language programs
are notoriously difficult to read unless they are well organized and properly documented.
Therefore, we start by writing the following:

# Dan Ellard -- 11/2/96

# add.asm-- A program that computes the sum of 1 and 2,
# leaving the result in register r2.
# Registers used:
# r2 - used to hold the result.

# end of add.asm

Even though this program doesn’t actually do anything yet, at least anyone reading our program
will know what this program is supposed to do, and who to blame if it doesn’t work1 .
Unlike programs written in higher level languages, it is usually appropriate to comment every
line of an assembly language program, often with seemingly redundant comments. Uncommented
code that seems obvious when you write it will be baffling a few hours later. While a well-written
but uncommented program in a high level language might be relatively easy to read and under-
stand, even the most well-written assembly code is unreadable without appropriate comments.
Some programmers prefer to add comments that paraphrase the steps performed by the assembly
instructions in a higher-level language.
We are not finished commenting this program, but we’ve done all that we can do until we know
a little more about how the program will actually work.
1
You should put your own name on your own programs, of course; Dan Ellard shouldn’t take all the blame.
1.2. GETTING STARTED WITH ANT-8 ASSEMBLY: ADD.ASM 3

1.2.3 Finding the Right Instructions

Next, we need to figure out what instructions the computer will need to execute in order to add
two numbers. Since the Ant-8 architecture has very few instructions, it won’t be long before you
have memorized all of the instructions that you’ll need, but as you are getting started you’ll need
to spend some time browsing through the list of instructions, looking for ones that you can use to
do what you want. A table of all of the instructions is given in figure 2.1, on page 19.
Luckily, as we look through the list of instructions, the very first instruction we come across is
the add instruction, which adds two numbers together.
The add instruction takes three operands, which must appear in the following order:

1. A register that will be used to hold the result of the addition. For our program, this will be
r2.
2. A register that contains the first number to be added. Therefore, we’re going to have to place
the value 1 into a register before we can use it as an operand of add. Checking the list of
registers used by this program (which is an essential part of the commenting) we select r3,
and make note of this in the comments.
3. A register that holds the second number to be added. We’re also going to have to place the
value 2 into a register before we can use it as an operand of add. Checking the list of registers
used by this program we select r4, and make note of this in the comments.

We now know how we can add the numbers, but we have to figure out how to place 1 and 2
into the appropriate registers. To do this, we can use the lc (load constant value) instruction,
which places an 8-bit constant into a register. Therefore, we arrive at the following sequence of
instructions:
# Dan Ellard -- 11/2/96
# add.asm-- A program that computes the sum of 1 and 2,
# leaving the result in register r2.
# Registers used:
# r2 - used to hold the result.
# r3 - used to hold the constant 1.
# r4 - used to hold the constant 2.

lc r3, 1 # r3 = 1
lc r4, 2 # r4 = 2
add r2, r3, r4 # r2 = r3 + r4.

# end of add.asm

1.2.4 Completing the Program

These three instructions perform the calculation that we want, but they do not really form a
complete program. We have told the processor what we want it to do, but we have not told it to
stop after it has done it!
4 CHAPTER 1. AN ANT-8 TUTORIAL

Ant-8 programs always begin executing at the first instruction in the program. There is no
rule for where the program ends, however, and if not told otherwise the Ant-8 processor will read
past the end of the program, interpreting whatever it finds as instructions and trying to execute
them. It might seem sensible (or obvious) that the processor should stop executing when it reaches
the “end” of the program (in this case, the add instruction on the last line), but there are some
situations where we might want the program to continue past the “end” of the program, or stop
before it reaches the end. Therefore, the Ant-8 architecture contains an instruction named hlt
that halts the processor.
The hlt instruction does not take any operands. (For more information about hlt, consult
Figure 2.1 on page 19.)

# Dan Ellard -- 11/2/96

# add.asm-- An Ant-8 program that computes the sum of 1 and 2,
# leaving the result in register r2.
# Registers used:
# r2 - used to hold the result.
# r3 - used to hold the constant 1.
# r4 - used to hold the constant 2.

lc r3, 1 # load 1 into r3.

lc r4, 2 # load 2 into r4.
add r2, r3, r4 # r2 = r3 + r4.

hlt # Halt - end execution.

# end of add.asm

1.2.5 The Format of Ant-8 Assembly Programs

As you read add.asm, you may notice several formatting conventions– every instruction is indented,
and each line contains at most one instruction. These conventions are not simply a matter of style,
but are actually part of the definition of the Ant-8 assembly language.
The first rule of Ant-8 assembly formatting is that instructions must be indented. Comments
do not need to be indented, but all of the code itself must be. The second rule of Ant-8 assembly
formatting is that only one instruction can appear on each line. (There are a few additional rules,
but these will not be important until section 1.4.1.)
Unlike many programming languages, where the use of whitespace and formatting is largely a
matter of style, in Ant-8 assembly language some use of whitespace is required.

1.2.6 Running Ant-8 Assembly Language Programs

At this point, we should have a working program. Now, it’s time to run it and see what happens.
There are two principal ways of running an Ant-8 program– using the commandline tools (aa8,
ad8 and ant8), or using AIDE8 (the Ant-8 Integrated Development Environment).
1.2. GETTING STARTED WITH ANT-8 ASSEMBLY: ADD.ASM 5

Using the Commandline Tools

Before the commandline tools can run on a program, the program must be written in a file. This
file must be plain text, and by convention Ant-8 assembly language files have a suffix of .asm.
In this example, we will assume that the file add.asm contains a copy of the add program listed
earlier.
Before we can run the program, we must assemble it. The assembler translates the program
from the assembly language representation to the machine language representation. The assembler
for Ant-8 is called aa8, so the appropriate command would be:

aa8 add.asm

This will create a file named add.ant that contains the Ant-8 machine-language representation
of the program in add.asm.
Now that we have the assembled version of the program, we can test it by loading it into the
Ant-8 debugger in order to execute it. The name of the Ant-8 debugger is ad8, so to run the
debugger, use the ad8 command followed by the name of the machine language file to load. For
example, to run the program that we just wrote and assembled:

ad8 add.ant

After starting, the debugger will display the following prompt: >>. Whenever you see the >>
prompt, you know that the debugger is waiting for you to specify a command for it to execute.
Once the program is loaded, you can use the r (for run) command to run it:

>> r

The program runs, and then the debugger indicates that it is ready to execute another command.
Since our program is supposed to leave its result in register r2, we can verify that the program is
working by asking the debugger to print out the contents of the registers using the p (for print)
command, to see if it contains the result we expect:

>> p
r01 r02 r03 r04 r05 r06 r07 r08 r09 r10 r11 r12 r13 r14 r15
00 03 01 02 00 00 00 00 00 00 00 00 00 00 00
0 3 1 2 0 0 0 0 0 0 0 0 0 0 0

The p command displays the contents of each register. The first line lists the register names.
The following line lists the value of each register in hexadecimal, and the last line lists the same
number in decimal.
The q command exits the debugger.
ad8 includes a number of features that will make debugging your Ant-8 assembly language
programs much easier. Type h (for help) at the >> prompt for a full list of the ad8 commands, or
consult the ad8 documentation for more information.
6 CHAPTER 1. AN ANT-8 TUTORIAL

Using AIDE8
AIDE8 provides a more tightly integrated way of creating, debugging, and running Ant-8 pro-
grams. Although it is less flexible than running each of the tools individually, for most users it is
more than sufficient.
When AIDE8 starts, only the editor window is shown. This window can be used to create or edit
an Ant-8 program. After the program is written, it can be assembled by pressing the Assemble
button. If the assembly process is successful, no error messages will be displayed; otherwise, the
cause of the error is printed at the bottom of the screen and the offending line of the program is
highlighted.
Once the program has been written and assembled, pressing the Debug button brings up the
debugger window. The debugger window displays the complete state of the Ant-8 machine. (The
debug window can be displayed at any time, even if there isn’t a program loaded into the Ant-8
machine, but without a program to display there isn’t much to see.)
To simply run the program, click on the Run button in the upper-left corner of the debugger
window. The execution of the program, instruction by instruction, will be displayed in the debugger
window as the state of the processor is updated.
The AIDE8 contains many other features. Consult the Help menu of AIDE8 for more infor-
mation.

1.3 Reading and Printing: add2.asm

Our program to compute 1 + 2 is not particularly useful, although it does demonstrate a number of
important details about programming in Ant-8 assembly language and the Ant-8 environment.
For our next example, we’ll write a program named add2.asm that computes the sum of two
numbers specified by the user at runtime, and displays the result on the screen.
The algorithm this program will use is:

1. Read the two numbers from the user.

We’ll need two registers to hold these two numbers. We will use r3 and r4 for this.

2. Compute their sum.

We’ll need a register to hold the result of this addition. We can use r2 for this.

3. Print the sum, followed by a newline.

4. Halt.
We already know how to do this, using hlt.

The only parts of the algorithm that we don’t know how to do yet are to read the numbers
from the user, and print out the sum.
Ant-8 does its I/O (or “input/output”) using the in instruction to read values from the user
into the computer, and the out instruction to display values to the user.
1.4. BRANCHES, JUMPS, AND CONDITIONAL EXECUTION: LARGER.ASM 7

The in instruction allows the user to specify values in one of three different formats: hexadec-
imal, binary, or ASCII. Similarly, the out instruction can display a value in hexadecimal, binary,
or ASCII. Note that there is no way to directly input or output a decimal value!
This gives the following program:

# Dan Ellard -- 11/2/96

# add2.asm-- An Ant-8 program that computes and prints the sum
# of two numbers specified at runtime by the user,
# followed by a newline
# Registers used:
# r2 - used to hold the result.
# r3 - used to hold the first number.
# r4 - used to hold the second number.
# r5 - used to hold the constant ’\n’.

in r3, Hex # read first number into r3 (as hex).

in r4, Hex # read second number into r4 (as hex).
add r2, r3, r4 # compute the sum r2 = r3 + r4.
out r2, Hex # print contents of r2 (as hex).

lc r5, ’\n’ # load a newline character into r5

out r5, ASCII # print contents of r5, as ASCII

hlt # Halt

# end of add2.asm.

1.4 Branches, Jumps, and Conditional Execution: larger.asm

The next program that we will write will read two numbers from the user, and print out the larger
of the two. The basic structure of this program is similar to the one used by add2.asm, except that
we’re computing the maximum rather than the sum of two numbers. The difference is that the
behavior of this program depends upon the input, which is unknown when the program is written.
The program must be able to decide whether to execute instructions to print out the first number
or execute the instructions to print out the second number at runtime. This is known as conditional
execution– whether or not certain parts of program are executed depends on a condition that is
not known when the program is written.
Browsing through the instruction set again, we find a description of the Ant-8 branching in-
structions. These allow the programmer to specify that execution should branch (or jump) to a
location other than the next instruction. These instructions allow conditional execution to be im-
plemented in assembly language (although in not nearly as clean a manner as higher-level languages
provide).
In Ant-8 assembler, there are three branching instructions: bgt, beq and jmp. bgt and beq are
called conditional branches, because they cause the program to branch when a specific condition
holds. In contrast, the jmp instruction is an unconditional branch, which is always taken.
8 CHAPTER 1. AN ANT-8 TUTORIAL

The bgt instruction takes three registers as arguments. If the number in the second register is
larger than the number in the third, then execution will jump to the location specified by the first;
otherwise it continues at the next instruction.
The beq instruction is similar in form to the bgt instruction, except that the branch occurs if
the second and third registers contain the same value.
The jmp instruction takes a single argument, which is an unsigned 8-bit constant. Execution
jumps to the location specified by the constant.

1.4.1 Labels
Keeping track of the numeric addresses in memory of the instructions to which we want to branch
is troublesome and tedious at best– a small error can make our program misbehave in strange
ways, and if we change the program at all by inserting or removing instructions, we will have
have to carefully recompute all of these addresses and then change all of the instructions that use
these addresses. This is much more than most humans can possibly keep track of. Luckily, the
computer is very good at keeping track of details like this, so the Ant-8 assembler provides labels,
a human-readable shorthand for addresses.
A label is a symbolic name for an address in memory. In Ant-8 assembler, a label definition is
an identifier followed by a colon. Ant-8 identifiers use the same conventions as Python, Java, C,
C++, and many other contemporary languages:

• Ant-8 identifiers must begin with an underscore, an uppercase character (A-Z) or a lowercase
character (a-z).

• Following the first character there may be zero or more underscores, or uppercase, lowercase,
or numeric (0-9) characters. No other characters can appear in an identifier.

• Although there is no intrinsic limit on the length of Ant-8 identifiers, some Ant-8 tools may
reject identifiers longer than 100 characters.

Labels must be the first item on a line, and must begin in the “zero column” (immediately after
the left margin). Label definitions cannot be indented, but all other non-comment lines must be.
Since labels must begin in column zero, only one label definition is permitted on each line of
assembly language, but a location in memory may have more than one label. Giving the same
location in memory more than one label can be very useful. For example, the same location in your
program may represent the end of several nested “if” statements, so you may find it useful to give
this instruction several labels corresponding to each of the nested “if” statements.
When a label appears alone on a line, it refers to the following memory location. This is often
good style, since it allows the use of long, descriptive labels without disrupting the indentation of
the program. It also leaves plenty of space on the line for the programmer to write a comment
describing what the label is used for, which is very important since even relatively short assembly
language programs may have a large number of labels.
1.5. LOOPING: LOOP.ASM 9

1.4.2 Branching Using Labels

Using the branching instructions and labels we can do what we want in the larger.asm program.
Since the branching instructions take a register containing an address as their first argument, we
need to somehow load the address represented by the label into a register. We do this by using the
lc (load constant) command. The larger.asm program illustrates how this is done.

# Dan Ellard -- 11/2/96

# larger.asm-- An Ant-8 program that computes and prints the larger
# of two numbers specified at runtime by the user.
# The algorithm used here is to put the larger of r2 and r3
# into r4, and then print r4.
# Registers used:
# r2 - used to hold the first number.
# r3 - used to hold the second number.
# r4 - used to hold the larger of r2 and r3.
# r5 - used to hold the address of the label "r2_larger"
# r6 - used to hold the a "newline" character

in r2, Hex # read a hexadecimal number into r2

in r3, Hex # read a hexadecimal number into r3

lc r5, $r2_larger # put the address of r2_larger into r5

bgt r5, r2, r3 # if r2 is larger, branch to r2_larger

add r4, r3, r0 # "copy" r3 into r4
jmp $endif # and then branch to endif
r2_larger:
add r4, r2, r0 # "copy" r2 into r4
endif:
out r4, Hex # print contents of r4 (in hex).
lc r6, ’\n’ # load a newline character into r6
out r6, ASCII # print contents of r6 (in ASCII).
hlt # Halt

# end of larger.asm.

Note that since Ant-8 does not have an instruction to copy or move the contents of one register
to another, in order to copy the value of one register to another register we’ve added 0 to one
register and put the sum in the destination register in order to achieve the desired result. (Recall
that register r0 always contains the constant zero.)

1.5 Looping: loop.asm

In the previous example program, we used the jump and branch instructions to implement condi-
tional execution, which meant that we could skip over some instructions depending on the values
10 CHAPTER 1. AN ANT-8 TUTORIAL

that the user typed. We can also use these instructions to implement loops, which allow the program
to repeatedly execute a sequence of instructions an arbitrary number of times.
The next program that we will write will read a character A (as ASCII) and then a number
B (as hexadecimal) from the user, and then print B copies of the character A. This algorithm
translates easily into Ant-8 assembler; the only thing that is new is that the execution might jump
“backwards” in the program to repeat some instructions more than once. The loop.asm programs
shows how this is done.

# Dan Ellard -- 01/20/2000

# loop.asm -- An Ant-8 program that illustrates looping by
# printing a given character a given number of times.
# Registers used:
# r2 - used to hold the character to print.
# r3 - used to hold the number of times to print the character.
# r4 - used to hold the address of the end of the loop.

lc r4, $endloop # r4 is the address of the end of the loop.

in r2, ASCII # Get the character to print
in r3, Hex # Get the number of times to print it
loop:
beq r4, r0, r3 # if r3 is zero, branch to $endloop.
bgt r4, r0, r3 # if r3 < zero, branch to $endloop.
out r2, ASCII # print the character.
inc r3, -1 # decrement r3.
jmp $loop # jump to $loop, to repeat the process.

endloop:
hlt # Halt

# end of loop.asm

1.6 Strings: hello.asm

The next program that we will write is the “Hello World” program, a program that simply prints
the message “Hello World” to the screen and then halts.
There is no way in Ant-8 to print out more than one character at a time, so we must use a
loop to print out each character of the string, starting at the beginning and continuing until we
reach the end of the string.
The string “Hello World” is not part of the instructions of the program, but it is part of the
memory used by the program. The assembler places all data values (not instructions) after all of
the instructions in memory.
The value of the data memory is loaded into memory at assembly time. You will have to be
careful to not accidently overwrite your data during run-time!
The way that the initial contents of data memory are defined is via the .byte directive. .byte
looks like an instruction which takes as many as eight 8-bit constants, but it is not an instruction
1.6. STRINGS: HELLO.ASM 11

at all. Instead, it is a directive to the assembler to fill in the next available locations in memory
with the given values.
All of the .byte items in an Ant-8 program must appear at the end of the program, after
the special label data . The data label indicates to the assembler that all subsequent items are
data. No instructions are permitted after the data label.
In our programs, we will use the following convention for ASCII strings: a string is a sequence
of characters terminated by a 0 byte. For example, the string “hi” would be represented by the
three characters ‘h’, ‘i’, and 0. Using a 0 byte to mark the end of the string is a convenient method,
used by several contemporary languages.
The program hello.asm is an example of how to use labels and treat characters in memory as
strings:

# Dan Ellard -- 01/19/2000

# hello.asm-- An Ant-8 "Hello World" program.
# Registers used:
# r2 - holds the address of the string
# r3 - holds the address of the end of the loop
# r4 - holds the next character to be printed.

lc r2, $str_data # load the address of the string into r2

lc r3, $endloop # load address of the end of loop.

loop:
ld1 r4, r2, 0 # Get the first character from the string
beq r3, r4, r0 # If the char is zero, we’re finished.
out r4, ASCII # Otherwise, print the character.
inc r2, 1 # Increment r2 to point to the next char
jmp $loop # and repeat the process...

endloop:
hlt

_data_: # Data for the program begins here:

str_data:
.byte ’H’, ’e’, ’l’, ’l’, ’o’, ’ ’
.byte ’W’, ’o’, ’r’, ’l’, ’d’, ’\n’, 0

# end of hello.asm

The label str data is the symbolic representation of the memory location where the string
begins in data memory.
12 CHAPTER 1. AN ANT-8 TUTORIAL

1.7 Character I/O: echo.asm

Now that we have mastered loops and reading and printing integers, we’ll turn our attention to
reading and printing single characters. (We’ve already seen how to read and write numbers, and
the process is similar, except that we use the ASCII device instead of Hex.)
The program we’ll write in this section simply echos whatever you type to it, until EOI (end of
input) is reached.
The way that EOI is detected in Ant-8 is that when the EOI is reached, any attempt to use
in to read more input will immediately fail, and a non-zero value will be placed in register r1 to
indicate that there was an error. If the in succeeds, then r1 is set to zero.
Therefore, our program will loop, continually using in to read characters, and checking r1 after
each in to see whether or not the EOI has been reached.

# Dan Ellard - 11/10/96

# echo.asm - An Ant-8 program that echos input until EOI is reached.
# Register usage:
# r2 - holds each character read in.
# r3 - address of $print.

lc r3, $print
loop:
in r2, ASCII # r2 = getchar ();
beq r3, r1, r0 # if not at EOF, go to $print.
jmp $exit # otherwise, go to $exit.
print:
out r2, ASCII # putchar (r2);
jmp $loop # iterate, go back to $loop.
exit:
hlt # Exit

# end of echo.asm

Note: because of the difference between the user interface of the debugger in AIDE8 and
the ordinary runtime Ant-8 environment, echo.asm behaves differently when run under AIDE8
than when run via ant8 or ad8. This is because in AIDE8, every input, including ASCII input,
must be followed by a newline, while in ordinary operation ASCII input does not. This should be
considered a shortcoming of AIDE8, not a problem with echo.asm.

1.8 Bit Operations: shout.asm

The next program we shall write is very similar to echo.asm, except that instead of simply echoing
its input, it converts all of the lowercase characters in the input to uppercase in the output.
There are several ways that this could be accomplished. The easiest way, and one that does
not require learning about any new Ant-8 instructions, would be to note that all of the lowercase
characters in ASCII are arranged consecutively, starting with ’a’ (with a value of 0x61) and
1.8. BIT OPERATIONS: SHOUT.ASM 13

continuing through ’z’ (with a value of 0x7A). The uppercase characters are arranged in the same
manner, ranging from ’A’ = 0x41 to ’Z’ = 0x5A. Therefore, in order to convert from uppercase
to lowercase all we need to do is take any characters that have ASCII codes in the range 0x61 to
0x7A and subtract 0x20 from them before printing them.
However, our goal in this section is to learn about Ant-8’s bitwise instructions, and so we use a
different observation– the ASCII code for the lowercase characters and the corresponding uppercase
characters differ only in a single bit. All the lowercase characters have the bit corresponding to
0x20 set to 1, while all the uppercase characters do not. Therefore, if we have a lowercase character,
in order to convert it to uppercase all we need to do is set this bit to 0. The bit we are interested
in is the fifth bit (counting from the right and starting at zero).
To change the fifth bit from 1 to 0, we can use the and instruction. If the 8-bit value is in
register r2, then computing the bitwise And of the value of r2 and the 8-bit value value consisting
of all 1 bits except the fifth bit, the result will be identical to the original value of r2 except that
the fifth bit will be 0.
We could explicitly compute the value of the 8-bit value that has all 1-bits except for the fifth
bit, or we can let the computer do this work for us. We choose the latter approach, because this
also means that we can introduce two more instructions, shf and nor.
Our first task is to initialize r8 with the 8-bit value consisting of all zero bits, except for the
fifth bit. (We know this value is 0x20, and so we could simply use this value, but we’ll use shf
instead:

lc r8, 1 # r8 has all 0 bits, except

# bit zero which is 1.
lc r9, 5
shf r8, r8, r9 # shift the 1 bit over 5 spaces.
# r8 is now 0x20.

nor r8, r8, r8 # NOR r8 with itself, which changes

# all the 1 bits to 0 and vice versa.
# r8 is now 0xDF.

The complete program is implemented in shout.asm.

# Dan Ellard - 05/10/2000

# An Ant-8 program that echos input until EOI is reached,
# converting from lowercase to uppercase.
# Register usage:
# r2 - holds each character read in
# r3 - address of $process
# r4 - address of $print
# r5 - address of $uppercase
# r6 - ’a’, the smallest lowercase ASCII value (0x61)
# r7 - ’z’, the largest lowercase ASCII value (0x7A)
# r8 - the mask to convert from lowercase to uppercase
14 CHAPTER 1. AN ANT-8 TUTORIAL

lc r3, $process
lc r4, $print
lc r5, $uppercase
lc r6, ’a’
lc r7, ’z’

lc r8, 1 # set r8 to 1.
lc r9, 5
shf r8, r8, r9 # slide over the 1 by 5 positions
nor r8, r8, r8 # and then use nor to flip all the bits

loop:
in r2, ASCII # r2 = getchar ();
beq r3, r1, r0 # if not at EOF, go to $process.
jmp $exit # otherwise, go to $exit.
process:
bgt r4, r2, r7 # if the char is > ’z’, just print it
beq r5, r2, r6 # else if the char is ’a’, uppercase it
bgt r5, r2, r6 # else if the char is > ’a’, uppercase it
jmp $print # else the char is < ’a’, so just print it
uppercase:
and r2, r2, r8 # zero the fifth bit of r2
print:
out r2, ASCII # putchar (r2);
jmp $loop # iterate, go back to $loop.
exit:
hlt # Exit

# end of shout.asm

1.9 Exercises
1. The add2.asm program can produce confusing output– if the sum of the two numbers is
greater than 127 or less than -128, the incorrect sum will be printed.

(a) Starting with a copy of add2.asm, write a program named add3.asm that prints a warn-
ing message if this occurs.
(b) Extend add3.asm so that it always prints the correct sum, even if the sum is larger than
127 or less than -128.
Hint– the sum will be no larger than 254 and no smaller than -256, and there are only
three main situations to worry about– the correct sum is between -128 and 127 (in which
case nothing special is necessary), between 128 and 254, or between -129 and -256.

2. Write an Ant-8 program named box.asm that asks the user for a height and a width, makes
1.9. EXERCISES 15

sure that both are larger than zero but less than twenty, and then draws a solid box of
asterisks with the given height and width.

3. Write an Ant-8 program named box2.asm that asks the user for a height and a width,
makes sure that both are larger than zero but less than twenty, and then draws a hollow box
of asterisks with the given height and width.

4. Write an Ant-8 program named decimal1.asm that takes as input a single hexadecimal
number in the range 00 - 7F and prints it in decimal notation.
Note that the range of 00 through 7F in hex is equal to the range from 0 to 127 in decimal–
you only need to deal with positive numbers.

5. Write an Ant-8 program named decimal2.asm that takes as input a single hexadecimal
number in the range 80 - 7F and prints it in decimal notation. Recall that 80 in hex is -128
in decimal, and FF in hex is -1 in decimal.

6. Write an Ant-8 program named sort.asm that reads 20 numbers from the user, sorts them,
and then prints them in ascending order.
16 CHAPTER 1. AN ANT-8 TUTORIAL
Chapter 2

The Ant-8 Instruction Set and

Assembly Language

This chapter gives a more detailed description of the Ant-8 3.1.0b instruction set and some
additional details about the Ant-8 assembler that are not covered by the tutorial chapter. The
exact definition of the Ant-8 instruction set and a precise specification for how Ant-8 programs
are executed are given in the Ant-8 3.1.0b Architecture Reference.

2.1 Ant-8 Architecture Overview

The Ant-8 architecture is a load/store architecture; the only instructions that can access memory
are the load and store instructions. All other operations access only registers (or, in the case of in
and out, access peripherals).
The Ant-8 CPU has 16 registers, named r0 through r15. Register r0 always contains the
constant 0, and register r1 is used to hold results related to previous operations (described later).
r0 and r1 are read-only. They can be used as destination registers, but their values are unchanged.
The other 14 registers (r2 through r15) are general-purpose registers.

2.2 Instructions
In the description of the instructions, the notation described in the following table is used:

des Must always be a register. The des register may be modified by the instruction.
reg Must always be a register.
src1 Must always be a register.
src2 Must always be a register.
const8 Must be an 8-bit constant (-128 .. 127): an integer (signed), char, or label.
uconst8 Must be an 8-bit constant (0 .. 255): an integer (unsigned) or label.
uconst4 Must be a 4-bit constant integer (0 .. 15).

17
18 CHAPTER 2. THE ANT-8 INSTRUCTION SET AND ASSEMBLY LANGUAGE

The Ant-8 assembly language instructions are listed in Figure 2.1.

Note that for all instructions, register r1 is always updated after the rest of the instruction is
done, so that it is always safe to use r1 as a source register.

2.2.1 Ant-8 Peripherals

The in and out operations set r1 to 0 if successful, and set r1 to non-zero values to indicate failure.

Operation Format Mnemonic Description

in 0 Hex Read two characters and interpret them as an 8-bit hex-
adecimal number. Each character must be a valid hex-
adecimal number.
1 Binary Read eight characters and interpret them as an 8-bit bi-
nary number. Each character must be ’0’ or ’1’.
2 ASCII Read a single character, as ASCII.
out 0 Hex Write an 8-bit number as two characters, using hexadec-
imal notation.
1 Binary Write an 8-bit number as 8 characters, using binary no-
tation.
2 ASCII Write the 8-bit number, as ASCII.
Note that the behavior of the in operation is undefined if the input is not properly formatted,
or contains illegal characters. For hexadecimal input, only the characters 0-9 and A-F (or a-f)
may be used. For binary input, only the 1 and 0 characters are permitted. There is no restriction
on ASCII characters.

2.3 The Ant-8 Assembler Reference

2.3.1 Comments
A comment begins with a # and continues until the following end-of-line. The only exception to
this is when the # character appears as part of an ASCII character constant (as described in section
2.3.3).

2.3.2 The data Label

A special label, data , is used to mark the boundary between the instructions of the program
(which must appear before the data label) and the data of the program (which appear afterward).

2.3.3 Constants
Several Ant-8 assembly instructions contain 8-bit or 4-bit constants.
2.3. THE ANT-8 ASSEMBLER REFERENCE 19

Figure 2.1: Ant-8 Instruction Mnemonics

Op Operands Description
add des, src1, src2 des gets src1 + src2. r1 gets 1 if the result is > 127, -1 if < -128, or
0 otherwise.
sub des, src1, src2 des gets src1 - src2. r1 gets 1 if the result is > 127, -1 if < -128, or
0 otherwise.
mul des, src1, src2 Multiply src1 and src2, leaving the low-order byte in register des and
the high-order byte in register r1.
and des, src1, src2 des gets the bitwise logical and of src1 and src2. r1 gets the bitwise
negation of the and of src1 and src2.
nor des, src1, src2 des gets the bitwise logical nor of src1 and src2. r1 gets the bitwise
negation of the nor of src1 and src2.
shf des, src1, src2 des gets the bitwise shift of src1 by src2 positions. If src2 is positive,
src1 is shifted to the left, if src2 is negative src1 is shifted to the
right.
beq reg, src1, src2 Branch to reg if src1 is equal to src2. r1 is unchanged.
bgt reg, src1, src2 Branch to reg if src1 > src2. r1 is unchanged.
ld1 des, src1, uconst4 Load the byte at src1 + uconst4 into des. r1 is unchanged.
st1 reg, src1, uconst4 Store the contents of register reg to src1 + uconst4. r1 is unchanged.
lc des, const8 Load the constant const8 into des. r1 is unchanged.
jmp uconst8 Branch unconditionally to the specified constant. r1 is set to the
address of the instruction following the jmp.
inc reg, const8 Add const8 to the specified register. r1 gets 1 if the result is > 127,
-1 if < -128, or 0 otherwise.
in des, const4 Read in a byte from the peripheral specified by const4, and place it
in the destination register. r1 is set to 0 if successful, 1 if EOI is
reached.
out src1, const4 Write the byte in the src1 register to the peripheral specified by
const4. r1 is set to 0.
hlt const8 Dump core, set the PC to the value const8, and halt the processor.
The PC is set to the value const8, so that if the processor is restarted
it will continue from that location.
20 CHAPTER 2. THE ANT-8 INSTRUCTION SET AND ASSEMBLY LANGUAGE

The 8-bit constants can be specified in a variety of ways: as decimal, octal, hexadecimal, or
binary numbers, ASCII codes (using the same conventions as C), or labels. Examples are shown
in the following table:

Representation Value Decimal Value

Decimal (base 10) 65 65
Hexadecimal (base 16) 0x41 65
Octal (base 8) 0101 65
Binary (base 2) 0b01000001 65
ASCII ’A’ 65
Decimal (base 10) 10 10
Hexadecimal (base 16) 0xa 10
Octal (base 8) 012 10
Binary (base 2) 0b1010 10
ASCII ’\n’ 10

The value of a label is the index of the subsequent instruction in instruction memory for labels
that appear in the code, or the index of the subsequent .byte item for labels that appear in the
data.
The 4-bit constants must be specified as unsigned numbers (using decimal, octal, hexadecimal,
or binary notation). ASCII constants or labels cannot be used as 4-bit constants, even if their value
can be represented in 4 bits.

2.3.4 Symbolic Constants

Constants can be given symbolic names via the .define directive. This can result in substantially
more readable code. The first operand of the .define directive is the symbolic name for the
constant, and the second value is an integer constant. The integer constant must not be a label or
another symbolic constant, however.

.define ROWS, 10 # Defining ROWS to be 10

.define COLS, 10 # Defining COLS to be 10

lc r2, ROWS # Using ROWS as a constant

inc r3, COLS # Using COLS as a constant

2.3.5 The .byte Directive

The .byte directive is used to specify data values to be assembled into the next available locations
in memory.
2.3. THE ANT-8 ASSEMBLER REFERENCE 21

Name Parameters Description

.byte byte1, · · ·, byteN Assemble the given bytes (8-bit integers) into the next avail-
able locations in the data segment. As many as 8 bytes can
be specified on the same line. Bytes may be specified as hex-
adecimal, octal, binary, decimal or character constants (as
described in 2.3.3).
No more than 8 bytes can be defined with the same .byte
statement.
22 CHAPTER 2. THE ANT-8 INSTRUCTION SET AND ASSEMBLY LANGUAGE
Index

add.asm, 1
add.asm (complete listing), 4
add2.asm, 6
add2.asm (complete listing), 7
assembly, 1

branch with labels , 9

branching, 7

character I/O, 12
commenting, 2

echo.asm, 12

hello.asm, 10
hello.asm (complete listing), 11

labels, 8
larger.asm, 7
loop.asm, 9
looping, 9

23