
Explanations of files in the test_code directory
------------------------------------------------

 These programs are used to test that vmips works correctly. Hopefully,
 soon, a DejaGNU test suite will be built around these, to automate
 checking of test results.

 Makefile.in - a Makefile generated from this by configure is used to
 build the test cases, and is also a shining example of how to build
 ROMs in general (in concert with setup.S and ld.script, generated from
 ld.script.in).

 asm_regnames.h - makes the so-called "software names" available to
 the assembler.

 bdexcp.S - intended to cause a bus error resulting from an access to
 a nonexistent memory address from a load instruction in the branch
 delay slot.

 clocker.S - intended to demonstrate the use of the clock interrupt,
 by printing a dot once each second.

 echo.c - intended as a very simple test program for the spim serial
 console chip. this program prints prompts, and echoes serial input bytes
 on the serial output (surrounded by brackets) until ^D is input.

 emptymain.c - this is a C file with an empty entry function used in the
 debugging of setup.S.

 exception.S - code to trigger an overflow exception (in the "add"
 statement) and a breakpoint exception (in the "break" statement).

 hello.c - a very simple "Hello, world!" ROM which outputs to the
 spim-compatible serial console device by polling.

 ld.script.in - ld.script, generated from this by configure, defines
 the layout of the program in a ROM file (for the benefit of the linker)
 and how it differs from the layout of the same program in the simulator.
 Originally advertised as "the answer to your every relocation woe."

 load.S - loads of all three data sizes (word, halfword, byte).

 loser.S - a 4-byte rom, used to demonstrate what happens when you run
 off the end of memory. (There's a special rule in the Makefile to build
 this one; usually ROMs are some multiple of the host system's page size,
 for the benefit of mmap.)

 mumble.S - zeroes out all the registers. use vmips -o dumpcpu to verify
 the results. this was the first program run on vmips.

 random.c - Random number generator from FreeBSD's C library. (This should
 eventually be expunged from source releases due to its non-GPL status.)

 setup.S - The original note for this file read: "the mini-kernel used to
 run sort.c; this will undoubtedly have a prolonged, painful existence and
 support many programs it was never meant to support." This prediction has
 proved to be true. However, now it supports halting vmips when exceptions
 occur, and has gdb support (added correct stabs entries).

 sort.c - an insertion sort demo. uses random.c or the CP0 Random register.
 use memdump option to vmips and od(1) to see results.

 tester.c - This was the first C program run on vmips.  It is a
 fixed-data, register implementation of the Euclidean Algorithm for
 computing the greatest common divisor. Here is a list of the (ten)
 calculations that it completes for a = 120,923,429 and b = 30,030:

   120923429 % 30030 = 22649
       30030 % 22649 = 7381
        22649 % 7381 = 506
          7381 % 506 = 297
           506 % 297 = 209
           297 % 209 = 88
            209 % 88 = 33
             88 % 33 = 22
             33 % 22 = 11
             22 % 11 = 0

 The key thing about this code is that it doesn't have any references
 to memory, and doesn't call any procedures or do anything that needs
 the stack.  Hence, it can operate without any loading or storing
 beyond that which is required for instruction fetching from uncached,
 non-TLB-mapped memory.

 You can use this code to verify that branches happen the instruction
 after they're executed (i.e., branch delay slot emulation is as
 expected), and the "haltdumpcpu" option can be used to determine that
 the program terminated correctly (whichever register corresponds to the
 result will contain 0x0b).

CVS: $Id: README,v 1.2.2.1 2001/12/29 09:38:47 brg Exp $

