Assignment 0

Installing and running the CASH compiler

As currently tested, the CASH compiler runs on RH 9.0 machines. It can be made to run on newer distros, but it takes some effort (more on this later). Most of the tools that you will need to use are command-line only, so ssh-ing into a remote machine to compile and run the compiler usually works quite well (in fact, this is how we do it).

All of you have been given accounts on two RH 9 machines:

  1. habu.crcl.cs.cmu.edu
  2. blackmamba.crcl.cs.cmu.edu
Those with CS kerberos identities can log into the machines using your CS username and password; those without CS accounts need to use their {ece,andrew} usernames. Your password is username745. Log in and change this ASAP, on both machines. Use the passwd -l command. All of you have local diskspace on these machines, in /usr1/users/745/.

Those with access to other AFS-enabled RH9 machines should also be able to run everything on those machines with no problems (fingers crossed).

On newer distros, running the infrastructure will take some effort. In particular, we might need to hack your libc.so, and make some small hacks to some other scripts and libraries. Nevertheless, if you are interested in doing this, let me know and I will tell you how (I might need to spend an hour or so with you on your machine to figure things out).

All right, with that out of the way, it is time for you to get the compiler, compile it, and test it.

  1. You will need a working directory where the compiler will live. This will grow to about 100MB. If your AFS quota permits, I recommend using AFS for the working directory so you can edit the code from your own desktops (ece, andrew users: use the klog command to access your afs accounts from habu and blackmamba). I shall call this WORK in subsequent steps.

  2. copy /afs/cs/academic/class/15745-s07/bin/745_setup.sh to your own space. At the top of the script is the variable INSTALL_BASE. Set this to WORK chosen in (1) above.

  3. 745_setup.sh is a bash script that needs to be sourced, like this: 

    $ . ./745_setup.sh

    csh/other shell users: please modify this suitably, and donate the modified versions to me :)

    After sourcing the 745_setup.sh script, your WORK directory should now have three subdirectories: suif/, scripts/ and config/.

    NOTE: you will need to source 745_setup.sh every time you log in, since it sets a bunch of envars.

  4. cd to WORK/suif/passes, and run make. This will compile the compiler (and probably take 10-15 mins. to do it).

    At this point, you should have a working CASH compiler. To check this, type the c2dil command, and make sure a long list of usage command gets printed out (the CASH binary is actually called "c2dil" for historical reasons, and we are too lazy to fix all the scripts and documentation to change it something more current).

  5. Run the following: 

    $ cd WORK/suif/passes/c2dil/Sample/1
$ make -f MakeProg
    This will compile one function of a sample program in Sample/1/ to C6x assembly. The assembly will be dumped to a file called asm.out in the same directory. You can clean up everything that the CASH compiler generated by typing 
    make -f MakeProg cl
    . If you want to look at an alternative, bigger example, play around with Sample/2/

Note:

The CASH compiler is buggy. In particular, it has the following problems right now:

  1. The compiler works well when compiling only one function. So, either put the function to be compiled in a file all by itself (as done in Sample/1/) or specify the function to be compiled in MakeProg (see Sample/2/).

  2. The clean-up and exit code causes a failure after the C6x assembly has been dumped. Ignore this for now, since this failure happens after the compiler has done what you want it to do.

  3. The compiler scheduler has a bug. We will see its manifestation, and how to manually fix the generated assembly code, in the next step. This bug has been fixed. Please cvs update as follows: 
    $ cd WORK/suif/passes/c2dil
$ cvs update
$ make

We hope to have all 3 2 of these problems solved over the weekend.

Assembling and simulating the generated code

This happens using TI's tools on a Windows machine. If you have a Windows machine on which you can install these tools, read on. If you would rather ssh into the class Windows box and use command-line versions of these tools, go here.

Documentation about the TI DSP and the Code Composer IDE is available here.

  1. Fire up the AFS client on your machine. Navigate to /afs/cs/academic/class/15745-s07/TI_Code_Composer/. Run the Setup.exe in that directory. All the defaults it suggests are reasonably sane.

  2. Fire up the "Texas Instruments->Code Composer Studio->Code Composer Studio" application from your start menu. When you run it the first time, it will ask you to do some setup; click "yes", select "C62xx CPU cycle accurate simulator, little endian", click "Import", click "Save and Quit", and click "Yes" finally to start up Code Composer Studio.

  3. Go to C:\CCStudio\MyProjects (assuming you accepted installation defaults) and create a directory called "squares_test" (this is your CCStudio project directory. This can actually be anywhere; in particular, the working dir you used for CASH can double as your CCStudio working dir if you put it in AFS).

  4. copy over main.c, sumsquares.h and asm.out to the squares_test directory. Rename asm.out to asm.out.s

  5. In CCStudio, click Project->New, give "squares_test" as project name and accept the other defaults

  6. Right-click on the project name in the left pane, click on "Add Files to Project...", and add the following files:
    1. squares_test/main.c
    2. squares_test/asm.out.s
    3. C:\CCStudio\C6000\cgtools\lib\rts6200 (this is the C library)
    (You do not need to add sumsquares.h)

  7. Right click on the project name again, click on "Build". The bottom pane will show the build status, with Errors and Warnings. Ensure that it gives you Warnings but no Errors (the Warnings will go away when we generate some config files and give them to you. Hopefully in the next day or two).

    Look at the C62xx CPU and Instruction Set Reference Guide on the documentation webpage to learn about the TI DSP, its hardware strtucture, and basic information about the assembly language, scheduling restrictions etc. Chapters 1 through 3.8 would be an excellent start. (The following ex-bug is explained in sectioned 3.7).

    Because of the aforementioned bug in the CASH scheduler, there is one error while compiling asm.test.s. To fix this problem, go the lines inicated in the error messages and change 

    ||      [A1]    b       L4
||              mv.L2   B0, B2
||      [!A1]   b       L1
    to 
    ||      [A1]    b       L4
||              mv.L2   B0, B2
        [!A1]   b       L1

  8. Load the just compiled binary into the simulator, by selecting File->Load Program... and selecting the squares_test\Debug\squares_test.out file.

  9. To simulate this program, click on Debug in the top menybar, then click on "Run". At the bottom, the "stdout" pane should contain the program's output (in this case, the sum of squares of 1 to 10).

To learn more about the Code Composer tool, see the Beginner's Guide linked off the Documentation page.

Using command-line versions of the Windows tools through ssh

 Remember that you can do this only after I have created an account for you, and you have done a console login on the machine and worked through a few steps. If you would like to do this, send me email. Do steps 1 and 2 on your desktop:
  1. If you are using a CS machine, put the following ssh server public ID key into your ~/.ssh/known_hosts (all in a single line, with no gaps) 
    romano,romano.crcl.cs.cmu.edu 2048 35 24050991831575791525968991373983841854072096851228808008572558922294086733884803414156588924544035065492716284906141496545998708985157062150902029283129282505976758809749334439919512494292626150378989647254325954747286701694549916334069222348267303128351223409041480151078033256606943139944786707356765408230292989200604704306008703207059293749170522121433662473556270799802191365055247146166640704014142708656101168376894062163150068557545106407849530129370701699603153461823222326945357155662448635220931605820079055688224793673870618477943699689055934909889975317638541717179399019757058214717951889477070569758053
  2. ssh -l <username> romano.crcl.cs.cmu.edu

    Steps 3 through 6 are on romano

  3. copy /home/mahim/bin/745_setup_win.sh, source it (put in ~/.bash_profile so it is sourced everytime)

  4. scp your files into your home dir

  5. Rename asm.out to asm.out.s

  6. To compile: cl6x <file1> ... <filen> -z -lrts6200.lib -o <binary file>

    Run cl6x to see options.

    See chapters 2 and 5 of the optimizing compiler guide to learn much more

  7. To simulate: load6x <binary file>

    Run load6x -help to see options

    See chapter 6 of the optimizing compiler guide to learn much more