C Programming on LC3

 Ramesh Yerraballi

This document will explain how to get started with C programming on the LC3. I assume that you have learn't to use the LC3Edit and  LC3Simulate programs to edit and run your LC3 assembly programs. You are now ready to take the next step in programming that is, to program in a higher-level programming language like C. This document will not teach you to program in C but simply help you get the proper environment setup on your PC (or Mac/Linux) machine to Edit, Compile and Debug your C programs. I will first cover the environment setup for a PC running Windows and towards the end of the document give you details of how this can be done on your Mac.

Software Needed

There are two main pieces of software you will need to install in addition to the LC3tools software, which you must already have. Recall that LC3tools was the software that when installed gave you LC3Edit and LC3Simulate. You can get it from here:
http://highered.mcgraw-hill.com/sites/0072467509/student_view0/lc-3_simulator.html 

LC3 C Compiler

While this software allows you to write, assemble and run/debug your LC3 assembly programs, it does not work with C programs. The LC3 software you need to do this is called the LC3 C Compiler. This software can be also downloaded from the publishers site at:
http://highered.mcgraw-hill.com/sites/0072467509/student_view0/c_to_lc-3_compiler.html
I will assume that you have this installed  on your C drive in a directory called c:\lc3

When you download and unzip this software it will be put in a directory called lcc-1.3. I recommend putting this on your C drive under the lc3 directory you already have your LC3tools: c:\lc3\lcc-1.3. There are several files under this directory which form the source code for the LC3 C Compiler software. Unlike the LC3Edit and LC3Simulate programs which were given to you as executables, the C Compiler is only available in source form. This means, you have to build the executables yourself by using the appropriate software.

Cygwin

This brings us to the second piece of software you need. On a PC running Windows the software that allows you to build the LC3 compiler is called Cygwin . The Cygwin software does a lot more than allow you to build the LC3 compiler it allows you to build just about any Unix software available in source form, to be able to run on Windows. Cygwin is freely available form the Cygwin website (www.cygwin.org). Download and run the file setup.exe from this link: http://cygwin.com/install.html

This is where the faint-hearted could give up but you are an aspiring engineer and I expect you to be not deterred so easily. The interface presented when the setup.exe file is run (by double-clicking of course) is rather unintuitive and prompts you to make choices that you may not be sure about. So here is the gist:
Pick the defaults on every screen prompted till you get to the screen that asks you to "Choose A Download Site". It does not matter which you pick other than affect the speed at which you download. I choose http://mirror.mcs.anl.gov because I've always found this site to be reliable and to have a decent speed.

The next screen will present a long list of packages and ask you to select the ones you want to install. In addition to the default packages, make sure you select these packages:
That is it. Click the next button at the bottom of the screen and give it a few minutes to complete the download and installation. This should take approximately 15-20 minutes depending on the speed of your Internet connection and your processor.


Building lcc in Cygwin

The Cygwin software you installed has one application called a shell that allows you to do all of the work needed including programming. First though, we will use it to build the LC3 C compiler. To do this, double click the "Cygwin Terminal" icon that was placed on your Desktop when Cygwin installation was complete. This will open a window that looks like this

Install the lc3 assembler
While the previous step installed the compiler software, it depends on one other utility which was part of lc3tools, i.e., the assembler. I am providing this at the following link: http://users.ece.utexas.edu/~ryerraballi/ee306/lc3as.exe

Right-click on the above link and choose save-link-as (Firefox) to save it in the following directory on your PC: C:\cygwin\bin


CONGRATULATIONS!!

That is it, you are now ready to write your C Programs, compile them and generate assembly and object files that can be run in the LC3 Simulator.

C Programming

It is not the intent of this document to teach you to program in C for that I refer you to the textbook, Introduction to Computing by Yale Patt and Sanjay Patel [1]. The second part of this text (chapter 11 onwards) covers C programming with LC3 computer as the reference. That is assuming you understand the LC3 assembly language and know basic programming principles, you can read this material to see how programming at a higher level works.

I will however show you how to write your C programs and go through the process of running them on the simulator, using the tools you installed.

Again, open the Cygwin Terminal if you did not already do so. You may want to create a directory for your C programming exercises to keep them well organized. To do this type the following commands:

$ cd
$ mkdir Exercises
$ cd Exercises
$ mkdir C
$ mkdir asm
$ cd C

The above set of commands will create a directory called C under Exercises in your default home directory where you can put all your C programs you write. Now we are ready to write our first C Program. Open an editor to write your first program:

$ joe hello.c

This will open the editor and you can type in your code. Here is your first C Program
#include <stdio.h>
int main(){
  char name[10];
  printf("What is your name: ");
  scanf("%s", name);
  printf("Hello %s\n", name);
  return(0);
}
If you want to learn how to use the editor tpye in Control-k followed by h. To close the file once you finished editing it type  Control-k followed by x.  Now you are ready to compile it, to do so type in the following at the command prompt:

$ lcc -o hello hello.c

This will take produce the assembly, object and symbol table files. Now open the object file in LC3Simulate like you do when you are working with assembly files.  When you run it is LC3Simulate the LC3 console should prompt you for your name and after you enter it should greet you.

That is it!

Bonus

Interestingly, the process of installing the software also gave you the ability to build C programs not just for the LC3 but also to run directly on your PC. That is you can compile the C program you just wrote for the x86 ISA. To do this, you use the gcc compiler instead of the lcc compiler as follows:
 
$ gcc -o hello hello.c

Note the gcc instead of lcc. This will create a file called hello.exe, which is a native executable for Windows. Run it as follows: