Provided by: nescc_1.3.4-2_amd64 bug

NAME

       nescc-mig - message interface generator for nesC

SYNOPSIS

       nescc-mig [any nescc option] [tool-specific options]
                 [-o output-file] [-nescc=driver]
                 tool msg-format-file message-type

DESCRIPTION

       nescc-mig  is  a  tool to generate code to process nesC messages (which are specified by C
       types). The tool argument specifies  what  tool  should  be  generated,  the  message-type
       specifies  the  C  type of the message you wish to process and msg-format-file specifies a
       nesC file which uses that type. The message type must be defined with struct message-type,
       nx_struct message-type, union message-type, nx_union message-type.

       When  used with types whose layout is platform-dependent (i.e., not defined with nx_struct
       or nx_union), it is important to specify the  correct  nescc  target  architecture  option
       (-fnesc-target=...). If you are invoking nescc-mig indirectly via mig, you can use the ncc
       -target=...  option instead.

       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. If
       you need access to other constants from your nesC application, please consult  the  nescc-
       ncg man page.

       The  current  tools  are java, csharp, python and C, which generate java, C#, python and C
       code to encode and decode messages.

OPTIONS

       You can pass any nescc option, as well as

       -o output-file
              Specify the file in which to output the generated code.

       -nescc=driver
              Use driver instead of nescc to extract type layout information.   For  example,  if
              you  specify  -nescc=ncc,  you  can  use nescc-mig to extract type information from
              TinyOS applications (which are normally compiled with ncc).

       tool-specific options
              See below.

JAVA TOOL

       This tool generates a java class to encode or decode a nesC message, basing itself on  the
       net.tinyos.message infrastructure. It 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.

       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.

C# TOOL

       This  tool  generates  a  C#  class  to  encode  or  decode a nesC message. It accepts the
       following options:

       -csharp-classname=full-class-name
              This option is required and specifies the  namespace  and  name  of  the  generated
              class.  If  the full-class-name has no '.', then no namespace directive is included
              in the output.

       -csharp-extends=class-name
              Specify  the  class   the   generated   class   will   extend.   The   default   is
              tinyos.message.Message.

              The methods in the generated class are the same as for the Java tool.

PYTHON TOOL

       This  tool  generates  a  Python class to encode or decode a nesC message.  It accepts the
       following options:

       -python-classname=full-class-name
              This option is required and specifies the name of the generated class.

       -python-extends=class-name
              Specify  the  class   the   generated   class   will   extend.   The   default   is
              tinyos.message.Message.Message.

              The methods in the generated class are the same as for the Java tool.

C TOOL

       This  tool generates a C header file (.h) with constants describing the type's layout, and
       a C module (.c) with functions to get and set each field. You must pass the .h file's name
       to nescc-mig using -o.

       The C tool accepts the following option:

       -c-prefix=prefix
              This  option  specifies  the  prefix  to  attach  to  the  generated  constants and
              functions. If omitted, message-type is used.

       For each non-array field fname of structure  message-type,  the  following  functions  and
       constants are generated:

       *      prefix_fname_get(): get field's value

       *      prefix_fname_set(): get field's value

       *      prefix_fname_OFFSETBITS: bit offset of field

       *      prefix_fname_OFFSET: byte offset of field

       *      prefix_fname_SIZEBITS: size in bits of field

       *      prefix_fname_SIZE: size in bytes of field

       For  each  array  field  fname  of  structure  message-type,  the  following functions and
       constants are generated:

       *      prefix_fname_get(): get field's value

       *      prefix_fname_set(): get field's value

       *      prefix_fname_offsetbits(): bit offset of array element

       *      prefix_fname_offset(): byte offset of array element

       *      prefix_fname_ELEMENTSIZEBITS: size in bits of array element

       *      prefix_fname_ELEMENTSIZE: size in bytes of array element

       *      prefix_fname_NUMELEMENTS: number of elements in array  (absent  for  variable-sized
              arrays)

       *      prefix_fname_NUMELEMENTS_i: size of ith array dimension

       Embedded  structures  in message-type are expanded, using _ to separate the structure name
       and its fields. A field of an array of embedded structures is considered to be an array.

ERRORS

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

SEE ALSO

       The  generated code for the various tools refer to libraries that are distributed with the
       TinyOS  operating  system.  Please  refer  to  that  project's  documentation   for   more
       information.

       mig(1), nescc(1), nescc-ncg(1)

                                          April 27, 2004                             nescc-mig(1)