ERIKA3 OIL specification

Introduction

The ERIKA3 RTOS is configured by means of an OIL file. The OIL file contains all information needed to configure the kernel, and in addition contains information for building the kernel library and application (this part is used in the standard eclipse distribution provided with ERIKA3.

The OIL file is written using the OIL (OSEK Implementation Language) language. The OIL language is a part of the OSEK/VDX standard. The specification of the OIL file structure and syntax was provided in the OSEK/VDX web site, and is now standardized as ISO 17356-6.

In this chapter we only provide a quick introduction of the OIL Language, together with a specification of the specific OIL attributes implemented by RT-Druid 3.

Standard OIL has no knowledge of multiprocessor systems. for this reason, Erika3 provides a set of OIL extensions that enable the user to create a multi-core configuration.

OIL Basics

In Erika3 all the RTOS objects like tasks, alarms, resources, are static and predefined at application compile time. To specify which objects exist in a particular application, Erika3 uses the OIL Language, which is a simple text description language.

Here is an example of an OIL File for the Arduino uno board:

CPU mySystem {
  OS myOs {
    EE_OPT = "OS_EE_APPL_BUILD_DEBUG";
    EE_OPT = "OS_EE_BUILD_DEBUG";
    CPU_DATA = AVR8 {
      MULTI_STACK = TRUE;
      IDLEHOOK = TRUE {
        HOOKNAME = "idle_hook";
      };
    };
    MCU_DATA = MEGA {
      MODEL = MEGA_328p;
    };
    LIB = ARDUINO {
      /* Used to select Board: UNO or NANO */
      SDK_BOARD = UNO;
      /* Used to select vendor: CC or ORG */
      VARIANT = CC {
        VERSION = "1.8.5";
      };
      /* Create libarduino.a */
      STAND_ALONE = TRUE;
    };
    KERNEL_TYPE = OSEK {
      CLASS = BCC1;
    };
  };
  APPDATA myApp {
    APP_SRC  = "code.cpp";
    APP_SRC  = "task.c";
  };
  TASK TaskL1 {
    PRIORITY = 1;
    STACK = PRIVATE {
      SIZE = 128;
    };
  };
};

The example contains a single object called CPU, which contains all the objects and values used for configuring the system. The CPU object contains other objects, such as: the OS, which specifies the global attributes for the system, and, in the example, one TASK.

The OIL File is parsed by the RT-Druid code generator and, as a result, part of the RTOS source code is generated and compiled together with the application. An OIL file consists of two parts: a set of definitions and a set of declarations:

• Definitions are used to define data types, constants and kernel objects that need to be provided in the declaration part for configuring a specific kernel. In other words, the definition part tells the configurator that there exists different objects like tasks, resources, and so on, describing their attributes and types, like in a C struct declaration.
  • In RT-Druid 3, the definition part of the OIL file is fixed and is contained inside the RT-Druid Eclipse Plugins.
• Declarations are used to specify which objects are really present in a particular application. You can think this part as a C variable definition, which defines the object really present in a kernel configuration.
  • The user has only to provide the declaration part, specifying for a particular application the objects to be created.

The OIL file basically contains the description of a set of objects. A CPU is a container of these objects. Other objects include the following:

• OS is the Operating System which runs on the CPU. This object contains all the global settings which influence the compilation process and the customization of the Erika3 RTOS.
• APPDATA contains the application makefile configuration (currently, the list of files to be compiled).
• APPMODE defines the different application mode. These modes are then used to control the autostart feature for tasks and alarms in the OIL file.
• TASK is an application task handled by the OS.
• RESOURCE is a resource (basically a binary mutex) used for mutual exclusion.
• EVENT is a synchronization flag used by extended tasks.
• COUNTER is a software source for periodic / one shot alarms.
• ALARM is a notification mechanism attached to a counter which can be used to activate a task, set an event, or call a function.

All the attributes in the OIL file can be:

• numbers, i.e. the PRIORITY attribute;
• strings, i.e. the APP_SRC attribute;
• enumerations, i.e. the KERNEL_TYPE attribute.

Attributes can have a default value, as well as an automatic value specified with the keyword AUTO. Some of the attributes can be specified more than once in the OIL file, such as the APP_SRC, and the configurator treats them as a set of values; i.e., in the case of APP_SRC, the set of application files to be compiled.

Finally, some items can in reality contain a set of sub-attributes, like in a C-language struct definition. For example, CPU_DATA contains a AVR8 object, which is detailed by a set of attributes.

The CPU Object

The CPU object is only used as a container of all the other objects, and does not have any specific attribute.

The OS Object

The OS Object is used to define the Erika3 global configuration as well as the compilation parameters. The attributes which can be specified for the OS object are specified in the following subsections.

Compilation attributes

The OIL file includes a set of fields for controlling the command line parameters which are passed to the compiler tools. The meaning of those elements is the following:

• EE_OPT contains a list of additional compilation flags passed to the Erika3 makefile. In practice, the EE_OPT makefile variable controls which files has to be compiled and with which options. The EE_OPT attributes are translated in #defines in the application C code.
• CFLAGS contains the list of additional C compiler options.
• ASFLAGS contains the list of additional assembly options.
• LDFLAGS Contains the list of additional linker parameters.
• LDDEPS Contains the list of additional library dependencies which have to be added to the makefile rules.
• LIBS Contains the list of additional libraries that needs to be linked.

Example of declaration:

CPU mySystem {
  OS myOs {
    EEOPT = "MYFLAG1";
    EEOPT = "MYFLAG2";
    CFLAGS = "-G0";
    CFLAGS = "-O0 -g";
    CFLAGS = "- Wall -Wl ,-Map -Wl , project .map ";
    ASFLAGS = "-g";
    LIBS = "-lm ";
    ...
  };
  ...
};