nescc-mig(1)

1nescc-mig(1)                General Commands Manual               nescc-mig(1)
2
3
4

NAME

6       nescc-mig - message interface generator for nesC
7

SYNOPSIS

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

DESCRIPTION

14       nescc-mig  is  a  tool to generate code to process nesC messages (which
15       are specified by C types). The tool argument specifies what tool should
16       be  generated, the message-type specifies the C type of the message you
17       wish to process and msg-format-file specifies a nesC  file  which  uses
18       that  type.  The message type must be defined with struct message-type,
19       nx_struct message-type, union message-type, nx_union message-type.
20
21       When used with types whose  layout  is  platform-dependent  (i.e.,  not
22       defined  with  nx_struct  or  nx_union), it is important to specify the
23       correct nescc target architecture option  (-fnesc-target=...).  If  you
24       are  invoking  nescc-mig  indirectly via mig, you can use the ncc -tar‐
25       get=...  option instead.
26
27       If an enum constant named AM_message_type (with  message_type  capital‐
28       ized)  is  found,  then the value of that constant is assumed to be the
29       active message type for message-type. If you need access to other  con‐
30       stants  from  your  nesC  application, please consult the nescc-ncg man
31       page.
32
33       The current tools are java, csharp, python and C, which generate  java,
34       C#, python and C code to encode and decode messages.
35

OPTIONS

37       You can pass any nescc option, as well as
38
39       -o output-file
40              Specify the file in which to output the generated code.
41
42       -nescc=driver
43              Use  driver instead of nescc to extract type layout information.
44              For example, if you specify -nescc=ncc, you can use nescc-mig to
45              extract  type  information  from  TinyOS applications (which are
46              normally compiled with ncc).
47
48       tool-specific options
49              See below.
50
51

JAVA TOOL

53       This tool generates a java class to encode or decode  a  nesC  message,
54       basing  itself on the net.tinyos.message infrastructure. It accepts the
55       following options:
56
57       -java-classname=full-class-name
58              This option is required and specifies the package  and  name  of
59              the  generated class. If the full-class-name has no '.', then no
60              package directive is included in the output.
61
62       -java-extends=class-name
63              Specify the class the generated class will extend.  The  default
64              is net.tinyos.message.Message.
65
66       For each field fname of structure message-type, there are the following
67       methods (the bit offset and size methods are useful for structures con‐
68       taining bitfields):
69
70       *      get_fname: get field's value
71
72       *      set_fname: set field's value
73
74       *      offsetBits_fname: return bit offset of field in message-type
75
76       *      offset_fname: return byte offset of field in message-type
77
78       *      sizeBits_fname: return size in bits of field (not for arrays)
79
80       *      size_fname:  return  size  in  bytes  of  field (not for arrays)
81              (absent if fname is a bitfield)
82
83       *      isSigned_fname: return true if fname is of a signed type
84
85       *      isArray_fname: return true if fname is an array
86
87       Embedded structures in message-type are expanded, using _  to  separate
88       the structure name and its fields.
89
90       A number of extra methods are present for fields that are arrays:
91
92       *      getElement_fname: get an element of the array
93
94       *      setElement_fname: set an element of the array
95
96       *      elementSize_fname: return size in bytes of array elements
97
98       *      elementSizeBits_fname: return size in bits of array elements
99
100       *      numDimensions_fname: return number of dimensions of the array
101
102       *      numElements_fname:  return number of elements of the array for a
103              given dimension (left-most dimension is numbered 0) - the dimen‐
104              sion is optional for 1-dimensional arrays
105
106       *      totalSize_fname:  return  size  in bytes of the array (absent if
107              the array is variable-size)
108
109       *      totalSizeBits_fname: return size in bits of the array (absent if
110              the array is variable-size)
111
112       If  the  array is 1-dimensional and the elements are one byte, then the
113       following methods exist:
114
115       *      getString_fname: build a Java string from the array assuming  it
116              contains a C-style null-terminated string
117
118       *      setString_fname:  set  the  array  to  a C-style null-terminated
119              string given a java string
120
121       The getElement_..., setElement_..., offset_... and offsetBits_... meth‐
122       ods  take one argument per array dimension. These methods report errors
123       if the array index is out of bounds. If an array has a maximum size  of
124       0,  mig  assumes it represents a variable-size array and does not check
125       the corresponding array index.
126
127       The data for a message is stored in an array, with  explicit  base  and
128       length  information.  The  constructors can either allocate this array,
129       receive it as an explicit argument or extract if from another  message.
130       The  base  and  length can also be optionally passed to these construc‐
131       tors.
132
133       The optional length argument overrides the default size of  sizeof(mes‐
134       sage-type);  this  is  useful for variable-size messages. The use of an
135       explicit base is helpful for messages embedded in other messages.
136
137       The generated class also has an amType() method which returns the  mes‐
138       sage's  active  message  type, or -1 if no AM_message_type constant was
139       found.
140

C# TOOL

142       This tool generates a C# class to encode or decode a nesC  message.  It
143       accepts the following options:
144
145       -csharp-classname=full-class-name
146              This  option is required and specifies the namespace and name of
147              the generated class. If the full-class-name has no '.', then  no
148              namespace directive is included in the output.
149
150       -csharp-extends=class-name
151              Specify  the  class the generated class will extend. The default
152              is tinyos.message.Message.
153
154              The methods in the generated class are the same as for the  Java
155              tool.
156

PYTHON TOOL

158       This  tool generates a Python class to encode or decode a nesC message.
159       It accepts the following options:
160
161       -python-classname=full-class-name
162              This option is required and specifies the name of the  generated
163              class.
164
165       -python-extends=class-name
166              Specify  the  class the generated class will extend. The default
167              is tinyos.message.Message.Message.
168
169              The methods in the generated class are the same as for the  Java
170              tool.
171

C TOOL

173       This  tool generates a C header file (.h) with constants describing the
174       type's layout, and a C module (.c) with functions to get and  set  each
175       field. You must pass the .h file's name to nescc-mig using -o.
176
177       The C tool accepts the following option:
178
179       -c-prefix=prefix
180              This option specifies the prefix to attach to the generated con‐
181              stants and functions. If omitted, message-type is used.
182
183       For each non-array field fname of structure message-type, the following
184       functions and constants are generated:
185
186       *      prefix_fname_get(): get field's value
187
188       *      prefix_fname_set(): get field's value
189
190       *      prefix_fname_OFFSETBITS: bit offset of field
191
192       *      prefix_fname_OFFSET: byte offset of field
193
194       *      prefix_fname_SIZEBITS: size in bits of field
195
196       *      prefix_fname_SIZE: size in bytes of field
197
198       For  each  array  field  fname of structure message-type, the following
199       functions and constants are generated:
200
201       *      prefix_fname_get(): get field's value
202
203       *      prefix_fname_set(): get field's value
204
205       *      prefix_fname_offsetbits(): bit offset of array element
206
207       *      prefix_fname_offset(): byte offset of array element
208
209       *      prefix_fname_ELEMENTSIZEBITS: size in bits of array element
210
211       *      prefix_fname_ELEMENTSIZE: size in bytes of array element
212
213       *      prefix_fname_NUMELEMENTS: number of elements  in  array  (absent
214              for variable-sized arrays)
215
216       *      prefix_fname_NUMELEMENTS_i: size of ith array dimension
217
218       Embedded  structures  in message-type are expanded, using _ to separate
219       the structure name and its fields. A field  of  an  array  of  embedded
220       structures is considered to be an array.
221
222

ERRORS

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