CS232 Fall 2011: SPIMbot Documentation

CS 232 SPIMbot documentation

Introduction

To make some of our MP's a little more interesting, we'll write programs for NASA's next-generation Mars rover called SPIMbot. Due to budget cuts, SPIMbot is not nearly as sophisticated as previous Mars rovers.

SPIMbot Input/Output:

SPIMbot's sensors and controls are manipulated via memory-mapped I/O; that is, the I/O devices are queried and controlled by reading and writing particular memory locations. All of SPIMbot's I/O devices are mapped in the memory range 0xffff0000 - 0xffffffff. Below we describe SPIMbot's I/O devices and their associated control and data registers.

Name Address Acceptable Values/Range Explanation

VELOCITY_VALUE 0xffff0010 10 to -10 Writing this location immediately updates SPIMbot's velocity.

ORIENTATION_VALUE 0xffff0014 360 to -360 This value is used when ORIENTATION_CONTROL is written; no immediate effect from writing this register.

ORIENTATION_CONTROL 0xffff0018 0 (relative), 1 (absolute) Writing this control register will update SPIMbot's orientation, using the last value written to ORIENTATION_VALUE as a relative or absolute angle (depending on the value written to this register).

SPIMBOT_X_LOCATION 0xffff0020 0 to 300 Reading this gives your SPIMbot's current X location.

SPIMBOT_Y_LOCATION 0xffff0024 0 to 300 Reading this gives your SPIMbot's current Y location.

WHICH_BLOCK 0xffff0070 0 - 10 Writing this address records which block you want to communicate with.

BLOCK_X 0xffff0070 0 - 300 Reading this location provides the x location of the center of the block whose number was most recently written to WHICH_BLOCK.

BLOCK_Y 0xffff0074 0 - 300 Reading this location provides the y location of the center of the block whose number was most recently written to WHICH_BLOCK.

CLUE_ADDR 0xffff007c any valid address By writing this location with a value corresponding a memory location, SPIMbot can request a clue for the current block (based on what number was last written to WHICH_BLOCK). The clue comes in the form of a cyclic graph whose pointers whose contents have been bit-reversed (a la MP#3), which gets written in the 4096 bytes starting at the specified address. After solving for the number of nodes in the graph, that value can be used as a key for either BLOCK_UNLOCK or BLOCK_LOCK. Clue requests have a long latency (100,000 cycles) and, if enabled, a CLUE_INTERRUPT will be raised when the clue is ready. Also, another request cannot be made within 10,000 cycles of a previous request. Reading this memory-mapped I/O location will tell you the number of cycles until the clue generator will accept the next request.

PRINT_INT 0xffff0080 any Prints an integer to the screen. (useful for debugging)

PRINT_FLOAT 0xffff0084 any Prints a floating point value to the screen. (useful for debugging)

BLOCK_UNLOCK 0xffff0090 any By writing this location with the most recent CLUE value for the current block (based on what number was last written to WHICH_BLOCK), the block will become unlocked for you. Block state doesn't change for opponent. If you enter an incorrect key value, you will not be able to manipulate this block for the rest of the contest. Each key can only be used once; the key value changes every time you request a new clue.

BLOCK_LOCK 0xffff0094 any By writing this location with the most recent CLUE value for the current block (based on what number was last written to WHICH_BLOCK), the block will become locked for your opponent. Block state doesn't change for you. If you enter an incorrect key value, you will not be able to manipulate this block for the rest of the contest. Each key can only be used once; the key value changes every time you request a new clue.

OTHER_BOT_X_LOC 0xffff00a0 0 to 300 Reading this gives your opponent's current X location.

OTHER_BOT_Y_LOC 0xffff00a4 0 to 300 Reading this gives your opponent's current y location.

We describe these in more detail below.

Velocity Control: SPIMbot's velocity can be set by writing to address 0xffff0010. Integer values between -10 and 10 (inclusive) are accepted. Reads are not supported.

Orientation Control: SPIMbot's orientation can be controlled in two ways: 1) by specifying an adjustment relative to the current orientation, and 2) by specifying an absolute orientation.
In both cases, an integer value (between -360 and 360) is written to the "orientation value register" (0xffff0014) and then a command value is written to the "orientation control register" (0xffff0018). If the command value is 0, the orientation value is interpreted as a relative angle (i.e., the current orientation is adjusted by that amount). If the command value is 1, the orientation value is interpreted as an absolute angle (i.e., the current orientation is set to that value).
Angles are measured in degrees, with 0 defined as facing right. Positive angles turn SPIMbot clockwise. While it may not sound intuitive, this matches the normal Cartesian coordinates (in that the +x direction is angle 0, +y=90, -x=180, and -y=270), since we consider the top-left corner to be (0,0) with +x and +y being right and down, respectively.

Running and Testing Your Code:

You can run and test your code using the spimbot executable available on the Sun EWS machines; because it is located at ~cs232/Linux/bin/spimbot it should be in your path when you issue the cs232 command.

spimbot's interface is much like that of xspim (upon which it is based). You are free to load your program as you did in xspim using the buttons. Both xspim and spimbot allow your program to be specified on the command line using the -file argument. In addition, SPIMbot includes two arguments (-maponly and -run) to facilitate rapidly evaluating whether your program is robust under a variety of initial conditions (these options are most useful once your program is debugged).

Useful command line arguments:

-file <file.s> Specifies the assembly file to use

-file2 <file.s> Specifies the assembly file to use for a second SPIMbot

-maponly Doesn't pop up the xspim window

-run immediately begins the execution of SPIMbot's program

-largemap draws a larger map (but runs a little slower)

-debug prints out scenario-specific information useful for debugging

-prof_file specifies a file name to put gcov style execution counts for each statement.

-tournament A command that disables the console, SPIM syscalls, and some other features of SPIM for the purpose of running a smooth tournament.

-exit_when_done Automatically closes SPIMbot when contest is over.

zilles@cs.uiuc.edu

Name	Address	Acceptable Values/Range	Explanation
VELOCITY_VALUE	`0xffff0010`	10 to -10	Writing this location immediately updates SPIMbot's velocity.
ORIENTATION_VALUE	`0xffff0014`	360 to -360	This value is used when ORIENTATION_CONTROL is written; no immediate effect from writing this register.
ORIENTATION_CONTROL	`0xffff0018`	0 (relative), 1 (absolute)	Writing this control register will update SPIMbot's orientation, using the last value written to ORIENTATION_VALUE as a relative or absolute angle (depending on the value written to this register).
SPIMBOT_X_LOCATION	`0xffff0020`	0 to 300	Reading this gives your SPIMbot's current X location.
SPIMBOT_Y_LOCATION	`0xffff0024`	0 to 300	Reading this gives your SPIMbot's current Y location.
WHICH_BLOCK	`0xffff0070`	0 - 10	Writing this address records which block you want to communicate with.
BLOCK_X	`0xffff0070`	0 - 300	Reading this location provides the x location of the center of the block whose number was most recently written to WHICH_BLOCK.
BLOCK_Y	`0xffff0074`	0 - 300	Reading this location provides the y location of the center of the block whose number was most recently written to WHICH_BLOCK.
CLUE_ADDR	`0xffff007c`	any valid address	By writing this location with a value corresponding a memory location, SPIMbot can request a clue for the current block (based on what number was last written to WHICH_BLOCK). The clue comes in the form of a cyclic graph whose pointers whose contents have been bit-reversed (a la MP#3), which gets written in the 4096 bytes starting at the specified address. After solving for the number of nodes in the graph, that value can be used as a key for either BLOCK_UNLOCK or BLOCK_LOCK. Clue requests have a long latency (100,000 cycles) and, if enabled, a CLUE_INTERRUPT will be raised when the clue is ready. Also, another request cannot be made within 10,000 cycles of a previous request. Reading this memory-mapped I/O location will tell you the number of cycles until the clue generator will accept the next request.
PRINT_INT	`0xffff0080`	any	Prints an integer to the screen. (useful for debugging)
PRINT_FLOAT	`0xffff0084`	any	Prints a floating point value to the screen. (useful for debugging)
BLOCK_UNLOCK	`0xffff0090`	any	By writing this location with the most recent CLUE value for the current block (based on what number was last written to WHICH_BLOCK), the block will become unlocked for you. Block state doesn't change for opponent. If you enter an incorrect key value, you will not be able to manipulate this block for the rest of the contest. Each key can only be used once; the key value changes every time you request a new clue.
BLOCK_LOCK	`0xffff0094`	any	By writing this location with the most recent CLUE value for the current block (based on what number was last written to WHICH_BLOCK), the block will become locked for your opponent. Block state doesn't change for you. If you enter an incorrect key value, you will not be able to manipulate this block for the rest of the contest. Each key can only be used once; the key value changes every time you request a new clue.
OTHER_BOT_X_LOC	`0xffff00a0`	0 to 300	Reading this gives your opponent's current X location.
OTHER_BOT_Y_LOC	`0xffff00a4`	0 to 300	Reading this gives your opponent's current y location.

`-file <file.s>`	Specifies the assembly file to use
`-file2 <file.s>`	Specifies the assembly file to use for a second SPIMbot
`-maponly`	Doesn't pop up the xspim window
`-run`	immediately begins the execution of SPIMbot's program
`-largemap`	draws a larger map (but runs a little slower)
`-debug`	prints out scenario-specific information useful for debugging
`-prof_file`	specifies a file name to put gcov style execution counts for each statement.
`-tournament`	A command that disables the console, SPIM syscalls, and some other features of SPIM for the purpose of running a smooth tournament.
`-exit_when_done`	Automatically closes SPIMbot when contest is over.