Instruction Set Architecture (ISA)

Instruction Classes

Class Format Key
b-class 00ii iiii i = instruction
t-class 0100 ixxx i = instruction, x = argument
e-class* 0101 iiii xxxx xxxx xxxx xxxx i = instruction, x = argument
v-class 011i xxxx i = instruction, x = argument
j-class 10ix xxxx i = instruction, x = argument
x-class 11xx xxxx x = argument

* stored in big-endian format

Color Codes:

  General purpose instruction
  Sets condition code
  Accessor to acquaintance list
  Migration instruction
  Accessor to the heap
  Accessor to sensors
  Local tuple space operation
  Remote tuple space operation

Variable type abbreviations

B-class Instructions [00ii iiii]

-

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
halt Halt execution 0x00     Halts execution of the issuing agent. This frees the agent's context for another incomming agent.
addr Push host address 0x01   [value] Pushes the mote's address onto the operand stack as a value.
aid Push agent ID 0x02   [agentid] Pushes agent's ID onto the operand stack.
rand Push random number 0x03   [value] Pushes a 16-bit random number onto the operand stack as a value.
cpush Pushes condition onto the stack 0x04   [value] Pushes the issuing agent's condition variable onto its stack as a value.
loc Push host location 0x05   [location] Pushes the mote's location onto the operand stack as a value.
vicinity Checks if dist <= 2 0x06 [location]   Checks whether the location on the stack is within a distance of <= 2 of the location(s) on the heap. Heap [0] must be the number of locations, Heap[1...n] must be the locations.
clear Clear the operand stack 0x07     Clear the operand stack.
numnbrs number of neighbors 0x08   [value] Pushes the number of neighbors onto the stack.
randnbr get random neighbor 0x09   [location] Pushes the location of a random neighbor onto the stack. Sets condition = 1 if success, else sets condition = 0.
wait make agent wait 0x0a     Stops agent execution without deallocating its resources. Allows it to wait for a reaction to fire

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
inc Increment value 0x0b

[value]

or

[location]

[value+1]

or

[loction]

Pops a value off the operand stack and pushes the incremented value back onto the stack.

If the top of the stack is a location, it increments the location as follows: If heap[11] = <value:1> increment only x, if heap[11] = <value:2> increment only y, otherwise increment both x and y

clearvar Clear heap variable 0x0c [value]   Pops a heap address value off the operand stack and clears the heap at that address.
inv Invert a value 0x0d [value] [value] Pops a value off the operand stack, multiplies it by -1, and pushes the result onto the stack.
not Boolean not 0x0e [value] [value] Pops a value off the operand stack. If the value is not 0, push a 0 onto the stack, else push a 1.
lnot logical not 0x0f [value] [value] Pops a value off the operand stack and pushes its logical not (e.g. 0x2e will result in 0xffd1).
copy Copy top of operand stack 0x10 [var] [var], [var] Pops a variable off the operand stack, pushes it back onto the stack twice.
pop Pop top of operand stack 0x11 [var]   Pops a variable off the operand stack.
cpull Pulls value from stack onto condition 0x12 [value]   Pops the value off the stack and sets it to be the condition.
sleep Sleep 0x13 [value]   Halt the issuing agent for [value] * 0.125 seconds.
jumpc Absolute jump condition 0x14 [value]   Jump to the absolute address specified in the value on top of the operand stack if the condition is > 0. Decrements the condition code if jump.
jumps Absolute jump stack 0x15 [value]   Jump to the absolute address specified in the value on top of the operand stack.
putled Actuate LEDs 0x16 [value] or [reading]  

Takes a single operand and lights the LEDs as follows.

If the operand is a value: It uses the lowest five bits of the operand to determine how to actuate the LEDs. The lowest three bits denote the 3 LEDs; bit 0 is red, bit 1 is green, and bit 2 is yellow. The next two bits (3 and 4) specify which operation to apply; 00 is set, 01 is off (active on 0), 10 is on, and 11 is toggle. For example, 31 (0x1f) toggles all three LEDs, 19 turns the red and green off (leaving yellow unchanged), and 0x2 sets the LEDS to be red off, green on, and yellow off.

Operation
Binary Value
Decimal Value
set only red on
00001
1
set only green on
00010
2
set only yellow on
00100
4
Toggle red
11001
25
Toggle green
11010
26
Toggle yellow
11100
28
Toggle all 3 LEDs
11111
31
Turn off red
01110
14
Turn off green
01101
13
Turn off yellow
01011
11
Turn off all 3 LEDs
01000
8
Turn on red
10001
17
Turn on green
10010
18
Turn on yellow
10100
20
Turn on all LEDs
10111
23


If the operand is a reading, it simply displays the lower 3 bits in on the LEDs.

smove Strong migration 0x17 [location]  

Performs a strong migration to a remote host. The location of the remote host is specified by the parameter on top of the operand stack. A strong migration does not affect the execution of the agent (the pc, stack, and heap are all maintained). The condition code is set as follows:

  • 0 - move failed (agent continues to run on original host)
  • 1 - move succeeded (agent now runing on remote host)
wmove Weak migration 0x18 [location]   A weak version of smove.
sclone Strong clone 0x19 [location]  

Pops the value off the operand stack. Clones itself at node with address value. The clone inherits the initiating agent's program counter.

The condition code is set as follows:

  • 0 - clone failed (agent continues to run on original host)
  • 1 - clone succeeded, this is the clone
  • 2 - clone succeeded, this is the parent
wclone Weak clone 0x1a [location]   A weak version of sclone. The condition codes are modified in the same way (i.e., 0 = fail, 1 = clone, 2 = parent).
getvars get a heap var, address in stack 0x1b [value] [var] Retrieves a variable off the heap and pushes it onto the operand stack. The address of the heap is specified by the value on top of the stack.
setvars set heap var, address in stack 0x1c

[value]
[var]

  Saves a variable on the heap. The variable and address to store it must both be on the operand stack.
getnbr get neighbor address 0x1d [value] [location]

Get the address of the neighbor. All neighbors are stored in a list. The value specifies which position in the list to get. The value must be between 0 and numnbrs-1. Sets condition = 1 if success, else sets condition = 0.

Note: There is no synchronization between a call to numnbrs and subsequent calls to getnbr, nor is there any between two calls to getnbr. Since the neighbor list is dynamic, calling getnbr may fail or may return the same neighbor using two different indices. Failure is indicated by setting the condition code to 0.

The suggested way of iterating through all neighbors is to take a snapshot of the neighbor list by calling numnbrs, then immediately calling getnbr to push the entire list onto the stack.

cisnbr is neighbor 0x1e [location]   Pops a location off the operand stack, sets the condition = 1 if the location is a neighbor.
sense take a sensor reading 0x1f [value]

[reading]

Reads a sensor. The sensor type is specified by the value on top of the operand stack, defined as follows:

  • Photo = 1
  • Temp = 2
  • Microphone = 3
  • Magnometer X = 4
  • Magnometer Y= 5
  • Accelerometer X =6
  • Accelerometer Y= 7
  • Sounder = 8

 

dec decrement 0x20 [value] or [location] [value] or [location] decrements a value or location. heap[11] is used to determine which axis to decrement in the case of a location. If heap[11] is not set, it decrements both the x and y coordinates, if heap[11] is 1 it only decrements the x coordinate, if heap[11] is 2 it only decrements the y coordinate.

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
dist distance 0x21

[location1],
[location2]

or

[reading1],
[reading2]

[value]

Pops two variables off the operand stack. If the two variables are both locations, this calculates the distance between them. The distance is calcualted using |x1-x2|^2 + |y1-y2|^2.

If the two variables are both sensor readings, this calculates how far apart they are.

swap Swap top two varibles 0x22 [var1], [var2] [var2],
[var1]
Pop [var1] then [var2] off the stack, then push [var2] then [var1] back on stack. This swaps their positions on the stack.
land logical bitwise AND 0x23 [value1], [value2] [value] Pop [value1] and [value2] off the stack. Then perform a logical bitwise AND between them and push the resulting value back onto the stack.
lor logical bitwise OR 0x24 [value1], [value2] [value] Pop [value1] and [value2] off the stack. Then perform a logical bitwise OR between them and push the resulting value back onto the stack.
and boolean AND 0x25 [value1], [value2] [value] Pop [value1] and [value2] off the stack. If both [value1] and [value2] are non-zero, push a 1 value onto the stack, else push a 0.
or boolean OR 0x26 [value1], [value2] [value] Pop [value1] and [value2] off the stack. If [value1] or [value2] are non-zero, push a 1 onto the stack, else push a 0.
mul Multiply 0x27 [variable1], [variable2]] [variable1] * [variable2] Pops two variables off the stack and performs a multiplication. Valid parameters are:
  • Two values
  • Two loctaions
  • A a value and a location
  • A value and a sensor reading

If heap[11]=1, only consider the x-coordinate, else if heap[11]=2, only consider the y coordinate. Otherwise, consider both coordinates.

div Divide 0x28 [variable1], [variable2] [variable2]
-----------
[variable1]

Pops two variables off the stack and performs a division operation. Valid parameters are:

  • Two values
  • Two loctaions
  • A a value (variable 1) and a location (variable 2)
  • A value (variable 1) and a sensor reading (variable 2)

Whenever a location is involved, heap[11] indicates which axis to consider. If heap[11]=1, only consider the x-coordinate, if heap[11]=2, only consider the y coordinate. By default consider both coordinates.

add Add two values 0x29 [value1], [value2] [value]

Pop [value1] and [value2] off the stack, push [value1] + [value2] onto the stack.

If adding a location and value, heap[11] is used: if 0 add value to both x and y, if 1 add only to x, if 2 add only to y.

mod Modulo 0x2a [value1], [value2] Value Pops the top two values off the stack. Pushes [value2] mod [value1] onto the stack as a value.
ceq Equal 0x2b [var1], [var2]  

Pop two variables off the stack. Set the condition to true if [var1] and [var2] have the same type and value. If one variable is an AgentID and the other a Value, the condition is set to true if the AgentID's unique id is equal to the value.

If the two values are type location and heap[11] contains a value, the value determines what to compare: 1 = x, 2 = y, otherwise both axies.

cneq Not Equal 0x2c [var1], [var2]   The opposite of ceq.
clt Less than 0x2d [Value1], [Value2] or [Reading1], [Reading2]   Pops the top two values off the stack. Set the condition to true if [Value2] < [Value1] or [Reading2] < [Reading1], false otherwise
cgt Greater than 0x2e [Value1], [Value2] or [Reading1], [Reading2]   Pops the top two values off the stack. Set the condition to true if [Value2] > [Value1] or [Reading2] > [Reading1], false otherwise
clte Less than or equal 0x2f [Value1], [Value2] or [Reading1], [Reading2]   Pops the top two values off the stack. Set the condition to true if [Value2] <= [Value1] or [Reading2] <= [Reading1], false otherwise
cgte Greater than or equal 0x30 [Value1], [Value2] or [Reading1], [Reading2]   Pops the top two values off the stack. Set the condition to true if [Value2] >= [Value1] or [Reading2] >= [Reading1], false otherwise
ceqtype Tests type equality 0x31 [var1], [var2]   Pops the top two variables off the operand stack and sets cond=1 if they are of the same type, cond=0 otherwise.
cistype Checks type 0x32 [type], [var]   Pops a type and variable off the operand stack. If the variable type equals the type popped off, set cond=1, else cond=0.
out out on host tuple space 0x33 [tuple]   Pops a tuple off the operand stack and places it into the local tuple space. This tuple become a public tuple accessible to anybody.
inp inp on host tuple space 0x34 [template] [tuple] ? Searches the host's local tuple space for a tuple matching a template. If a match is found, remove it from the tuple space, push its fields onto the operand stack and set the condition to 1. If no matching tuple is found, set condition to 0.
rdp rdp on host tuple space 0x35 [template] [tuple] ? Same as inp except do not remove tuple.
in in on host tuple space 0x36 [template] [tuple] Same as inp except blocks until a tuple is found.
rd rd on host tuple space 0x37 [template] [tuple] Same as rdp except blocks until a tuple is found.
tcount counts the number of tuples in the local tuple space that match a template 0x38 [template] [value] Pops a template off the op stack and pushes the number of tuples that match it onto the op stack. This operation only considers tuples that are public, system, or private to the executing agent.
rout remote OUT 0x39

[location],
[tuple]

  Inserts a tuple into a remote hosts's tuple space. Sets cond=1 if successful, 0 otherwise. The tuple becomes a public tuple accessible to anybody.
rinp remote INP 0x3a

[location],
[template]

[tuple] ? Performs a INP operation on a remote host. Blocks until the results are received, a NACK is received, or AGILLA_RTS_MAX_NUM_TRIES timeouts occur. If the results arrive, cond=1 and the result is placed onto operand stack. Otherwise, cond=0. Only public tuples are considered.
rrdp remote RDP 0x3b [location],
[template]
[tuple] ? Same as rinp except performs a remote RDP.

rinpg

N/A
remote INPG 0x3c

[location],
[template]

  Performs an INPg operation on the host located at the specified location. The results are placed into the local tuple space marked with the initiating agent as the owner. The operation blocks until timeout occurs. If any result arrive, cond=1, else cond=0. Only public tuples on the destination host are considered. Tuples already in the local tuple space are not considered.

rrdpg

remote RDPG 0x3d [template]
 [value],
[location},
...
or
nothing
Searches all one-hop neighbors for a matching tuple. If at least one match is found, condition=1 and the location(s) are stored on the heap where heap[0] is the number of results, and heap[1...n] are the locations. If no results are found, the heap is not modified and cond=0. Note that at most heap[0...8] will be used.
regrxn register reaction 0x3e [value], [template]   Registers a reaction on the tuplespace. The template specifies the type of tuple that causes the reaction to fire. The value specifies what the program counter should be set to when the reaction fires. Reactions are carried across strong migrations and clones.
deregrxn deregister reaction 0x3f [template]   Deregisters a reaction from the tuplespace.

 

T-Class Instructions [0100 ixxx]

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
pushrt push reading type 0x40-0x47   [type]

Pushes a reading reading type onto the operand stack.

  • 001 - photo reading [PHOTO]
  • 010 - temperature reading [TEMP]
  • 011 - microphone reading [MIC]
  • 100 - magnometer x-axis reading [MAGX]
  • 101 - magnometer y-axis reading [MAGY]
  • 110 - accelerometer x-axis reading [ACCELX]
  • 111 - accelerometer y-axis reading [ACCELY]
pusht Push type 0x48-0x4d   [type]

Pushes a type onto the operand stack.

  • 000 - ANY
  • 001 - AGENTID
  • 010 - STRING
  • 011 - TYPE
  • 100 - VALUE
  • 101 - LOCATION
    0x4e-0xe4f      

 

E-Class Instructions [0101 iiii xxxx xxxx xxxx xxxx]

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
pushn Push a name onto the operand stack 0x50   [name] Pushes a name onto the operand stack. A name is a 16-bit value with the following format: [a-z,0-9][a-z,0-9][a-z,0-9]. It is encoded as follows: [a = 1, b = 2, ..., 0 = 26, 1 = 27, ...].
pushcl Push constant long 0x51   [value]

Pushes a 16-bit value onto the operand stack. This is more powerful than pushc since pushc can only push a 6-bit value onto the operand stack.

One special value you can push onto the stack is "uart". You can, for example, pushcl uart, then smove to move the agent onto the PC.

pushloc Push a location onto the stack 0x52   [location] Pushes a location onto the stack. Syntax is pushloc x y where (x,y) is the location that is placed onto the stack.
    0x53-0x5f      

 

V-Class Instructions [011i xxxx]

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
getvar moves a variable from the heap to the stack 0x60 - 0x6b   [var]

Copies a variable from the heap and pushes it onto the stack. The address within the heap is specified by the last 4 bits of the instruction. Since there is only a 12-word heap, only addresses 0-b are valid.

If the heap variable is INVALID, it does not push anything onto the stack and sets condition=0. Otherwise, it sets condition=1.

    0x6c - 0x6f      
setvar Moves a variable from the stack to the heap 0x70 - 0x7b [var]   Pops a variable off the operand stack and puts it into the heap. The address within the heap is specified by the last 4 bits of the instruction. Since there is only a 12-word heap, only addresses 0-b are valid.
    0x7c-0x7f      

 

J-Class Instructions [10ix xxxx]

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
rjumpc conditional relative jump 0x80 - 0x9f     Performs a relative jump if the condition code is > 0. Decrements the condition code if jump. The last 5 bits of the instruction is treated as a 2-complement integer and is added to the agent's program counter. (Allows an agent to jump forward or backward 15 instructions).
rjump unconditional relative jump 0xa0 - 0xbf     Performs an unconditional relative jump. The last 5 bits of the instruction is treated as a 2-complement integer and is added to the agent's program counter. (Allows an agent to jump forward or backward 15 instructions).

 

X-Class Instructions [11xx xxxx]

Instruction

Short Description Opcode Initial Stack Final Stack Long Description
pushc Push a constant value onto the stack 0xc0 - 0xff   [value] Pushes the least signicant 6 bits onto the operand stack as a value (range is 0 to 63).

 

 


This work is supported by the ONR MURI Project CONTESSA and the NSF under grant number CCR-9970939.