G^enoM Manual

For G^enoM version 3

Sara Fleury - sara.fleury@laas.fr
Matthieu Herrb - matthieu.herrb@laas.fr
Anthony Mallet - anthony.mallet@laas.fr
Cédric Pasteur

Copyright 2009-2010 © LAAS/CNRS

September 20, 2010

Contents

1  Introduction
2  Component model
3  G^enoM overview
4  A minimal example
5  Input file format
    5.1  Overview
    5.2  Preprocessing
    5.3  Dotgen grammar
    5.4  Dotgen specification
    5.5  Identifiers and reserved keywords
    5.6  Line directives
    5.7  Module declaration
    5.8  Type declaration
    5.9  Constant declaration
6  G^enoM IDL mappings
    6.1  C mappings
        6.1.1  Scoped names
        6.1.2  Mapping for constants
        6.1.3  Mapping for basic data types
        6.1.4  Mapping for enumerated types
        6.1.5  Mapping for strings
        6.1.6  Mapping for arrays
        6.1.7  Mapping for structure types
        6.1.8  Mapping for union types
        6.1.9  Mapping for sequence types
    6.2  C++ mappings
        6.2.1  Scoped names
        6.2.2  Mapping for constants
        6.2.3  Mapping for basic data types
        6.2.4  Mapping for enumerated types
        6.2.5  Mapping for strings
        6.2.6  Mapping for arrays
        6.2.7  Mapping for structure types
        6.2.8  Mapping for union types
        6.2.9  Mapping for sequence types
7  Running G^enoM
    7.1  Synopsis
    7.2  Description
    7.3  General options
    7.4  Template options
    7.5  Environment variables
8  Templates
    8.1  The template command
    8.2  The engine command
    8.3  The dotgen command
        8.3.1  dotgen genom
        8.3.2  dotgen template
        8.3.3  dotgen input
        8.3.4  dotgen parse
        8.3.5  dotgen types
        8.3.6  dotgen components
    8.4  The language command
    8.5  The object command
    8.6  The buildenv command
        8.6.1  buildenv autoconf
Index

1
Introduction

2
Component model

3
G^enoM overview

4
A minimal example

5
Input file format

This chapter describes the G^enoM Input File Format (dotgen) semantics and gives the syntax for dotgen grammatical constructs.

5.1  Overview

The G^enoM Input File Format ( dotgen) is the language used to formally describe a G^enoM component in terms of services and data types it provides. A description written in dotgen completely defines the interface and the internals of a component. A description of the dotgen preprocessing is presented in section 5.2. The grammar is presented in section 5.3 and associated semantics is described in the rest of this chapter either in place or through references to other sub sections of this chapter. A source file containing a dotgen component specification must have a ".gen" extension. The description of the dotgen grammar uses a syntax notation that is similar to Extended Backus-Naur Format (EBNF). Table 5.1 lists the symbols used in this format and their meaning.

Symbol	Meaning
::=	Definition.
|	Alternation.
text	Nonterminals.
"text"	Terminals.
( ... )	Grouping.
{ ... }	Repetition: may occur zero or any number of times.
[...]	Option: may occur zero or one time.

Table 5.1: dotgen EBNF symbols

5.2  Preprocessing

A dotgen specification consists of one or more files that are preprocessed. The preprocessing performs file inclusion and macro substitution and is controlled by directives introduced by lines having # as the first character other than white space. The preprocessing is done by the C preprocessor available on the host system and configured during the build of G^enoM. It is invoked as a separate process. Preprocessor directives beginning with # have their own syntax (namely, the C preprocessor syntax), independent of the dotgen language and not described in this document. See for instance [1] for a documentation. Directives may appear anywhere in the source file but are not seen nor interpreted by G^enoM. The primary use of the preprocessing facilities is to include definitions (especially type definitions) from other dotgen specifications. Text in files included with a #include directive is treated as if it appeared in the including file.

5.3  Dotgen grammar

5.4  Dotgen specification

A dotgen specification consists of one or more statements. Statements are either IDL statements, G^enoM statements or cpp line directives. The syntax is: Definitions are named be the mean of identifiers: see section 5.5. Cpp line directives are normally issued by the C preprocessor and are used to define the current input file name and line number (section 5.6). An IDL statement defines types (see section 5.8), constants (see section 5.9) or IDL modules containing types and constants (see section 5.7). The syntax follows closely the subset the OMG IDL specification corresponding to type and constants definitions (see Part I, chapter 7 of [2]). Note that this subset of the dogten grammar is not in any manner tied to OMG IDL and may diverge from future OMG specifications. A G^enoM statement defines components, communication ports, services and execution contexts called tasks.

5.5  Identifiers and reserved keywords

An identifier is a sequence of ASCII alphabetic, digit, and underscore ("_") characters. The first character must be an ASCII alphabetic character. Words that are reserved keywords in the dotgen language are valid identifiers where their use is not ambiguous.

5.6  Line directives

Line directives are normally not used. They are inserted by cpp, as a result of preprocessing the input file (section 5.2). They can be used mostly to achieve special effects on error reporting or similar. A line directive starts with the # sign: The # sign is followed by the current line number and file name of the source file, optionally followed by a numeric flag. The flag is never used by G^enoM. Its meaning depends on the C preprocessor used: see for instance chapter 1.8, C preprocessor output, of the FSF C preprocessor [1]. The file name and line number replace the current value kept internally by G^enoM and are used in error reporting messages as well as a few other places.

5.7  Module declaration

A module definition satisfies the following syntax: The only effect of a module is to scope IDL identifiers. It is similar to a C++ or Java namespace; it is considered good practice to enclose your type definitions inside a module definition to prevent name clashes between components.

5.8  Type declaration

Type declarations define new data types and associate a name (an identifier) with it. The typedef keyword can be used to name an existing type. The constructed types struct, union and enum also name the type they define. The syntax is the following:

A type specification is the description of a type. It can be used in a typedef construct or anywhere a typed value is expected.

5.9  Constant declaration

6
G^enoM IDL mappings

G^enoM IDL is independent of the programming language used to implement the services and internals of a component. In order to use the G^enoM generated source code, it is necessary for programmers to know how to access the service parameters and ports from their programming languages. This chapter defines the mapping of G^enoM IDL constructs to the supported programming languages. The mapping between G^enoM IDL and a programming language diverges from the OMG CORBA standard. This is unfortunate, because this might lead to some confusion for the developers used to OMG CORBA, but it was necessary to define mappings well targetting real-time platforms. The design strategy that guided the definition of those mappings was to try to have contiguous memory segments, that do not require memory management primitives, for most of the data types. Only unbounded string and sequences do not follow this scheme. G^enoM currently implements mappings for the C and C++ languages. For the C language, see section 6.1. For the C++ language, see section 6.2

6.1  C mappings

6.1.1  Scoped names

The C mappings always use the global name for a type or a constant. The C global name corresponding to a G^enoM IDL global name is derived by converting occurrences of "::" to "_" (an underscore) and eliminating the leading underscore.

6.1.2  Mapping for constants

In C, constants defined in dotgen are #defined. For instance, the following IDL:

      const long longint = 1;
      const string str = "string example";

would map into

      #define longint 1
      #define str "string example"

The identifier can be referenced at any point in the user's code where a literal of that type is legal.

6.1.3  Mapping for basic data types

The basic data types have the mappings shown in Table 6.1. Integer types use the C99 fixed size integer types as provided by the stdint.h standard header. Users do not have to include this header: the template mapping generation procedure output the appropriate #include directive along with the mappings for the integer types.

IDL	C
boolean	bool
unsigned short	uint16_t
short	int16_t
unsigned long	uint32_t
long	int32_t
unsigned long long	uint64_t
long long	int64_t
float	float
double	double
char	char
octet	uint8_t
any	type any not implemented yet

Table 6.1: Basic data types C mappings

6.1.4  Mapping for enumerated types

The C mapping of an IDL enum type is an unsigned, 32 bits wide integer. Each enumerator in an enum is #defined with an appropriate unsigned integer value conforming to the ordering constraints. For instance, the following IDL:

      enum e {
         value1,
         value2
      };

would map, according to the scoped names rules, into

      typedef uint32_t e
      #define e_value1  1
      #define e_value2  2

6.1.5  Mapping for strings

G^enoM IDL bounded strings are mapped to nul terminated character arrays (i.e., C strings). Unbounded strings are mapped to a pointer on such a character array. For instance, the following OMG IDL declarations:

      typedef string unbounded;
      typedef string<16> bounded;

would map into

      typedef char *unbounded;
      typedef char bounded[16];

6.1.6  Mapping for arrays

G^enoM IDL arrays map directly to C arrays. All array indices run from 0 to size-1. For instance, the following IDL:

      typedef long array[4][16];

would map into

      typedef int32_t array[4][16];

6.1.7  Mapping for structure types

G^enoM IDL structures map directly onto C structs. Note that these structures may potentially include padding. For instance, the following IDL:

      struct s {
         long a;
         long b;
      };

would map into

      typedef struct {
         int32_t a;
         int32_t b;
      } s;

6.1.8  Mapping for union types

G^enoM IDL unions map onto C structs. The discriminator in the enum is referred to as _d, the union itself is referred to as _u. For instance, the following IDL:

      union u switch(long) {
         case 1: long a;
         case 2: float b;
         default: char c;
      };

would map into

      typedef struct {
         int32_t _d;
         union {
            int32_t a;
            float b;
            char c;
         } _u;
      } u;

6.1.9  Mapping for sequence types

G^enoM IDL sequences mapping differ slightly for bounded or unbouded variations of the sequence. Both types maps onto a C struct, with a _maximum, _length and _buffer members. For unbounded sequences, buffer points to a buffer of at most _maximum elements and containing _length valid elements. An additional member _release is a function pointer that can be used to release the storage associated to the _buffer and reallocate it. It is the responsibility of the user to maintain the consistency between those members. For bounded sequences, buffer is an array of at most _maximum elements and containing _length valid elements. Since _buffer is an array, no memory management is necessary for this data type. For instance, the following IDL:

      typedef sequence<long> unbounded;
      typedef sequence<long,16> bounded;

would map into

      typedef struct {
         uint32_t _maximum, _length;
         int32_t *_buffer;
         void (*release)(void *_buffer);
      } unbounded;

      typedef struct {
         const uint32_t _maximum;
         uint32_t _length;
         int32_t _buffer[16];
      } bounded;

6.2  C++ mappings

6.2.1  Scoped names

The C++ mappings for scoped names use C++ scopes. IDL modules are mapped to namespaces. For instance, the following IDL:

      module m {
         const string str = "scoped string";
      };

would map into

      namespace m {
         const std::string str = "scoped string";
      }

6.2.2  Mapping for constants

G^enoM IDL constants are mapped to a C++ constant. For instance, the following IDL:

   const long longint = 1;
   const string str = "string example";

would map into

   const int32_t longint = 1;
   const std::string str = "string example";

6.2.3  Mapping for basic data types

The basic data types have the mappings shown in Table 6.2. Integer types use the C99 fixed size integer types as provided by the stdint.h standard header (since the C++ cstdint header is not part of the C++ at the time of writing this document). Users do not have to include this header: the template mapping generation procedure output the appropriate #include directive along with the mappings for the integer types.

IDL	C++
boolean	bool
unsigned short	uint16_t
short	int16_t
unsigned long	uint32_t
long	int32_t
unsigned long long	uint64_t
long long	int64_t
float	float
double	double
char	char
octet	uint8_t
any	type any not implemented yet

Table 6.2: Basic data types C++ mappings

6.2.4  Mapping for enumerated types

The C++ mapping of an IDL enum type is the corresponding C++ enum. An additional constant is generated to guarantee that the type occupies a 32 bits wide integer. For instance, the following IDL:

      enum e {
         value1,
         value2
      };

would map, according to the scoped names rules, into

      enum e {
         value 1,
         value 2,
         _unused = 0xffffffff,
      };

6.2.5  Mapping for strings

G^enoM IDL bounded strings are mapped to nul terminated character arrays (i.e., C strings) wrapped inside the specific genom::bounded_string class. Unbounded strings are mapped to std:string provided by the C++ standard. For instance, the following OMG IDL declarations:

      typedef string unbounded;
      typedef string<16> bounded;

would map into

      typedef std::string unbounded;
      typedef genom::bounded_string<16> bounded;

The genom::bounded_string provides the following interface:

      namespace genom3 {
         template<std::size_t L> struct bounded_string {
            char c[L];
         };
      }

This minimalistic definition will be refined before the official 3.0 G^enoM release.

6.2.6  Mapping for arrays

G^enoM IDL arrays map directly to C++ arrays. All array indices run from 0 to size-1. For instance, the following IDL:

      typedef long array[4][16];

would map into

      typedef int32_t array[4][16];

6.2.7  Mapping for structure types

G^enoM IDL structures map directly onto C++ structs. Note that these structures may potentially include padding. For instance, the following IDL:

      struct s {
         long a;
         long b;
      };

would map into

      struct s {
         int32_t a;
         int32_t b;
      };

6.2.8  Mapping for union types

G^enoM IDL unions map onto C structs. The discriminator in the enum is referred to as _d, the union itself is referred to as _u. For instance, the following IDL:

      union u switch(long) {
         case 1: long a;
         case 2: float b;
         default: char c;
      };|

would map into

      struct u {
         int32_t _d;
         union {
            int32_t a;
            float b;
            char c;
         } _u;
      };

Note that the C++ standard does not allow union members that have a non-trivial constructor. Consequently, the C++ mapping for such kind of unions is not allowed in G^enoM either. This concerns sequences and strings, and structures or unions that contain such a type. You should thus avoid to define such datatypes in G^enoM IDL in order to maximize the portability of your definitions.

6.2.9  Mapping for sequence types

G^enoM IDL sequences mapping differ for bounded or unbouded variations of the sequence. The unbounded sequence maps onto a C++ std::vector provided by the C++ standard. The bounded sequences maps onto the specific genom3::bounded_vector class. For instance, the following IDL:

      typedef sequence<long> unbounded;
      typedef sequence<long,16> bounded;

would map into

      typedef std::vector<int32_t> unbounded;
      typedef genom3::bounded_vector<int32_t, 16> bounded;

The genom::bounded_vector provides the following interface:

      namespace genom3 {
         template<typename T, std::size_t L> struct bounded_vector {
            T e[L];
         };
      }

This minimalistic definition will be refined before the official 3.0 G^enoM release.

7
Running G^enoM

7.1  Synopsis

genom3 [-l] [-h] [--version]
genom3 [-I dir] [-D macro[=value]] [-E|-n] [-v] [-d] file.gen
genom3 [general options] template [template options] file.gen

7.2  Description

The G^enoM program is a source code generator that is used to generate software components from a formal description file. The input file is expected to contain the description of the services, input and output ports, data types definitions and execution contexts of a software component, written in the dotgen language. The dotgen specification is first processed by a C preprocessor before it is parsed by G^enoM and transformed into an abstract syntax tree. The program used as a C preprocessor can be changed with the CPP environment variable. G^enoM accepts -I and -D options that are passed inchanged to the cpp program. The abstract syntax tree is exported in a format suitable to a generator engine that is in charge of a template execution for actual source code generation. The generator engine provides a scripting language and a set of procedures for use by templates. The directory where source code for the generator engine is searched can be changed with the -s option. Templates are a set of source files that serve as the basis for source code generation. Templates source files are interpreted by the generator engine. They can contain code written in the scripting language provided by the generator engine, that computes generated output, or regular source code that is appended directly to the generated code. Intermediate files and scripts are saved in a temporary directory before they are copied to the final destination directory. The -T option changes the path of the temporary directory. The -d option will keep all temporary files instead of deleting them once the program terminates. This is useful only for template development and debugging. The choice of a template depends on the kind of source code that is wanted by the user. Refer to the documentation of the templates for a description on what they do. The names of the available templates can be listed with the -l option. The directory in which templates are looked for can be changed with the -t option. The G^enoM program accepts general options that affect the general program behaviour. G^enoM can also pass template options to the template. These options will only affect the template behaviour.

7.3  General options

-I dir

Add the directory dir to the list of directories to be searched for included files. The dir argument is passed as-is to the cpp program via the same -I option.

When -r option is in effect (either explicitely passed on the command line, or configured by default during the build process), an implicit -I directive pointing to the directory of the input file is appended to the end of the list of searched directories.

-D macro[=value]

Predefine macro, with definition 1 or value if given, in the same way as a #define directive would do it. This option is passed as-is to the cpp program.

If you are invoking genom from the shell, you may have to use the shell quoting character to protect shell's special characters such as spaces.

An implicit macro __GENOM__ is always defined and contains the version of the genom program. This can be used to divert some lines in source files meant to be included by other tools that genom, and that contain syntax that genom does not understand.

-E

Stop after the preprocessing stage, and do not run genom proper. The output of cpp is sent to the standard output. genom exits with a non-zero status if there are any preprocessing errors, such as a non-existent included file.

-n, --parse-only

Stop after the input file parsing stage, and do not invoke any template. This is useful to check the syntax of the input file. Any errors or warning are reported and genom exits with a non-zero status if there are errors.

-l, --list

Print to the standard output the list of available templates. Each line of output contains the name of a template and the genom engine that is uses (currently, only Tcl-based templates are supported).

By default, the standard templates directory is searched, but any -t option will be taken into account.

-t path, --tmpldir=path

Use path as the directory containing templates. This can be a colon separated list of directories which are search in order.

This option is useful only for templates not installed in the genom standard directories, i.e. share/genom/<version>/templates or share/genom/site-templates.

path is searched for files matching dir/*/template.tcl, where * is the actual template name.

-s dir, --sysdir=dir

Use dir as the directory holding genom engine files. This option is useful if non-standard engines are to be used. The default value is share/genom/<version>/engines.

dir should contain directories named after the engine name.

-T dir, --tmpdir=dir

Use dir as the temporary directory holding intermediate files. See also the environment variable TMPDIR.

-r, --rename

Some cpp programs cannot handle correctly files with a .gen extension. This option will make genom call cpp with an input file ending in .c, linked to the real input file.

--no-rename

This option is the opposite of -r: it forces genom to invoke cpp directly with the .gen input file. This is the default behaviour. If you are using GNU cpp, it might be necessary to pass it the additional -xc option, to force it to handle the file as C source.

-v, --verbose

Force genom to be more verbose while processing input files.

-d, --debug

Activate some debugging options. In particular, temporary files are not deleted. Useful for debugging genom itself or generator engines.

--version

Display the version number of the invoked GenoM.

-h, --help

Print usage summary and exit.

7.4  Template options

-h, --help

Templates might define their own specific options. The -h option is always defined, and prints a summary of supported options. See the template manual for a detailed description. Template options should be passed after the template name, and before the input file name.

7.5  Environment variables

CPP

Define the C preprocessor program to use. The default depends on the value configured during the genom build process, but it is most often gcc -E -xc on Linux systems.

The CPPprogram must recognize -I and -D arguments.

GENOM_TMPL_PATH

The value of GENOM_TEMPLATE_PATH is a colon-separated list of directories, much like PATH, where G^enoM looks for templates. Setting this variable overrides the default search path, but any -t option takes precedence over this variable.

TMPDIR

Path to the directory holding temporary files. Defaults to /tmp.

8
Templates

8.1  The template command

8.2  The engine command

8.3  The dotgen command

8.3.1  dotgen genom

Those commands implement access to genom program parameters or general information.

8.3.2  dotgen template

Those commands return information about the template currently being parsed.

8.3.3  dotgen input

Those commands return information about the current genom input file (.gen file).

8.3.4  dotgen parse

8.3.5  dotgen types

This command return information about the type definitions in the .gen file.

8.3.6  dotgen components

This command return information about the components definitions in the .gen file.

8.4  The language command

8.5  The object command

8.6  The buildenv command

8.6.1  buildenv autoconf

Bibliography

[1]

Free Software Foundation. The C preprocessor. http://gcc.gnu.org/onlinedocs/cpp/.

[2]

Object Management Group. CORBA specification, version 3.1. Part I: CORBA interfaces. http://www.omg.org/spec/CORBA/3.1/Interfaces/PDF.

Index

B   buildenv (template command), 8.6      autoconf, 8.6          create, 8.6          subdir, 8.6	D   dotgen, 5.1      grammar, 5.3      identifier, 5.5      specification, 5.4 dotgen (template command), 8.3      components, 8.3      genom, 8.3          cmdline, 8.3          debug, 8.3          program, 8.3          stdout, 8.3          version, 8.3      input, 8.3          base, 8.3          dir, 8.3          file, 8.3          notice, 8.3      parse, 8.3      template, 8.3          dir, 8.3          name, 8.3          sysdir, 8.3          tmpdir, 8.3      types, 8.3
E   engine (template command), 8.2      chdir, 8.2      mode, 8.2      pwd, 8.2	I   identifier, 5.5 input      file format, 5.1      preprocessing, 5.2
L   language (template command), 8.4      cname, 8.4      comment, 8.4      declarator, 8.4      declarator*, 8.4      declarator&, 8.4      dereference, 8.4      fileext, 8.4      hfill, 8.4      invoke, 8.4      mapping, 8.4      member, 8.4      reference, 8.4      signature, 8.4	O   object (template command), 8.5      foreach, 8.5
P   preprocessing, 5.2	T   template (template command), 8.1      arg, 8.1      fatal, 8.1      link, 8.1      message, 8.1      options, 8.1      parse, 8.1      require, 8.1      usage, 8.1 template command      buildenv, 8.6      dotgen, 8.3      engine, 8.2      language, 8.4      object, 8.5      template, 8.1