[Tinyos-commits] CVS: tinyos-1.x/tos/lib/VM/languages/motlle/doc
tinyscheme.txt, 1.1, 1.2
David Gay
idgay at users.sourceforge.net
Thu Oct 27 20:21:55 PDT 2005
Update of /cvsroot/tinyos/tinyos-1.x/tos/lib/VM/languages/motlle/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20504
Modified Files:
tinyscheme.txt
Log Message:
mostly complete
Index: tinyscheme.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/tos/lib/VM/languages/motlle/doc/tinyscheme.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** tinyscheme.txt 26 Oct 2005 00:28:27 -0000 1.1
--- tinyscheme.txt 28 Oct 2005 03:21:53 -0000 1.2
***************
*** 35,40 ****
As this examples shows, TinyScheme uses the standard Mate handlers and
! function libraries (in this case, the timer0 handler and settimer0, led
! functions)
The current version of TinyScheme only supports the pc (tossim), mica2 and
--- 35,40 ----
As this examples shows, TinyScheme uses the standard Mate handlers and
! procedure libraries (in this case, the timer0 handler and settimer0, led
! procedures)
The current version of TinyScheme only supports the pc (tossim), mica2 and
***************
*** 75,82 ****
# Use the TinyScheme language
<LANGUAGE NAME="TinyScheme">
! # Load the basic TinyScheme functions
<LOAD FILE="../mate/runtime/sgen/intfns.vmsf">
! # Here is where you add VM-specific contexts and functions, either
# from Mate's library (led, id, the mica sensorboard) or from TinyScheme's
# (the commfns.vmsf file, which contains single-hop communication
--- 75,82 ----
# Use the TinyScheme language
<LANGUAGE NAME="TinyScheme">
! # Load the basic TinyScheme procedures
<LOAD FILE="../mate/runtime/sgen/intfns.vmsf">
! # Here is where you add VM-specific contexts and procedures, either
# from Mate's library (led, id, the mica sensorboard) or from TinyScheme's
# (the commfns.vmsf file, which contains single-hop communication
***************
*** 96,101 ****
like a usual TinyOS program.
! Note that TinyScheme library functions are found in directonies named sgen,
! while motlle library functions are found in directonies named gen.
2) Running TinyScheme programs
--- 96,129 ----
like a usual TinyOS program.
! Note that TinyScheme library procedures are found in directories named sgen,
! while motlle library functions are found in directories named gen.
!
! 1.1 Building a VM with floating-point support
! ---------------------------------------------
!
! The default scheme.vmsf configuration given above has 15-bit integers only.
! If you replace
! <SEARCH PATH="../mate/rep-16">
! by
! <SEARCH PATH="../mate/rep-float">
! and
! <LOAD FILE="../mate/runtime/sgen/intfns.vmsf">
! by
! <LOAD FILE="../mate/runtime/sgen/floatfns.vmsf">
! in your .vmsf file, you get 16-bit integers and 32-bit floating-point
! numbers, at the cost of approximately double RAM usage for your
! data structures.
!
! Note that / (real division) is only available if you have a floating-point
! VM. If you use rep-16, you get quotient (integer division) but not /.
!
! Finally, by default, transcendental (sin, cos, tan, etc) and other
! miscellaneous (sqrt, expt) procedures are not included. If you want all of
! these, add
! <LOAD FILE="../mate/runtime/sgen/transcendentalfns.vmsf">
! to your .vmsf file. Or you can include these procedures individually by
! adding
! <FUNCTION name=mXXX>
! lines to your .vmsf file, where XXX=sin, cos, etc.
2) Running TinyScheme programs
***************
*** 125,131 ****
The major differences between TinyScheme and Scheme are:
- - there is no tail-recursion-elimination support
- => don't write recursive loops, especially as motes have no RAM ;-)
- use do
- named let, quasiquote and macros are not available
- there is no call-with-current-continuation and no support for delayed
--- 153,156 ----
***************
*** 134,152 ****
types
- all input/output and character and most string procedures are missing
! - numbers are integers and, optionally 32-bit floats; the handling of
! numbers doesn't quite match the Scheme standard
- equal?, member, assoc are not available
! In more detail, and matching the structure of the "Revised^5 Report on
! the Algorithmic Language Scheme":
! 3.2 Disjointness of Types
! Character, boolean and port types do not exist.
! 3.5 Proper tail recursion
! -- is not available
4.1.4 Procedures
--- 159,302 ----
types
- all input/output and character and most string procedures are missing
! - numbers are 15-bit integers or 16-bit integers and 32-bit floats
! (see Section 1.1 above)
! - the handling of numbers doesn't quite match the Scheme standard
- equal?, member, assoc are not available
+ See Appendix A for more details on the differences between TinyScheme
+ and Scheme, and Appendix B for a list of standard Scheme procedures
+ present, absent or modified in TinyScheme.
! TinyScheme also includes a few extensions:
! - bitwise operations are supported:
! (| k1 ...): bit-wise or of its integer arguments
! (& k1 ...): bit-wise and of its integer arguments
! (^ k1 ...): bit-wise xor of its integer arguments
! - some vector, string and list operations are unified:
! (any-ref x k): applies to vectors, lists, strings
! (any-set! x1 k x2): applies to vectors, lists (sets the k-1th car), strings
! map, for-each, and length's arguments can be lists, vectors or strings
! - a few miscellaneous procedures:
! (error k): causes error k
! (garbage_collect): does a garbage collection
!
! 4) Mote library
! ===============
!
! As mentioned above, TinyScheme can use standard Mate librarires such as sensor
! access. It also currently comes with its own set of mote-specific procedures
! (some of these will be merged with the standard Mate libraries in future
! releases). The only documented library at this point is the communications
! library.
!
! 4.1 Using Mate libraries
! ------------------------
!
! To use a Mate procedure or context, you can just include it in your .vmsf
! file with
! <FUNCTION NAME=...>
! and
! <CONTEXT NAME=...>
!
! At this point, only procedures taking integer arguments, and those returning
! integer or sensor values will work with TinyScheme (in particular, procedures
! relating to Mate buffers cannot be used). Mate sensor values become integers
! in TinyScheme.
!
! 4.2 Communication procedures
! ----------------------------
!
! To include the communications library in a VM, add
! <LOAD FILE="../matelib/sgen/commfns.vmsf">
! to your .vmsf file (scheme.vmsf already contains this library).
!
! This library supports single-hop, broadcast and serial port communication.
! It includes three procedures and one context:
!
! (send k s) --> b
! Send packet s (a string) to address k, returning success/failure.
! if k is uart-addr, sends to the serial port
! if k is bcast-addr, broadcasts the message
! otherwise, the packet is sent to mote with id k
!
! (encode v) --> s
! Encode a vector as a string. Produces a string which is the concatenation
! of the elements of v, each encoded as follows:
! k: encode as 2 little-endian bytes
! n: encode as a 4-byte float
! s: encode n-char string as n identical bytes
! k . x: encode x as usual, pad (w/ 0s) or truncate (lowest significant
! bytes) to k bytes
! ignored for floats (always encoded as 4 bytes)
!
! example: (encode (vector (1 . 33) "aa")) --> "!aa"
!
!
! (decode s v) --> v
! Decode string s into v, and return v.
! Each element x of v is replaced by a value decoded from s according
! to rules which depend on the value of x:
! If x = 1, decode 1 byte from s as an unsigned number
! If x = 2, decode 2 bytes from s as an unsigned little-endian number
! If x = -1, decode 1 byte from s as a signed number
! If x = -2, decode 2 bytes from s as a signed little-endian number
! If x is any floating point number, decode 4 bytes from s as a
! floating point number
! If x is a string of length k, overwrite x with k bytes from s
!
! example: (decode "!aa" (vector 1 (make-string 2))) --> #(33 "aa")
!
! The context is called receive, and is executed when a message sent via
! 'send' from another mote is received. To access the message, you use the
! (received-msg) --> s
! Return received message
! procedure.
!
! The messages sent and received by this library use active message id 42.
!
! For example, in the oscillosope application, mote 0 forwards all received
! messages to the serial port:
! (define (receive)
! (if (zero? (id))
! (send uart-addr (received_msg))))
!
! Messages are typically sent using encode:
! // send a 4-byte message with the values of x and y
! (send bcast-addr (encode (vector x y)))
!
! This message could be decoded like this:
! (define (receive)
! (let ((decoded (decode (received-msg) (vector 2 2))))
! ;; (vector-ref decoded 0) is now the x value sent,
! ;; and (vector-ref decoded 1) the y value
! ...))
!
! The oscilloscope.ts example contains a more complex use:
! (define readings (make-vector 10))
! ...
! (send bcast-addr (encode (vector id() current 0 (encode readings))))
!
! This creates a 26 byte message whose format is:
! bytes 0, 1: the sender's node id
! bytes 2, 3: the value of current
! bytes 4, 5: 0
! bytes 6-25: the 10 elements of readings, encoded with 2 bytes per number
! This is the format expected by the net.tinyos.oscope.oscilloscope application.
!
!
! Appendix A: Changes from R5RS
! =============================
!
! The following summarise the differences between TinyScheme and Scheme,
! following the structure of the "Revised^5 Report on the Algorithmic
! Language Scheme":
!
! 3.2 Disjointness of Types
!
! Character, boolean and port types do not exist.
4.1.4 Procedures
***************
*** 158,166 ****
supported.
- 4.1.5 Conditionals
-
- The result of (if <test> <consequent>) is unspecfied even when <consequent>
- is evaluated.
-
4.2.4 Iteration
--- 308,311 ----
***************
*** 185,189 ****
6.1 Equivalence predicates
! eqv? and eq? behave identically
-- equal? is not available
--- 330,334 ----
6.1 Equivalence predicates
! -- eqv? and eq? behave identically
-- equal? is not available
***************
*** 214,218 ****
6.3.2 Pairs and lists
! c[ad]*r are only available up to three a+d's (i.e., the four car/cdr forms
are absent).
--- 359,363 ----
6.3.2 Pairs and lists
! -- c[ad]*r are only available up to three a+d's (i.e., the four car/cdr forms
are absent).
***************
*** 230,242 ****
6.3.5 Strings
! The string lexical syntax is that of C.
!
! -- the string comparison and substring functions are not available
6.4 Control features
! apply is changed to
! (apply proc vector)
! Calls proc with the values in vector as the actual arguments.
-- force, call-with-current-continuation, values, call-with-values,
--- 375,385 ----
6.3.5 Strings
! -- the string comparison and substring procedures are not available
6.4 Control features
! -- apply takes a single vector argument:
! (apply proc v)
! Calls proc with the values in vector as the actual arguments.
-- force, call-with-current-continuation, values, call-with-values,
***************
*** 245,253 ****
6.5 Eval
! -- eval and its related functions are not available
6.6 Input and output
! -- Scheme's I/O functions are not available. See the description of the
motlle/TinyScheme communication library below.
--- 388,396 ----
6.5 Eval
! -- eval and its related procedures are not available
6.6 Input and output
! -- Scheme's I/O procedures are not available. See the description of the
motlle/TinyScheme communication library below.
***************
*** 255,401 ****
The lexical changes from Scheme (already mentioned above) are:
- - strings follow the C syntax
- numbers follow C syntax, except that the #b, #o, #d and #x radix
specifiers are supported
! Additional features
! -------------------
!
! Bitwise operations are supported:
! (| n1 ...): bit-wise or of its integer arguments
! (& n1 ...): bit-wise and of its integer arguments
! (^ n1 ...): bit-wise xor of its integer arguments
!
! Some vector, string and list operations are unified:
! (any-ref x n): applies to vectors, lists, strings
! (any-set! x1 n x2): applies to vectors, lists (sets the n-1th car), strings
! map, for-each, length, reverse and append's arguments can be lists,
! vectors or strings
!
! A few miscellaneous functions are also available:
! error: i -> . Causes error i
! garbage_collect: -> . Does a garbage collection
!
!
! 4) Mote library
! ===============
!
! As mentioned above, TinyScheme can use standard Mate librarires such as sensor
! access. It also currently comes with its own set of mote-specific functions
! (some of these will be merged with the standard Mate libraries in future
! releases). The only documented library at this point is the communications
! library.
!
! This description
! includes a function signature of the form "X1 X2 X3 ... -> Y.",
! where the Xi's describe the number and type of arguments, and Y
! the type of the result, using the following conventions:
! x, y, x1, y1, x2, y2, ... : a value of any type
! n, n1, n2, ... : a number (int or float)
! i, i1, i2, ... : an integer
! r, r1, r2, ... : a float (real number)
! b, b1, b2, ... : a boolean value (0 = FALSE, everything else = TRUE)
! s, s1, s2, ... : a string
! fn, fn1, ... : a function (or closure as it is sometimes known)
! l, l1, l2, ... : a list
! v, v1, v2, ... : a vector
!
! If Y is absent, the function has no (useful) result.
!
! 4.1 Using Mate libraries
! ------------------------
!
! To use a Mate function or context, you can just include it in your .vmsf
! file with
! <FUNCTION NAME=...>
! and
! <CONTEXT NAME=...>
!
! At this point, only functions take integer arguments, and those returning
! integer or sensor values will work with TinyScheme (in particular, functions
! relating to Mate buffers cannot be used).
!
! 4.2 Communication functions
! ---------------------------
!
! To include the communications library in a VM, add
! <LOAD FILE="../matelib/sgen/commfns.vmsf">
! to your .vmsf file (base.vmsf already contains this library).
!
! This library supports single-hop, broadcast and serial port communication.
! It includes three functions and one context:
!
! send: i s -> b. Send packet s to address i, returning success/failure.
! if i is uart_addr, sends to the serial port
! if i is bcast_addr, broadcasts the message
!
! encode: v -> s. Encode a vector as a string. Produces a string which
! is the concatenation of the elements of v, each encoded as follows:
! i: encode as 2 little-endian bytes
! f: encode as 4-byte float
! s: encode n-char string as n identical bytes
! i . x: encode x as usual, pad (w/ 0s) or truncate to n bytes
! ignored for floats (always encoded as 4 bytes)
!
!
! decode: s v -> v. Decode string s into v, based on the decoding rules
! specified in v. Elements of v should be:
! i: 1->1-byte unsigned, 2->2-byte unsigned,
! -1->1-byte signed, -2->2-byte signed
! f: decode a 4-byte float
! s2: overwrite s2 with chars from s
!
! The context is called receive, and is executed when a message sent via
! 'send' from another mote is received. To access the message, you use the
! received_msg: -> s. Return received message
! function.
!
! The messages sent and received by this library use active message id 42.
!
! For example, in the oscillosope application, mote 0 forwards all received
! messages to the serial port:
! any receive() {
! if (id() == 0)
! send(uart_addr, received_msg());
! }
!
! Messages are typically sent using encode:
! // send a 4-byte message with the values of x and y
! send(bcast_addr, encode(vector(x, y)));
!
! This message could be decoded like this:
! any receive() {
! any decoded = decode(received_msg(), vector(2, 2));
! // decoded[0] is now the x value sent, and decode[1] the y value
! }
!
! The oscilloscope.mt example contains a more complex use:
! any readings = make_vector(10);
! ...
! send(bcast_addr, encode(vector(id(), current, 0, encode(readings))));
!
! This creates a 26 byte message whose format is:
! bytes 0, 1: the sender's node id
! bytes 2, 3: the value of current
! bytes 4, 5: 0
! bytes 6-25: the 10 elements of readings, encoded with 2 bytes per number
! This is the format expected by the net.tinyos.oscope.oscilloscope application.
!
!
! XXX vmsf configuration
!
! The default scheme.vmsf configuration given above has 15-bit integers only.
!
! If you replace
! <SEARCH PATH="../mate/rep-16">
! by
! <SEARCH PATH="../mate/rep-float">
! and
! <LOAD FILE="../mate/runtime/gen/intfns.vmsf">
! by
! <LOAD FILE="../mate/runtime/gen/floatfns.vmsf">
! in your .vmsf file, you get 16-bit integers and 32-bit floating-point
! numbers.
!
! Note that / (real division) is only available if you have a floating-point
! VM. If you use rep-16, you get quotient (integer division) but not /.
--- 398,404 ----
The lexical changes from Scheme (already mentioned above) are:
- numbers follow C syntax, except that the #b, #o, #d and #x radix
specifiers are supported
! Appendix B: Scheme procedures in TinyScheme
! ===========================================
More information about the Tinyos-commits
mailing list