[insert project logo here (125x200px max)]

Navigator

Mailing-lists

Please report any errors or omissions you find to our `Help' mailing-list, or post a message in the Forums.

Copyright and Licensing Information

Snap is (c) Jonathan T. Moore, 1999-2002 and licensed under the GNU General Public License (GPL).

All other parts of Splash are (c) Willem de Bruijn, 2002-2003 and licensed under the BSD Open Source License.

All sourcecode is made publicly available.

Acknowledgment

Splash and the Splash website are hosted by SourceForge.net

SourceForge.net Logo

osi-open source certified logo

Splash - Documentation

SNMP Plus a Lightweight API for SNAP Handling

SNAP Instruction Reference

This manual contains a complete enumeration of the current SNAP instruction set. We will use the notation s[i] to refer to the ith stack value, with s[0] being the top stack value. The program counter will be abbreviated pc. Branch offsets will be abbreviated off.

1  Control Flow Instructions

  • exit. Terminates the current packet execution.
  • paj n. "Pop and jump." Computes an offset off: = n+ s[0]. Pops s[0] from the stack, verifies that off > 0, and then sets pc: = pc+ off. Thus, paj 1 with a zero on top of the stack is the same as a pop.
  • tpaj n. "Test, pop, and jump." If s[0] = 0, then sets off: = n + s[1], else off: = 1. Pops s[0] and s[1], verifies that off > 0, and then sets pc: = pc+ off. If s[0] ¹ 0, tpaj n has the same effect as popi 2.
  • ji n. "Jump immediate." Verifies that n > 0, and sets pc : = pc+ n.
  • bez n. "Branch if equal to zero." If s[0] = 0, then sets off: = n, else off: = 1. Pops s[0], verifies that off > 0, and then sets pc: = pc+ off. bez 1 has the same effect as pop.
  • bne n. "Branch if not equal to zero." If s[0] ¹ 0, then sets off: = n, else off: = 1. Pops s[0], verifies that off > 0, and then sets pc: = pc+ off. bne 1 has the same effect as pop.

2  Stack Manipulation Instructions

  • pop. Removes s[0] from the stack, then increments pc.
  • popi n. Removes the top n values from the stack, then increments pc.
  • pull n. Pushes a copy of s[n] on top of the stack (so pull 0 duplicates the top stack value), then increments pc.
  • store n. Overwrites s[n] with the value stored at s[0], pops s[0], then increments pc. store 0 is the same as a pop.
  • pint n. Pushes n onto the stack with an "integer" type tag, then increments pc.
  • paddr n. Pushes n onto the stack with an "address" type tag, then increments pc.
  • ptup n. Pushes n onto the stack with a "tuple" type tag, then increments pc.
  • pexc n. Pushes n onto the stack with an "exception type tag, then increments pc.
  • pstr n. Pushes n onto the stack with a "string" type tag, then increments pc.
  • pflt n. Pushes n onto the stack with a "float" type tag, then increments pc.
  • pullstack. Pulls the nth item from the stack, where s[0] contains n. The results overwrites the top stack value, then increments pc.
  • stackcount. Pushes the number of items on the stack (excluding this new value), then increments pc.
  • stackempty. Pushes a boolean value: 1 if the stack was empty, 0 otherwise, then increments pc.

3  Heap Manipulation Instructions

  • mktup n. Allocates a length-n tuple in the heap, initializes the values with s[0], ¼, s[n - 1], pops s[0], ¼, s[n - 1], and then pushes a tuple value on the stack which is a heap offset indicating the location of the newly allocated tuple. Finally, mktup increments pc.
  • nth n. If s[0] is a tuple value, then nth pops s[0], extracts the nth value from the heap-allocated tuple indicated by the heap offset in s[0] and pushes it on the stack. Finally, nth increments pc.
  • len. If s[0] is a tuple value, len pops s[0] and pushes the length of the tuple to which it points, then increments pc.
  • istup. If s[0] is a tuple value, pushes a 1 on top of it, else pushes 0. Then istup increments pc. Note that unlike the other heap manipulation instructions, istup does not pop any values off the stack before pushing its result.

4  Relational Operators

For the purposes of the relational operators indicated here, two stack values are equal if they are bit-wise equal (note that this implies that their type tags must be equal as well). For results, all relational operators push a 1 if their predicate is true, 0 if it is false. All relational operator instructions increment pc afterwards. Relative order operations such as greater-than or less-than are only valid for integers and floating point numbers.
  • eq. Pops s[0] and s[1] and pushes (s[0] = s[1]).
  • eqint n. Pops s[0] and compares it to n interpreted as an "integer" constant, pushing 1 if they are equal, 0 otherwise.
  • eqadr n. Pops s[0] and compares it to n interpreted as an "address" heap offset pointer, pushing 1 if they are equal, 0 otherwise.
  • eqtup n. Pops s[0] and compares it to n interpreted as a "tuple" heap offset pointer, pushing 1 if they are equal, 0 otherwise.
  • eqexc n. Pops s[0] and compares it to n interpreted as an "exception" constant, pushing 1 if they are equal, 0 otherwise.
  • eqstr n. Pops s[0] and compares it to n interpreted as a "string" heap offset pointer, pushing 1 if they are equal, 0 otherwise.
  • eqflt n. Pops s[0] and compares it to n interpreted as a "float" heap offset pointer, pushing 1 if they are equal, 0 otherwise.
  • neq. Pops s[0] and s[1] and pushes (s[0] ¹ s[1]).
  • nqint n. Pops s[0] and compares it to n interpreted as an "integer" constant, pushing 1 if they are not equal, 0 otherwise.
  • nqadr n. Pops s[0] and compares it to n interpreted as an "address" heap offset pointer, pushing 1 if they are not equal, 0 otherwise.
  • nqtup n. Pops s[0] and compares it to n interpreted as a "tuple" heap offset pointer, pushing 1 if they are not equal, 0 otherwise.
  • nqexc n. Pops s[0] and compares it to n interpreted as an "exception" constant, pushing 1 if they are not equal, 0 otherwise.
  • nqstr n. Pops s[0] and compares it to n interpreted as a "string" heap offset pointer, pushing 1 if they are not equal, 0 otherwise.
  • nqflt n. Pops s[0] and compares it to n interpreted as a "float" heap offset pointer, pushing 1 if they are not equal, 0 otherwise.
  • gt. Pops s[0] and s[1] and pushes (s[1] > s[0]).
  • gti n. Pops s[0] and pushes (s[0] > n), where n is an integer constant.
  • geq. Pops s[0] and s[1] and pushes (s[1] ³ s[0]).
  • geqi n. Pops s[0] and pushes (s[0] ³ n), where n is an integer constant.
  • lt. Pops s[0] and s[1] and pushes (s[1] < s[0]).
  • lti n. Pops s[0] and pushes (s[0] < n), where n is an integer constant.
  • leq. Pops s[0] and s[1] and pushes (s[1] £ s[0]).
  • leqi n. Pops s[0] and pushes (s[0] £ n), where n is an integer constant.
  • fgti n. Pops s[0] and pushes (s[0] > n), where n is a "float" heap offset pointer.
  • fgeqi n. Pops s[0] and pushes (s[0] ³ n), where n is a "float" heap offset pointer.
  • flti n. Pops s[0] and pushes (s[0] < n), where n is a "float" heap offset pointer.
  • fleqi n. Pops s[0] and pushes (s[0] £ n), where n is a "float" heap offset pointer.

5  Arithmetic Operators

We divide our discussion of arithmetic operators by the type of arguments they take. All instructions increment pc afterwards.

5.1  Integer/Float Operators

  1. add. Pops s[0] and s[1] and pushes (s[1] + s[0]).
  2. addi n. Pops s[0] and pushes (s[0] + n), where n is an "integer" constant.
  3. faddi n. Pops s[0] and pushes (s[0] + n), where n is a "float" heap offset pointer.
  4. sub. Pops s[0] and s[1] and pushes (s[1] - s[0]).
  5. subi n. Pops s[0] and pushes (s[0] - n), where n is an "integer" constant.
  6. fsubi n. Pops s[0] and pushes (s[0] - n), where n is a "float" heap offset pointer.
  7. mult. Pops s[0] and s[1] and pushes (s[1] * s[0]).
  8. multi n. Pops s[0] and pushes (s[0] * n), where n is an "integer" constant.
  9. fmuli n. Pops s[0] and pushes (s[0] * n), where n is a "float" heap offset pointer.
  10. div. Pops s[0] and s[1] and pushes (s[1] / s[0]).
  11. divi n. Pops s[0] and pushes (s[0] / n), where n is an "integer" constant.
  12. fdivi n. Pops s[0] and pushes (s[0] / n), where n is a "float" heap offset pointer.

5.2  Integer-only Operators

  1. mod. Pops s[0] and s[1] and pushes (s[1] mod s[0]).
  2. modi n. Pops s[0] and pushes (s[0] mod n).
  3. neg. Pops s[0] and pushes (0 - s[0]).
  4. not. Pops s[0], pushes 1 if (s[0] = 0), 0 otherwise.
  5. lnot. Pops s[0], and pushes ( s[0]) (bitwise negation).
  6. and. Pops s[0] and s[1] and pushes (s[1] & s[0]) (bitwise and).
  7. andi n. Pops s[0] and pushes (s[0] & n).
  8. or. Pops s[0] and s[1] and pushes (s[1] | s[0]) (bitwise or).
  9. ori n. Pops s[0] and pushes (s[0] | n).
  10. lshl. Pops s[0] and s[1] and pushes (s[1] << s[0]) (left shift logical).
  11. lshli. Pops s[0] and pushes (s[0] << n).
  12. rshl. Pops s[0] and s[1] and pushes (s[1] >> s[0]) (right shift logical).
  13. rshli. Pops s[0] and pushes (s[0] >> n).
  14. rsha. Pops s[0] and s[1] and pushes (s[1] >> > s[0]) (right shift arithmetic).
  15. rshai. Pops s[0] and pushes (s[0] >> > n).
  16. xor. Pops s[0] and s[1] and pushes (s[1] xor s[0]).
  17. xori n. Pops s[0] and pushes (s[0] xor n).

5.3  Address operators

  1. snet. Pops s[0] and s[1]. Pushes the subnet address computed by using the value pointed to by s[0] as an IPv4 address and the value pointed to by s[1] as a subnet mask.
  2. sneti n. Pops s[0] and pushes the subnet address computed by using the value pointed to by s[0] as an IPv4 address and the value pointed to by interpreting n as an "address" heap offset pointer as a subnet mask.
  3. bcast n. Pops s[0] and s[1]. Pushes a broadcast address computed by using the value pointed to by s[0] as an IPv4 address and the value pointed to by s[1] as a subnet mask.
  4. bcasti n. Pops s[0] and pushes the broadcast address computed by using the value pointed to by s[0] as an IPv4 address and the value pointed to by interpreting n as an "address" heap offset pointer as a subnet mask.

6  Environment Query Instructions

All environment query instructions also increment pc afterwards.
  • isx. Pushes a 1 onto the stack if s[0] is an exception value, 0 otherwise. Note that s[0] is not popped from the stack.
  • getrb. Pushes the current packet's resource bound count onto the stack.
  • getsrc. Pushes a copy of the packet's source address header field onto the stack.
  • getdst. Pushes a copy of the packet's destination address header field onto the stack.
  • getspt. Pushes a copy of the packet's source port header field onto the stack.
  • here. Pushes a copy of one of the current node's addresses onto the stack.
  • ishere. Pops s[0], and if it is one of the current node's addresses, pushes a 1, else pushes a 0.
  • route. Pops the address in s[0], and pushes the address of the next hop towards that address.
  • rtdev. Pops the address in s[0], pushes the address of the next hop towards that address, then pushes the number of the corresponding outgoing interface.

7  Networking Instructions

  • send. Pops s[0], s[1], s[2], and s[3]. Sends a new packet with destination address s[0], resource bound s[1], copies of the top s[3] stack values (after popping s[0-3] above), and entry point s[3]. If s[2] is -1, then the entire stack is taken (again, after popping s[0-3] above). All other header fields for the new packet are inherited from the current packet. The current packet's resource bound is decremented by s[1]. Finally, pc is incremented.
  • dsend. Identical to send, with exception of the transfer method. dsend sends a packet directly to the final destination, while send uses intermediate SNAP hosts to forward itself.
  • hop. Pops s[0], s[1], s[2], and s[3]. Sends a new packet with destination address s[0] (where s[0] is one of the current node's neighbors), resource bound s[1], copies of the top s[3] stack values (after popping s[0-3] above), and entry point s[3]. If s[2] is -1, then the entire stack is taken (again, after popping s[0-3] above). All other header fields for the new packet are inherited from the current packet. The current packet's resource bound is decremented by s[1]. Finally, pc is incremented.
  • forw. If the packet's destination address is an address of the current node, simply increments pc. Else, sends a copy of the current packet towards the destination address and then terminates the current packet's execution. forw is equivalent to the following sequence of instructions: 
        getdst             ; find destination of packet
    ishere             ; are we there?
    bne      nosend-pc ; if so, fall through
    getep              ; same entry point as current packet
    pint     -1        ; take all the current stack
    getrb              ; use all remaining resource bound
    getdst             ; use same destination address
    send               ; send packet
    exit
  nosend:
    ...
  • dforw. Identical to forw, with exception of the transfer method. dforw sends a packet directly to the final destination, while forw uses intermediate SNAP hosts to forward itself.
  • forwto. Pops s[0]. If s[0] is one of the current node's addresses, simply increments pc. Else, sends a copy of the current packet but with destination address s[0] and then terminates the current packet's execution.
  • dforwto. Identical to forwto, with exception of the transfer method. dforwto sends a packet directly to the final destination, while forwto uses intermediate SNAP hosts to forward itself.
  • demux. Pops s[0] and s[1] and delivers the string indicated by the heap offset pointer s[1] to the application port number s[0]. Then the current packet terminates.
  • demuxi n. Pops s[0] and delivers the string indicated by the heap offset pointer s[0] to the application port number n. Then the current packet terminates.

8  Debugging Instructions

  • print. Causes s[0] to be printed to the system log, then advances pc.

9  Service Interface Instructions

  • calls n. Invokes the node-resident service named by the string pointed to by the heap offset pointer n. Further behavior is service-dependent.