mate-manual.tex

无线通信的主要编程软件,是无线通信工作人员的必备工具,关天相关教程我会在后续传上.

\begin{verbatim}
    OP<width><name><operand>.nc
\end{verbatim}
}

Width and operand are both numbers. Width specifies how many bytes
wide the instruction is. If no width is specified, the default is
one. Operand specifies how many bytes of embedded operand there
are. If no operand is specified, the default is zero. Note that, after
considering width and operand, the instruction must have an opcode in
its first byte. That is, the instruction cannot be two bytes wide and
have no embedded operand; as the \mate scheduler dispatches on the
first byte of the opcode, it would not be able to distinguish this
instruction from other ones.

Here are a few examples:

\vspace{0.1in}
{\scriptsize
\begin{tabular}{|l|c|c|c|l|} \hline
Component & Width & Name  & Embedded & Description\\ \hline
OPrand    &  1    & rand  & 0        & Generates a random number\\
OPpushc6  &  1    & pushc & 6        & Push a constant onto the stack\\
OP2jumps10&  2    & jumps & 10       & Jump to a 10-bit address\\ \hline
\end{tabular}
}
\vspace{0.1in}

Functions are always one byte wide and never have embedded
operands. In the above example, neither {\tt pushc} nor {\tt jumps}
are available as library functions; they are actually primitives that
compose part of what TinyScript compiles to.

\subsection{Primitives}

Primitives are operation components that a language compiles to. They
cannot be included in a VM in the same way functions can: they have no
ODF which VMBuilder can use to include them. The only way to include
them is to use a language that compiles to them. Operations such as
branches, memory access, and arithmetic are examples of \mate
primitives.

Primitives provide language storage abstractions, such as
variables. For example, TinyScript has the notion of sixteen variables
that are shared between all handlers, and eight variables which are
private to each handler. The operations {\tt getvar4} and {\tt
setvar4} implement the former, while the operations {\tt getlocal3}
and {\tt setlocal3} implement the latter.

The implementations of the two abstractions are very similar. A single
component implements {\tt getvar4} and {\tt setvar4}, providing two
{\tt MateBytecode} interfaces. Sixteen opcodes map to each instance of
{\tt MateBytecode}, for the four bits of embedded operand. The
component allocates sixteen shared variables in its frame.  To
determine which variable a program is accessing, the implementation
subtracts the executed opcode from the base opcode, Additionally, the
implementation checks that the program holds the lock to the shared
variable:

{\scriptsize
\begin{verbatim}
  MateStackVariable heap[16];

  command result_t Get.execute(uint8_t instr,
                               MateContext* context) {
    uint8_t arg = instr - OPgetvar4;
    uint8_t lock = varToLock(arg);
    if ((lock == 255) || !call Locks.isHeldBy(lock, context)) {
      call Error.error(context, MATE_ERROR_INVALID_ACCESS);
      return FAIL;
    }
    dbg(DBG_USR1, "VM (%i): Executing getvar (%i).\n", (int)context->which, (int
)arg);
    call Stacks.pushOperand(context, &heap[arg]);
    return SUCCESS;
  }
\end{verbatim}
}

{\tt getlocal3} and {\tt setlocal3} are similar, except there
are only eight variables, and there's no need to check locks. However,
the component that implements the two primitives has to allocate state
for each context:

{\scriptsize
\begin{verbatim}
  MateStackVariable vars[MATE_CONTEXT_NUM][NUM_VARS];

  command result_t Get.execute(uint8_t instr,
                               MateContext* context) {
    uint8_t arg = instr - OPgetlocal3;
    dbg(DBG_USR1, "VM (%i): OPgetlocal3 (%i).\n", (int)context->which, (int)arg)
;
    call Stacks.pushOperand(context, &vars[context->which][arg]);
    return SUCCESS;
  }
\end{verbatim}
}

Some primitives are more than one byte wide. For example, {\tt
OP2jumps10}, the basic branch instruction is two bytes wide. The {\tt
byteLength()} command of the {\tt MateBytecode} interface must return
the byte width of an instruction, so the scheduler knows how much to
increment the program counter by. {\tt It increments the program
counter before executing the instruction.} The component implementing
the primitive is responsible for getting the extra bytes. For example,
this is part of {\tt OP2jumps10M}:

{\scriptsize
\begin{verbatim}
  command uint8_t MateBytecode.byteLength() {return 2;}

  command result_t MateBytecode.execute(uint8_t instr,
                                            MateContext* context) {
    uint16_t addr = (instr - OP2jumps10) << 8;
    MateStackVariable* cond = call Stacks.popOperand(context);

    addr |= call Store.getOpcode[context->currentHandler](context->pc-1);
\end{verbatim}
}

It generates the 10-bit jump address by taking the bottom two bits of
the opcode and incorporating the next byte. Since the VM has already
incremented the program counter, the next byte is at {\tt context-$>$pc-1}.

The \mate tutorials briefly mention a requirement when using the \mate
operand stack. When a component pops operands off the stack with {\tt
popOperand}, the call returns a pointer to a stack variable. This is a
pointer into the stack data structure. If a component then pushes
something onto the stack, that push can modify the region of the stack
the pointer refers to. There are situations when it is safe to access
popped operands after pushes, however.

Elements on the operand stack have a fixed size. For example, a buffer
(which stores a pointer) is the same size as a value. An operand stack
is an array of operands and a stack pointer, which indicates the next
free element. Pushing something onto the stack fills the next free
element, and increments the stack pointer. Popping something off the
stack decrements the stack pointer, and returns a pointer to that
element. The following three snippets of pseudocode are examples of
the resulting behavior:

\begin{verbatim}
  op1 = pop();
  op2 = pop();
  push(4);   // op2 is now invalidated
  push(op2); // BUG, unless you want to copy the top of the operand stack

  op1 = pop();
  op2 = pop();
  push(op2);  // SAFE; returns op2 to operand stack
  push(op1);  // same as above

  op1 = pop();
  op2 = pop();
  push(op1); // invalidates op2, which is now the same as op1
  push(4);   // invalidates op1
\end{verbatim}


\section{Languages}
\label{sec:language}

A language is defined by the set of primitives it compiles to. A
LANGUAGE element in a VM specification file causes VMBuilder to search
for a language description file ({\tt .ldf}). An LDF must have a
LANGUAGE element with the NAME and DESC tags. Additionally, it should
have a series of PRIMITIVE elements.  PRIMITIVE elements have one
required tag, OPCODE. They also have the optional field LOCKS, which
specifies if the primitive encapsulates a shared resources which the
concurrency manager must arbitrate access to. For example, this is a
snippet of {\tt tscript.ldf}:

{\scriptsize
\begin{verbatim}
<LANGUAGE name="TinyScript" desc="A simple, BASIC-like language.">
<PRIMITIVE opcode="halt">
<PRIMITIVE opcode="2pushc10">
<PRIMITIVE opcode="2jumps10">
<PRIMITIVE opcode="getlocal3">
<PRIMITIVE opcode="setlocal3">
<PRIMITIVE opcode="bpush3" locks=true>
<PRIMITIVE opcode="getvar4" locks=true>
<PRIMITIVE opcode="setvar4" locks=true>
<PRIMITIVE opcode="or">
<PRIMITIVE opcode="and">
<PRIMITIVE opcode="not">
<PRIMITIVE opcode="eq">
<PRIMITIVE opcode="gte">
<PRIMITIVE opcode="gt">
\end{verbatim}
}

VMBuilder interprets PRIMITIVE elements in a language file; it does
not load any additional files in response to them. It uses the OPCODE
tag to refer to the primitive's component when wiring the instruction
set. If the LOCKS tag exists (the value is ignored), the VMBuilder
also has MateTopLevel wire the primitive component to the concurrency
manager.

The LANGUAGE element has a single optional tag,
FIRSTORDERFUNCTIONS. If the LANGAUGE element has this tag (whose value
is ignored), the VMBuilder includes support for first order
functions. It does so by wiring functions to the {\tt FunctionImpls}
interface of {\tt MateEngine} and generating a set of function
identifiers of the form fn\_name, where {\it name} is the name of the
function. These indentifiers are in an enum in {\tt MateConstants.h},
and can therefore can be accessed through the VM Java constants file.

\section{VM Options}

Tutorial 4 presents how to specify the language, events, and functions
that a \mate VM supports. More advanced users can also modify various
VM options. These options can be set with one or more {\tt OPTION}
elements. The supported options are:

\vspace{1ex}
{\scriptsize
\begin{tabular}{|l|l|l|}\hline
Name  & Type & Description \\ \hline
OPDEPTH      & integer & Sets the maximum depth of a context operand stack. \\
             &         & The default value is 8.\\
             &         & Changing this value will change the maximum length of  TinyScript statements.\\
             &         & Larger values increase RAM utilization.\\\hline
BUF\_LEN      & integer & Sets the maximum size of a data buffer.\\
             &         & The default value is 10.\\
	     &         & Larger values will allow you to manage larger buffers. \\
             &         & However, this will increase the RAM allocated for each buffer.\\
             &         & If made much larger, it increase packet size, {\bf greatly} increasing RAM utilization.\\
             &         & Decreasing this value will not reduce the RAM utilization of message buffers.\\ \hline
CAPSULE\_SIZE & integer & Sets the maximum size of a code capsule.\\
             &         & The default value is 128.\\
             &         & Changing this value will affect how large a program you can write.\\
             &         & Larger values increase RAM utilization.\\ \hline
\end{tabular}
}
\vspace{1ex}

For example, to change some options, you could add either a single element

\begin{verbatim}
<OPTION OPDEPTH=6 CAPSULE_SIZE=64>
\end{verbatim}

or multiple elements

\begin{verbatim}
<OPTION OPDEPTH=6>
<OPTION CAPSULE_SIZE=64>
\end{verbatim}



\section{Java Toolchain}

When VMBuilder generates a Makefile for a \mate VM, it includes rules
for building a few Java classes that the \mate toolchain uses. The
foremost of these is a constants class, which it generates with the
{\tt ncg} tool. This class contains all of the mappings between
handler names and IDs, context names and IDs, instructions and their
bytecodes, error codes, and data types. It also generates a set of
message classes, for interacting with a VM.

\subsection{Constants Class}

Every VM has a constants class. The name of the class is VM-specific,
to prevent users from accidentally loading the wrong constants
file. For example, the Bombilla constants class name is
BombillaConstants. The class contains all of the constants contained
in MateConstants.h as public variables. The \mate toolchain has a
class, named {\tt net.tinyos.script.ConstantMapper}, for easily
accessing these variables through the Java reflection API.

The constructor to ConstantMapper takes two arguments, a class name
and a prefix. The prefix acts as a filter on the constants it
considers. For example, if you instantiate a ConstantMapper like so:

\begin{verbatim}
ConstantMapper map = new ConstantMapper("BombillaConstants", "OP");
\end{verbatim}

then all of its accessor functions will operate on the public fields
of a class named {\tt BombillaConstants} whose name begins with {\tt
OP}, in this case the instructions of the Bombilla VM.

ConstantMapper provides three basic methods for fetching constants:
{\tt codeToName()} {\tt nameToCode()}, and {\tt names()}. For example,
the TinyScript compiler takes a TinyScript program and produces
assembly code for it. The ScriptAssembler then takes each instruction
and determines its bytecode with the {\tt nameToCode()} method. In
contrast, when the Scripter displays a VM error, it reads the binary
values of the error condition, context, and handler, and produces
human-readable names for them with the {\tt codeToName()}
method. Finally, the ScripterGUI determines the set of valid handlers
one can write scripts for by using {\tt names()}, then translates
those names to IDs with {\tt nameToCode()}.

Obtaining the name of a VM's constants file requires reading in the VM
description file that VMBuilder produces. Every VM application
directory has a file named {\tt vm.vmdf}, which describes the VM. The
Java class {\tt net.tinyos.script.Configuration} automatically loads
and parses VM descroption files, extracting the important fields. It
takes the path to the file as an argument in its constructor. This is
why you must run Scripter from the VM application directory: it
instantiates a Configuration with the name {\tt vm.vmdf}. This will
also ensure that the Java loader will find the right constants
file. Configuration has accessor functions to get at the important
instances of ConstantMapper, such as capsule names, opcodes, and error
codes. You can also get the constant class name, if you need to build
other ConstantMappers, with the {\tt constantClassName()} method.


\subsection{Message Classes}

By default, the Makefile VMBuilder generates builds several Java
message classes. These classes are all built in the {\tt vm\_specific}
subdirectory. They allow Scripters to generate the proper packets for
transmitting code to a mote, as well as read mote data output.

The first class, code transmission, has three kinds of messages: {\tt
CapsuleMsg}, {\tt CapsuleStatusMsg}, and {\tt
CapsuleChunkMsg}. CapsuleMsg is for generating a full \mate capsule
that matches the on-mote memory layout. CapsuleStatusMsg is so tools
can monitor download status as it occurs. CapsuleChunkMsg is so the
Scripters can send the chunks that make up a capsule along the serial
port to a mote.

The second class, data transmission, has three kinds of messages: {\tt
BufferBCastMsg}, {\tt BufferUARTMsg}, and {\tt MultiHopMsg}. The first
two are the format the {\tt bcast} and {\tt uart} functions send: a
\mate data buffer in the payload of a packet. MultiHopMsg is for
packets sent through a multihop routing layer: it includes multihop
header fields, as well as the \mate buffer. The tool {\tt
net.tinyos.script.VMBufferReader} listens for all three of these kinds
of packets and outputs information on them. It is a good place to
start if you want to read data from \mate into a Java application.


\section{Conclusion}

\mate is under active development. Bugs, questions, contexts, and
functions can be sent to Phil Levis ({\tt [e-mail]}).

\end{document}