CSE 378 Homework #3: Building Cebollita Applications

This page is a supplement to homework 3.

The Build Process and make

"Building" an application means:
1. Compiling it, if it's a C-- program, to produce an assembly file (a .s file).
2. Assembling the assembly file, to produce an object file (a .o file).
3. Linking the .o you just produced with some "prologue" and possibly other .o files.

In homework 2 you used the command make to build your applications. make simply types the commands for the two or three steps above for you. (A full description of make is outside the scope of this course. Documenation can be found on the web if you're interested, though.) You can continue to do that, but it will help to understand what is going on.

What Is the Prologue For?

This description is particular to Cebollita. Real systems use prologues as well, though. They serve the purposes given here, plus a few more that don't apply to the simple case of Cebollita.

In a nutshell, the prologue is where execution actually begins. In Cebollita, all the prologue does is call your program using a jal instruction. How does it know the name of your program, which it needs to include in the jal instruction? By definition (of C--, and C, and C++, and Java) your program starts executing at main - you must supply a function named main to have a linkable C-- (or C/C++) program. The prologue simply does a jal main, and when you link the prologue with your program the right thing happens.

When your main finishes, it does a standard procedure return. That brings execution back to the prologue. At that point it issues whatever commands are required to terminate the "process" -- the running instance of the program.

In Cebollita, we have the prologue so that we don't have to rely on every programmer putting the correct instruction sequence at the end of their main routine to terminate the process. The linker expects there to be a prologue, so it sets the entry point of the .exe file, i.e., not main. This means the linker expects to find in one of the .o files supplied to it containing the definition of the symbol __start. So, if you don't include a prologue when you link, the linker will report an error.

It turns out there are multiple versions of the prologue. There have to be, because there are multiple ways to terminate the process. The "real way" is to invoke the operating system, asking it to terminate. The problem is that there isn't always an operating system around to ask. In particular, in this assignment there is no operating system. You build a processor, you load a bare executable into memory, you set the PC to 0, and you tell your machine to start exectuing. No operating system anywhere in sight.

On the other hand, the Cebollita simulator itself provides an operating system (sort of), and in the next assignment you'll expand your processor implementation, adding what is required to run an operating system. That next machine will then run a little OS we wrote.

So, the upshot is that there are three different prologues, for three different situations.

Simple Test Programs

Your first test programs will be just a couple of instructions. For example, you might have this:

.text
          .global  main
main:     add     $t3, $t2, $t1
          halt

You won't have jal implemented, so you won't be able to use a real prologue to link with this. However, __start is not defined, causing the linker to complain.

One way to solve this problem is to link with cebollita\apps\prologue-standalone.s:

# The null prologue, which leaves the user-written code at PC=0
# but satisifies the linker by having a __start: symbol
.text
         .global __start
__start: 

That satisfies the linker, but doesn't create any instructions at all.

Alternatively (and equivalently, in terms of the .exe that is produced), you can just create the symbol __start in your .s file and not link with any prologue:

.text
         .global  __start
__start:  add     $t3, $t2, $t1
          halt

More Complicated Programs in HW3

Suppose you write a test program in C--. You have a main function, because that's where execution starts. And, suppose you're pretty sure you have jal and all the other instructions working.

You can link your C-- program with prologue-noos.s (supplied in the files section at the end of the homework 3 writeup):

# The Cebollita ISA simulator's loader has set things up so that on entry:
# $gp = size of text segment
# $sp = text size + data size + heap size + stack size - 4
# $pc = entry point (presumably __start here!)
.text
         .global __start
__start: jal   main
         halt

Note that it uses the Halt instruction to stop, so doesn't need an OS.

Future Assignments, When We're Running an OS

The OS is called using the Syscall instruction. I'm giving the prologue for this situation here, but just for completeness. We won't discuss what Syscall does for a couple of weeks.

# The Cebollita ISA simulator's loader has set things up so that on entry:
# $gp = size of text segment
# $sp = text size + data size + heap size + stack size - 4
# $pc = entry point (presumably __start here!)
.text
         .global __start
__start: jal   main
         ori   $v0, $0, 10             # exit
         syscall

Back to make

In homework 2 you issued commands like make for-standalone and make for-os. Those commands caused some more commands to be executed that "remembered" which prologue to use in the future. Then when you did something like make fact, that remembered information (which was stored in a file) was looked up, and the correct prologue used in the link step. That's all that was going on.

What to Do Now

The purpose of this (long) page was to explain what was going on. That's better than a formula for what to do (like in homework 2) because, among other things, there are many different ways to achieve the build. You can, for instance, use make for the standalone case. (You could also modify make to know about prologue-noos.s, which it doesn't now, but that would require a relatively sophisticated understanding of make.) You can also (or instead) just issue the command required to build individually. For example,

$ cebasm myTestProg.s
$ ceblink -o myTestProg.exe prologue-standalone.o myTestProg.o

or when you're nearly done

$ cebcc myTestProg.c
$ cebasm myTestProg.s
$ ceblink -o myTestProg.exe prologue-noos.o myTestProg.o

Note: Because the initial SMOK model we're distributing halts the machine on a Syscall, you can use make for-os to build if you want, once you have jal working. You'll get that last prologue listed here linked with your program, but your machine should halt when it reaches the Syscall instruction. This is a complete hack, however.