[Tutorial Home] [Lesson 1] [Lesson 2] [Lesson 3] [Lesson 4] [Lesson 5] [Lesson 6]

Lesson 4: Building a VM

Last modified: Thu Aug 26 18:44:56 PDT 2004

In prior lessons, you used the standard VM that the Maté release provides, Bombilla. In this lesson, you will learn how to build a new VM with handlers and functions that meet the needs of a particular application.

Introduction

So far, you have been using Bombilla, a stock VM that the Maté release includes. The Maté framework allows you to customize VMs by selecting the set of functions and handlers they support. By default, Bombilla includes all of the functions and handlers that are part of the standard release . In lesson 2, you may have had to change what sensor board Bombilla supported; this required changing the VM in a very limited way. Knowing how to build VMs will allow you to incorporate additonal handlers or functions that you or someone else writes. The lesson after this one, lesson 5, shows how to write new functions and handlers.

The VM Specification File

In lesson 1, you build Bombilla by running the VMBuilder application from the directory tos/liv/VM/samples:

java net.tinyos.script.VMBuilder bombilla.vmsf

bombilla.vmsf is a VM specification file (vmsf). It tells VMBuilder what handlers, functions, sensorboards and other options to include in the VM. Open tos/lib/VM/samples/bombilla.vmsf in an editor. The first line of the file should read:

<VM NAME="BombillaVM"
 DESC="A simple VM that includes a range of triggering events and functions."
 DIR="../../../../apps/Bombilla">

This is an example of an element; all Maté files (barring nesC code) are sequences of these XML-like elements. The name of an element is the first word after the opening <: the above example is a VM element. Elements have tags, which are key value pairs. The above VM element has three tags, NAME, DESC, and DIR. Element and tag names are case-insensitive; the above could alternatively be written as:

<vm name="BombillaVM"
 DESC="A simple VM that includes a range of triggering events and functions."
 dir="../../../../apps/Bombilla">

with no change to its meaning. The Maté toolchain only recognizes certain elements and tags. Unrecognized tags and elements are ignored. Although the names of the tags are case insensitive, often the values of the tags are case sensitive. For example, changing the case of directory names in the dir tag is significant.

Every VMSF must have a VM element with a NAME, DESC, and DIR tag. This is so VMBuilder knows what to name files associated with the VM and what directory in which to put them. The Bombilla DIR tag puts the VM in tinyos-1.x/tos/lib/VM/samples/../../../../apps/Bombilla, which is tinyos-1.x/apps/Bombilla.

After the VM element come four SEARCH elements:

<SEARCH PATH="../opcodes">
<SEARCH PATH="../contexts">
<SEARCH PATH="../languages">

SEARCH elements tell VMBuilder where to look for files. VMBuilder will search them in the order the file specifies them. PATH tags that have a relative path (like those above) are resolved from where VMBuilder is run, that is, tos/lib/VM/samples. PATH tags can also be absolute paths. Every VMSF should have the first three SEARCH elements (opcodes, contexts, languages), which is where all of the standard Maté files are.

The two lines of the file specify a sensorboard and what language to use (TinyScript). If you're using a Telos mote, it uses MicroScript instead (microscript):

<LOAD FILE="../sensorboards/micasb.vmsf">
<LANGUAGE NAME="tinyscript">

The LOAD element tells VMBuilder to load the file specified by the FILE tag and process the elements contained in it. In the above example, micasb.vmsf contains elements specifying what functions to support, and where to find the underlying TinyOS components. Using the LOAD element, you can write files containing libraries of functions, for example, which a VM can then include with a single element.

The LANGUAGE element tells VMBuilder what language to support. Currently, Maté only supports TinyScript, but we're currently working on also suppoting motlle, a scheme-like language. Every VM should have this element, if you want to be able to program with it.

A set of FUNCTION elements follows. These describe the set of functions the VM should include and provide to the programmer. For example, Bombilla has several functions for clearing, querying, and sorting buffers:

<FUNCTION NAME="bclear">
<FUNCTION NAME="bfull">
<FUNCTION NAME="bsize">
<FUNCTION NAME="bufsorta">
<FUNCTION NAME="bufsortd"> 
		    

The NAME tag is the name of the function; it refers to an opcode description file (.odf). The ODF file contains information on how many parameters the function takes and their types, whether it has a return value, and a brief description. Lesson 5 details how to introduce new functions by writing ODF files.

Finally, after the FUNCTION elements are the CONTEXT elements. These elements specify what software handlers the VM provides: each has its own execution context. Similar to FUNCTION elements, they have a single tag, NAME, which specifies a context description file (.cdf) that contains information on the handler. Bombilla includes six handlers:

<CONTEXT NAME="Trigger">
<CONTEXT NAME="Timer0">
<CONTEXT NAME="Timer1">
<CONTEXT NAME="Once">
<CONTEXT NAME="Reboot">
<CONTEXT NAME="Broadcast">
		    
Building a New VM

Now that you've seen the Bombilla specification file file, you'll write a description file for a new VM, named SimpleVM. First, open a file named simple.vmsf in the samples directory. The first line should be a VM element; write the following in the file:

<VM NAME="SimpleVM"
    DESC="A bare bones VM from tutorial 4."
    DIR="../../../../apps/SimpleVM">
		    

Next, include the standard Maté library directories with SEARCH elements, and TinyScript with a LANGUAGE element. If you want to support a sensor board, then also add an appropriate LOAD element.

<SEARCH PATH="../opcodes">
<SEARCH PATH="../contexts">
<SEARCH PATH="../languages">
<LANGUAGE NAME="tinyscript">

If you're using Telos motes, use MicroScript instead of TinyScript. SimpleVM has two handlers, Once and Timer0. Write the following in the file:

<CONTEXT NAME="Once">
<CONTEXT NAME="Timer0">

Finally, it supports only a few functions:

<FUNCTION NAME="rand">
<FUNCTION NAME="int">
<FUNCTION NAME="sleep">
<FUNCTION NAME="led">

Save and close the file. In the samples directory, run VMBuilder:

java net.tinyos.script.VMBuilder simple.vmsf
		    

Barring any typos in the specification file, this will generate all of the needed VM files in tinyos-1.x/apps/SimpleVM. Go to that directory and build the VM for your desired platform. You can install the VM and use the Scripter as you did before with Bombilla. If you use the GUI scripter, you'll see that SimpleVM, in addition to the functions you specified, has settimer0 as a function. Including Timer0 as a context automatically includes settimer0 as a function.

In a VM specification file, the LANGUAGE, CONTEXT, and FUNCTION elements all have a single tag, NAME. All of them tell VMBuilder to look for a description file in the search path. LANGUAGE looks for a language description file (.ldf), FUNCTION looks for an operation description file (.odf), and CONTEXT looks for a context description file (.cdf). VMBuilder reads the file, which contains information on the particular function, context, or language. The file naming is as follows:



Element Format File Name
Context <CONTEXT NAME=event> eventContext.cdf
Function <FUNCTION NAME=func> OPfunc.odf
Language <LANGUAGE NAME=lang> lang.ldf

The next two lessons describe how to write new functions and contexts, including their description files. Currently, Maté only supports TinyScript and its stripped down variant, MicroScript as languages.

The VMBuilder GUI

There is also a VMBuilder GUI, which you can use to browse available functions and contexts:

java net.tinyos.script.VMBuilder -gui -t=<lib/VM directory>
		    

In the above command, the lib/VM directory refers to the path to tinyos-1.x/tos/lib/VM. Specifying this at the command line allows the tool to automatically find ODFs and CDFs. The VMBuilder GUI cannot build VMs; it is only useful as a browsing tool. You should see a GUI like this:

Conclusion

This tutorial showed you how to create a new VM from existing functions and context. The next and final tutorial will show you how to write new functions and contexts.


< Previous Lesson | Next Lesson > | Top