NAME

mig - message interface generator for nesC

SYNOPSIS

mig [any ncc option] [-o output-file] [-java-classname=full-class-name] [-java-extends=class-name] tool msg-format-file message-type

DESCRIPTION

mig is a tool to generate code that processes TinyOS messages. The tool argument specifies what tool should be generated, the msg-format-file specifies your application's top-level nesC file, and the message-type specifies the C type of the message you wish to process. The C type must be defined with `struct message-type' or `union message-type' in a .h file which your nesC application `includes'. If your .h file defining the message type does not depend on any other files, then you can specify the .h file directly as the msg-format-file.

If you also need access to some constants from your nesC application, please consult the ncg man page.

If an enum constant named AM_message_type (with message_type capitalized) is found, then the value of that constant is assumed to be the active message type for message-type.

Currently there is only one tool, java, which generates a java class that encodes and decodes messages. The -java-* options are specific to this tool. It is described below.

-o output-file

specify the file in which to output the generated code.

mig works by invoking ncc. It will generally be necessary to pass some options through to ncc so that your file can be compiled. Some commonly necessary options are:

-target=known-tinyos-platform

specify the target architecture of your TinyOS application which is generating or receiving messages. So, e.g., if compiling your application for tossim specify -target=pc. The default target is ncc's default target.

-I dir

specify an additional search directory for nesC components.

-board=known-tinyos-sensorboard

specify one (or more) sensor boards. This effects the search path and preprocessor symbols (and may therefore be necessary when feeding a file to mig).

JAVA TOOL

This tool generates a java class to encode or decode a TinyOS packet, basing itself on the net.tinyos.message infrastructure. For each field fname of structure message-type, there are the following methods (the bit offset and size methods are useful for structures containing bitfields):

• get_fname: get field's value
• set_fname: set field's value
• offsetBits_fname: return bit offset of field in message-type
• offset_fname: return byte offset of field in message-type
• sizeBits_fname: return size in bits of field (not for arrays)
• size_fname: return size in bytes of field (not for arrays) (absent if fname is a bitfield)
• isSigned_fname: return true if fname is of a signed type
• isArray_fname: return true if fname is an array

Embedded structures in message-type are expanded, using _ to separate the structure name and its fields.

A number of extra methods are present for fields that are arrays:

• getElement_fname: get an element of the array
• setElement_fname: set an element of the array
• elementSize_fname: return size in bytes of array elements
• elementSizeBits_fname: return size in bits of array elements
• numDimensions_fname: return number of dimensions of the array
• numElements_fname: return number of elements of the array for a given dimension (left-most dimension is numbered 0) - the dimension is optional for 1-dimensional arrays
• totalSize_fname: return size in bytes of the array (absent if the array is variable-size)
• totalSizeBits_fname: return size in bits of the array (absent if the array is variable-size)

If the array is 1-dimensional and the elements are one byte, then the following methods exist:

getString_fname: build a Java string from the array assuming it contains a C-style null-terminated string

setString_fname: set the array to a C-style null-terminated string given a java string

The getElement_..., setElement_...,offset_... and offsetBits_... methods take one argument per array dimension. These methods report errors if the array index is out of bounds. If an array has a maximum size of 0, mig assumes it represents a variable-size array and does not check the corresponding array index. The data for a message is stored in an array, with explicit base and length information. The constructors can either allocate this array, receive it as an explicit argument or extract if from another message. The base and length can also be optionally passed to these constructors.

The optional length argument overrides the default size of sizeof(message-type); this is useful for variable-size messages. The use of an explicit base is helpful for messages embedded in other messages.

The generated class also has an amType() method which returns the message's active message type, or -1 if no AM_message_type constant was found.

The java tool accepts the following options:

-java-classname=full-class-name

this option is required and specifies the package and name of the generated class. If the full-class-name has no '.', then no package directive is included in the output.

-java-extends=class-name:

specify the class the generated class will extend. The default is net.tinyos.message.Message.

EXAMPLE

APPDIR=`ncc -print-tosdir`/../apps/Ident
mig java -I $APPDIR -java-classname=net.tinyos.ident.IdentMsg $APPDIR/App.nc IdentMsg -o IdentMsg.java

ERRORS

mig reports an error if ncc cannot compile msg-format-file, if message-type isn't found or if it contains pointers.

SEE ALSO

ncc ncg