nescc-mig(1)

📦 version 1.3.5, in debian bookworm, ubuntu jammy

💖 NAME 💖

okay so bestie, welcome to nescc-mig — the message interface generator for nesC 🌸. That's the section 1 of the manual, General Commands Manual, and it's about to be your new obsession, fr fr.

🦋 SYNOPSIS 🦋

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

✨ DESCRIPTION ✨

so nescc-mig is the tool that generates code to process nesC messages (and those messages are specified by C types, periodt). Here's the vibe check on the arguments:

  • tool — tells it what tool should be generated. it's giving "pick your fighter" 💅
  • message-type — the C type of the message you wish to process
  • msg-format-file — a nesC file that uses that type

and listen, your message type has to be defined as one of these, exactly:

struct message-type, nx_struct message-type, union message-type, nx_union message-type.

🚨 IMPORTANT CAVEAT 🚨 — when you're working with types whose layout is platform-dependent (aka not defined with nx_struct or nx_union), it is important that you specify the correct nescc target architecture option: -fnesc-target=.... no cap. and if you're invoking nescc-mig indirectly via mig, you can use the ncc -target=... option instead. slay 🫶

Also, cute little easter egg: if an enum constant named AM_message_type is found (that's with message_type capitalized, iykyk), then the value of that constant is assumed to be the active message type for message-type. 💫 And if you need access to other constants from your nesC application, please consult the nescc-ncg man page — she's got the lore.

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

🎀 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, bestie. ⬇️

☕ JAVA TOOL 🌈

This tool generates a java class to encode or decode a nesC message, basing itself on the net.tinyos.message infrastructure. She accepts the following options:

  • -java-classname=full-class-name — this option is required and specifies the package and name of the generated class. and heads up: if the full-class-name has no . in it, 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 these extra little cuties 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. 🚨 And 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. noted. 📌

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 it 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. She 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. She 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. don't forget, bestie, it's not optional 🫠

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 😭
  • message-type isn't found
  • it contains pointers
⚠️ yeah, pointers? instant no. she said nope. 🙅‍♀️

🫶 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. 📚

and that's the whole page, bestie — this one's from April 27, 2004, straight out of the General Commands Manual, and it lives in section 1 as nescc-mig(1). go generate some message interfaces, you main character 💅✨🦋

📦 where this page comes from