This guide conveys the knowledge necessary to develop your own KESO applications. We assume that you have successfully setup the environment at described in the First Steps.
We will first outline the general chain of tools involved when building a KESO application. The actual toolchain may vary depending on the used backend.
A KESO application consists of one or more Java modules and a system
description file that defines the structure of the system and instances of
operating system objects such as tasks. Each Java module resides in a
subdirectory of the libs directory. An application may consist of
multiple such modules, which are merged by jino (KESO's compiler) to a single
Java source file hierarchy. The system configuration file (given to jino by the
environment variable $KESORC) tells jino which modules are needed by the
current application. Jino compiles the Java modules to C source code and also
generates a configuration file for the OSEK operating system in
OIL format
for the used OSEK operating system. The generated C code is created in subdirectories
of the output base directory given by the environment variable $KESOOUTPATH. If
$KESOOUTPATH is not set, the default output base directory tmp/ is used.
The code for the OSEK OS is built using the
OSEK implementation specific OSEK system generator (OSEK SG) tool. Finally, the
application source code and the OS source code are compiled and linked using a
standard C compiler/linker toolchain.
An application consists of one or more modules. Each module is a part of the total source base that is used by the application. When creating the application, all modules used by the application are combined to a single hierarchy of Java classes, which is then processed as the source code of the application. The modules used by the application are given in the system description file $KESORC. Modules may further depend on other modules, which are automatically included by jino when creating the source hierarchy.
Each module resides in a subdirectory of the libs/ directory, the name of which becomes the name of the module. The directory contains the Java source files of the module in the usual Java package directory structure (the module's root directory itself is not a package). In addition, the module directory contains a special file META that contains additional information on the module, most notably its dependencies on other modules. Most application modules will at least depend on the core module, which contains the KESO specific service APIs as well as the core parts of the standard class library. As an example, the code of the trafficlight demo application is stored in the module mica2_trafficlight. The META file of this module looks as follows:
AUTHORS=mike
REQUIRE=core
REQUIRE=avr
The AUTHORS line is purely informational. Each REQUIRE line lists a dependency of the module. In this case, the mica2_trafficlight module depends on the modules core and avr, which will added to the application code base.
The system description file $KESORC defines the system objects and configuration options for the OSEK OS. A comprehensive and well-commented configuration file is rc/fully_documented_example.kcl; while this file does not define a valid application, it contains most of the available configuration items and comments on their meaning. Each application is described by a system configuration file. These files normally reside somewhere in the directory tree rc/. The actual configuration file that is used when running jino is given in the environment variable $KESORC, which holds the path to the file relative to the src/ directory. For the single domain configuration of the trafficlight demo application, the setting of this environment variable could look like:
In this section, we will focus on the core parts of the configuration file at the example of the trafficlight_mica_singledomain.kcl configuration file. Configuration items on special topics such as the use of portals are documented in separate howtos.
The configuration trafficlight_mica_singledomain.kcl contains the following:
World (TrafficLights) {
# A system defines the software for one node (in the network)
System (Mica2) {
# software modules of the application (: separated)
Modules = "mica2_trafficlight";
# backend selection
Target = "AVR_JOSEK";
ProcessorType = "atmega128";
# Clock Frequency, used by the AVR USART driver
Frequency = 7372800;
# Configuration of the OSEK OS
OsekOS (JOSEK) {
STATUS = "STANDARD";
STARTUPHOOK = false {}
ERRORHOOK = false {}
SHUTDOWNHOOK = false {}
PRETASKHOOK = false {}
POSTTASKHOOK = false {}
MICROCONTROLLER = "atmega128";
FREQ = 7372800;
}
Domain (trafficLightControl) {
Heap = IdleRoundRobin {
HeapSize=1024;
SlotSize=16;
}
Task (tlTask) {
# class containing the task's entry function (must implement Runnable)
MainClass="trafficlight/TrafficLightTask";
# OSEK Schedule: not preemptable
Schedule="NON";
# task is not activated on startup
Autostart = false {
Appmode = "OSDEFAULTAPPMODE";
}
# OSEK scheduling priority
Priority = "10";
}
Task (rcTask) {
MainClass="trafficlight/RemoteControlTask";
Priority = "5";
Schedule="NON";
Autostart = false {
Appmode = "OSDEFAULTAPPMODE";
}
}
# definition of the rx_isr
# The name must be equal to the interrupt vector of the service routine
ISR(SIG_UART0_RECV) {
# class containing the ISR function
HandlerClass="trafficlight/RemoteControlTask";
# signature of the ISR function; must be a static function
HandlerMethod="rx_isr()V";
# ISR category
Category = "2";
}
ISR(SIG_UART0_DATA) {
HandlerClass="keso/driver/avr/atmega128/Usart";
HandlerMethod="transmitCompleteInterrupt()V";
Category = "2";
}
Alarm (tlAlarm) {
# underlying system counter
UseCounter = "counter1";
# action to perform when the alarm expires
# tlAlarm activates tlTask
Action = ACTIVATETASK {
UseTask = "tlTask";
}
# tlAlarm is not armed on system startup
# the inner attributes are only relevant for autoarmed alarms
Autostart = false {
Appmode = "OSDEFAULTAPPMODE";
Alarmtime = "1";
Cycletime = "1";
}
}
Service (TrafficLightService) {
ServiceInterface="trafficlight/TrafficLightServiceInterface";
ServiceClass="trafficlight/TrafficLightService";
}
Import (TrafficLightService) { }
}
# base of tlAlarm, advances every second
Counter (counter1) {
MAXALLOWEDVALUE = "10";
MINCYCLE = "1";
TIMER_BASE = "Counter1";
# major tick is 1s (10 minors)
TICKSPERBASE = "10";
# minor tick is 100 ms
# TIME_IN_NS is JOSEK specific
TIME_IN_NS = "100000000";
}
}
}
General Format
The configuration file format is similar to the structure of the standard OSEK OIL configuration files with some modifications. Comments may be inserted using the # character as known from various scripting languages. There are three basic structural elements in an KESORC configuration file:
Simple Attributes: Simple assignments of the form
KEY = VALUE;
Complex Attributes: Attributes that may contain further simple subattributes.
Named Blocks: Blocks may contain any of the structural elements, have a name but are not assigned a value. For many types of blocks, the given name is purely informational. For some block types,
e.g. task blocks, the name given will be used in the Java code to refer to the entity defined by the block. In both cases, names used should be unique throughout the configuration for each type of block.
KESO is principally capable of creating software images for a whole network of nodes. This functionality has, however, recently not been used and may be broken. Nevertheless, the configuration file structure represents this idea: The configurations for the different nodes are enclosed in a World block, the name of which is purely informational (becomes part of the output directory name). The World block contains System (synonym alternative: Node) blocks, that contain the configuration for one node in the system. The name of the each system block is again purely informational, but together with the world name forms the output directory name of the form WORLDNAME_SYSTEMNAME.
The most important attributes in a System block are
Modules: colon-separated list of module names used by the application (dependencies as defined in the modules' META files need not be listed here)
Target: compiler backend to be used
There may be other backend-specific subattributes such as the ProcessorType attribute required for the AVR_JOSEK backend. These are best determined by looking at existing configurations for that backend.
OsekOS configuration
The OsekOS block contains the configuration of the OSEK operating system. Besides the standard attributes defines in the OIL specification there may be implementation specific additional attributes. These are equivalent to those used in the OIL file for the specific implementation and should be documented with the respective OSEK implementation.
Domains
Any application control flow is executed within a protection domain, thus each system will contain at least one domain definition. Each domain contains the definition of its heap, the control flows (Task, ISR) and other domain local system objects such as OSEK Resources (Resource) or Alarms (Alarm). Most attributes of these OSEK system objects are defined in OIL. We will focus on the KESO specific additions.
Heap
Each domain contains a heap of its own, the management strategy and size of which are defined in a complex attribute Heap within the Domain block. The value assigned to the heap attribute determines the heap management strategy to be used. The currently available strategies are:
RestrictedDomainScope: no garbage collection
CoffeeBreak: stop-the-world garbage collection
IdleRoundRobin: incremental garbage collection (i.e., GC preemptable by the application)
The heap attribute contains the HeapSize subattribute, which defines the size of the heap in bytes. For large heap sizes, one may alternatively use HeapSizeKB or HeapSizeMB to define the heap size in kiB or MiB units. Depending on the heap implementation, there may be further subattributes such as the SlotSize attribute for garbage collected heaps. Detailing the available subattributes is beyond the scope of this howto. For the SlotSize, a power of two greater or equal than 8 should be used.
Tasks
The OSEK equivalent to a Java thread. Tasks cannot be dynamically created in an OSEK system (and hence also in KESO) and need to be statically defined in a Task block each. KESO strictly separates the system object of a task (the Thread object) and the application object (instance of a class implementing the Runnable interface). In KESO, applications must not subclass the java.lang.Thread class. For each defined task, jino statically creates a Thread object, that is used for system operations on the control flow (e.g., activating a task), and an instance of the application logic class containing the run() method. The Thread object is available through the name service (provided by the keso.core.TaskService class) using the task's name as given in the Task block definition. Besides the standard OIL attributes defined for a Task block, KESO
requires the MainClass attribute in a Task block that defines the class containing the application logic (i.e., the run() method) of the task.
ISRs
Interrupt service routines (ISR) may be defined in an ISR block. In the Java code, an ISR routine is defined as a static method that does not expect parameters. Besides the standard OIL ISR attributes, KESO requires the attributes
HandlerClass: defines the class containing the ISR routine
HandlerMethod: defines the signature of the ISR routine
The name of the ISR block defines the interrupt vector entry that will be used for the ISR. This name is normally defined by the C library for the target platform.
Alarms and Resources
OSEK Alarms and OSEK Resources are defined in Alarm and Resource blocks. The subattributes of these blocks are the standard OSEK attributes as defined in the OIL specification. As with tasks, the name of the blocks is used to refer to the respective entities in the Java code using the name service (keso.core.AlarmService and keso.core.ResourceService). Example definitions are also available in many existing configurations such as the above example.
Counters and Events
Since these entities are not subject to service protection (in the case of events service protection is given by the domain local tasks that are required as targets for the notification), these entities are defines system-wide as blocks within the System block.
Counters are defined in a Counter block and are required as the basis for alarms. For an explanation of the two-level OSEK Counter/Alarm concept see the OSEK/VDX specification. There are no KESO specific subattributes for Counter blocks, however, many OSEK implementations define additional subattributes, e.g. for defining the duration of a (minor) counter tick.
Events are defines in an Event block. There are no KESO specific subattributes.
jino can be influenced by compiler options given in the environment variable $JINOFLAGS. A list of available options is given by the script X-options, which should reside in your PATH after invoking KESO's environment setup script. Unfortunately, these flags are not documented at the moment. Currently, a sanedefault setting is
