## Software Model

The AMALTHEA software model is central accessible through the SWModel element.

### Memory Information

Analyzing and mapping the software structure to available memories needs additional information of the included elements. This type of information targets the consumed size of memory of an element, represented by the size attribute of type DataUnit. The element AbstractMemoryElement is a generalized element that provides this data. The following image shows the structure and also the elements of the software model that are extending AbstractMemoryElement (the overview picture is only showing the hierarchy and not possible relationships between the elements):

### Labels

The label element represents a data element. It is directly located in a defined area of a given memory.
It can be used as a parameter, a temporarily existing variable or representing a constant value.

The following attributes are describing a label:

Name | Description
--- | ---
name | The name represented as String value (derived from AbstractElementMemoryInformation)
displayName | In addition to the name attribute, which must be unique, a label can also be described by an additional and optional display name. The displayName attribute must not be unique. It can be used for example to represent specification data, which can be different from the unique name (like a symbol) of an available software build.
dataType | Reference to the data type definition
constant | Boolean value to represent, if label is representing a constant value
bVolatile | Boolean value to mark a label as volatile
dataStability | Enumeration value to represent the data stability needs of the label. If set, it overwrites the global settings stated by the OsDataConsistency, otherwise it inherits them (see OS Data Consistency).
stabilityLevel | Enumeration value to represent the data stability level of the label. If set, it overwrites the global settings stated by the OsDataConsistency, otherwise it inherits them (see OS Data Stability).

### Channels

The channel element has two different characteristics: it represents a data element in memory and also a way how runnables transmit larger amounts of data. A typical applications is the streaming of video data where a continuous sequence of images is sent in smaller chunks.

The following attributes are describing a label:

Name | Description
--- | ---
name | The name represented as String value (derived from AbstractElementMemoryInformation)
displayName | In addition to the name attribute, which must be unique, a label can also be described by an additional and optional display name. The displayName attribute must not be unique. It can be used for example to represent specification data, which can be different from the unique name (like a symbol) of an available software build.
elementType | Reference to the data type definition of a single element
defaultElements | Number of elements initially in the channel (at start-up)
maxElements | Depth of channel (maximum number of elements that may be stored)

### Data Types

#### General Information

The AMALTHEA data model supports meta information for data types. Therefore the element TypeDefinition exists in the software part of the model. It consists of the name and size to define a data type. BaseTypeDefinition has the additional possibility to define the representation of these data types in a target environment (e.g. AUTOSAR), represented by the Alias element.

The compound data types are data structures, based on given or defined base types.
In the literature they are also often named composite or derived types see Wiki.
The result of this type of definition is an own data type, which can be used as base data types.
They can consist of static structures or dynamic ones, like arrays or stacks.

The following compound data type definitions are currently supported:

- Pointer: Holds a reference to another type using its memory address
- Array: Contains a number of elements of the same data type. The size of an array can be fixed or expandable.
- Struct: Contains other data types in a structured way, often called fields or members. The fields can be accessed by their name.

#### Sample

In the picture below a small sample is modeled containing the following information:

- Boolean type with size of 8 bits and alias for AR (Boolean) and C (bool)
- Char16 type with size of 16 bits and alias for AR (Char16) and C (short)
- charArray consists of 4 elements of type Char16
- “hello world struct” with the attribute name (charArray) and valid (Boolean)

Note: The picture shows the element types for better understanding!

### Activations

Activations are used to specify the intended activation behavior of Runnables and ProcessPrototypes. Typically they are defined before the creation of tasks (and the runnable to task mappings). So if there are no tasks defined, or if the mapping of runnables to tasks is not done, this is a way to document when the runnables should be executed.
Activations are independent of other top level elements in the AMALTHEA model. Single, periodic, sporadic, event or custom (free textual description only, no predefined semantic) activation pattern can be defined. This information can be used in the following development steps to create tasks, stimuli and the mappings to dedicated hardware.

- PeriodicActivation: The Time object in the role of min must not contain a negative value!
- PeriodicActivation: The Time object in the role of max must not contain a negative value!
- PeriodicActivation: The Time object in the role of offset must not contain a negative value!
- PeriodicActivation: The Time object in the role of deadline must not contain a negative value!
- SingleActivation: The Time object in the role of min must not contain a negative value!
- SingleActivation: The Time object in the role of max must not contain a negative value!

### Tasks / ISR

The following figure shows the structure which describes Tasks and Interrupt Service Routines ( ISR) in the AMALTHEA software model. The abstract class Process generalizes ISRs and Tasks and provides the common attributes like the activation that is at runtime level represented by a Stimulus. A Task or ISR contains calls either to other Tasks (via inter process activation) or Runnables. These types of calls are included in the activityGraph attribute.

Name | Description
--- | ---
name | Name of the process
stimuli | Reference to one or more Stimuli representing the different types of possible activations of this Process
activityGraph | List of activities (e.g. runnable calls, label accesses). This specifies the behavior of the process. The objects will be executed in the same order they are stored in the list.
preemption | Defines the preemption of a task by higher priority tasks.
multipleTaskActivationLimit | Defines the maximum number of existing instances from the same task at any time, which is checked for load limitation reasons when a task is activated. If the multipleTaskActivationLimit is exeeded, the activation is ignored. See the “BTF Example” (User Guide > Examples) for an multipleTaskActivationLimit of 3.

### Runnables and Services

Both elements, runnables and services, are an abstraction of an executable entity. They are both represented by the Runnable element and are distinguished by using the service attribute of type boolean.
Unlike tasks, which are activated in the context for the operating system, runnables are called by tasks or other runnables.

Runnables and Services in the AMALTHEA model can have call parameters. It is possible to specify the arguments of a service call and potential data dependencies. Based on these types of information, an additional analysis can be performed.

### Runnables

The next picture shows the general structure of the Runnable element.

Name | Description
--- | ---
callback | True if a runnable is used as a callback
service | True if Runnable element can be seen in a service or global function manner. In more detail, the Runnable is only called from other Runnables and not directly from a Task context.
activations | Although runnables in the simulation can only be called by tasks, it is possible to specify activation patterns for a runnable.
executionCondition | It is possible to specify an execution condition for a runnable (depending on modes).
activityGraph | Top level object containing ActivityGraphItem objects, representing runtime, label accesses, other Runnable accesses. The possibilities are described below.
tags | Can be used to annotate or group special kind of Runnables

### Activity Graph

A ActivityGraph is the root container of ActivityGraphItems. In addition some of the items can also contain sub items. These items are implementing the interface IActivityGraphItemContainer.

The following picture shows the structure of a Activity Graph. The Activity Graph Items are used to define detailed behavior. With the Switches it is possible to define alternative execution paths. The elements of the graph are executed in the order they are stored in the data model.

### Activity Graph Items

The ActivityGraphItems are describing the detailed behavior of a Process or Runnable. This can be either an abstraction of runtime or representing access to other elements like Runnables, Labels and Semaphore. An overview of the different possibilities is given in the next pictures.

#### Groups

A Group is used to structure the ActivityGraphItems. The boolean attribute isOrdered indicates if the execution order of the contained elements is fixed or random.

#### Mode Switch

With the ModeSwitch it is possible to define different execution paths. They can be used like if-else or switch-case statements in a programming language. A ModeSwitch uses the value of mode labels to decide which entry has to be executed. The first fulfilled condition determines the path to execute.
A ModeSwitchEntry object is used to represent an execution path. A mode condition is defined for each entry (via ModeConditionDisjunction).
At the ModeSwitch it is also possible to define a default path, which is executed if no condition of the ModeSwitchEntries fits to the current mode settings.

#### Probability Switch

Each entry (path) of a ProbabilitySwitch has a probability-value. As the name indicates, this is the value that defines the probability that the path is executed. It is computed as a fraction of its value divided by the sum of all ProbabilitySwitchEntries in the surrounding switch.

#### Ticks

Ticks allow to specify the required execution “time” in a basic way. They are the equivalent of cycles in the hardware domain and the execution time can easily be calculated if the frequency of the executing ProcessingUnit (PU) is known.
Detailed definition: see Ticks

#### Execution Need

ExecutionNeed allows to specify the required execution “time” in a more abstract way. Multiple NeedEntries can be used to specify execution characteristics. There is a map of default entries and (optional) maps of entries for specific hardware types (e.g. FPGA). These extended entries are also implemented as a map with a processing unit definition as the key.

A simple approach (equivalent to the RunnableInstructions in older versions of the AMALTHEA model) is the specification of the “number of generic instructions” that have to be executed. Together with the hardware feature “instructions per cycle (IPC)” and the frequency of a processing unit it permits the calculation of the execution time on a specific processing unit.

With the generic concept of ExecutionNeeds it is also possible to describe more detailed characteristics, e.g. instruction mixes of floating point operations, integer operations, load/store operations, etc., or any other relevant aspect.

#### Calls and AUTOSAR communication

Name | Description
--- | ---
RunnableCall | The activation of another Runnable.
SenderReceiverCommunication | An abstract description for sender-receiver-communication (it can be read or write).
ServerCall | An abstract description for client/server communication. It refers to a required runnable that describes the called server operation
SynchronousServerCall | A synchronous server call with defined waiting behaviour.
AsynchronousServerCall | An asynchronous server call with (optional) specification of result runnable.
GetResultsServerCall | Get the result of a previous asynchronous server call (with defined blocking behaviour).

#### Label Access

Name | Description
--- | ---
access | The type of access is represented using the values of LabelAccessEnum.
data | Describes the access to an existent Label (set as reference).
dataStability | Describes the data stability needs. If set, it overwrites the label settings, otherwise it inherits them (see OS Data Consistency).

implementation

Describes how a label access is implemented:

- explicit: also known as “direct”
- implicit: also known as "optimized"
- timed

statistic | Defines the frequency of the label access.

transmissionPolicy

The following attributes reflect the computing demand (time) depending on data:

- chunkSize: Size of a part of an element, maximum is the element size.
- chunkProcessingTicks: Number of ticks that will be executed to process one chunk (algorithmic overhead).

The next attribute specifies the amount of data actually accessed by a runnable (required to analyze memory bandwidth demands):

- transmitRatio: Specify the ratio of each element that is actually transmitted by the runnable in percent. Value must be between [0, 1], default value is 1.0 .

#### Channel Access

Common attributes:

Name | Description
--- | ---
data | Describes the access ( ChannelSend or ChannelReceive) to an existent Channel (set as reference).
elements | Maximum number of elements that are transmitted.

transmissionPolicy

The following attributes reflect computing demand (time) depending on data:

- chunkSize: Size of a part of an element, maximum is the element size.
- chunkProcessingTicks: Number of ticks that will be executed to process one chunk (algorithmic overhead).

The next attribute specifies the amount of data actually accessed by a runnable (required to analyze memory bandwidth demands):

- transmitRatio: Specify the ratio of each element that is actually transmitted by the runnable in percent. Value must be between [0, 1], default value is 1.0 .

Receive attributes:

Name | Description
--- | ---

receiveOperation

The type of an operation is defined by LIFO or FIFO, Read or Take:

- LIFO: last-in, first-out
- FIFO: first-in, first-out
- Read: reads elements (without modifying the channel content)
- Take: removes the received elements

elementIndex | Position (index) in channel at which the operation is effective. Zero is the default and denotes the oldest (FIFO) or newest element (LIFO) in the channel.
lowerBound | Minimum number of elements returned by the operation. The value must be in the range [0,n], with n is the maximum number of elements that are received. Default value is n.
dataMustBeNew | Specify if the operation must only return elements that are not previously read by the runnable. Default value is false.

#### Semaphore Access

Name | Description
--- | ---
SemaphoreAccess | Represents an access of a Semaphore. The type of access is defined using the SemaphoreAccessEnum values. The Semaphore itself is set as a reference to an existent one.
access | Defines the type of access (request, exclusive, release).
waitingBehaviour | Defines if the process is blocking the core when it waits (active) or not (passive).

#### Mode Label Access

Name | Description
--- | ---

ModeLabelAccess

Describes the access to an existing ModeLabel (set as reference). The type of access is represented using the values of ModeLabelAccessEnum:

- read: indicates that the behavior of the runnable is influenced by the current value of the ModeLabel.
- set: represents the change of a mode label. The defined value is set.
- increment / decrement: changes a mode label. The value is increased / decreased by step. In case of an EnumMode the next / previous literal is set (according to step limited by the range of literals).

- ModeLabelAccess: The value string must be a valid element of the corresponding Mode!

#### Custom Event Trigger

The Custom Event Trigger references an event of type Custom Event. The execution of a Custom Event Trigger entry triggers the corresponding event that can be observed by an Event Stimulus.

#### Enforced Migration

Each task is controlled by at least one task scheduler. A task scheduler is the resource owner of one or multiple processor cores (The task scheduler decides on which of its cores the task is executed). The Enforced Migration forces the task to switch to another task scheduler. Therefore the Enforced Migration entry contains a reference to the new task scheduler.

This element is used as a short notation to simplify the simulation of different design possibilities. It should normally be modeled as two separate tasks and an inter process trigger.

#### Inter Process Trigger

The Inter Process Trigger references a stimulus of type Inter Process Stimulus. The execution of an Inter Process Trigger entry triggers the processes that are mapped to this stimulus.

#### Schedule Point

At a Schedule Point, the process calls the scheduler that currently administrates it. This is used for cooperative task scheduling (see OSEK Specification 2.2.3, 2005).

#### Terminate Process

If a Terminate Process is reached during the execution of a Activity Graph, the Task or ISR terminates immediately. It is not required to insert this element at the end of a Activity Graph. It can be used to define an execution path (by using Switches) that terminates a process.

#### Wait/Clear/Set Event

The AMALTHEA Software Model contains a list of OS-Event objects. These can be used for task synchronization. Elements are Wait Event, Clear Event and Set Event.

With Wait Event the process waits for a number of events (defined in the Event Mask) to be set. Here it can be defined if the process waits just for one of the OS-Events (maskType = OR) or for all of them (maskType = AND). The waiting behaviour defines if the process is blocking the core when it waits (active) or not (passive).

Set Event sets/fires a list of OS-Events. Here it is possible to define a context for the OS-Event. If a process is referenced, then the OS-Events are set just for this process.

The execution of a Clear Event entry unsets all referenced OS-Events.

For more information about OS-Events, see the OSEK Specification 2.2.3, 2005.

#### Statistical Values

It is possible to add to different elements (as shown in the picture above) different types of statistical values. These values can be used to describe in more detail the following behaviors:

- RunEntityCallStatistic: Can be used to describe in more detail the dynamic call behavior of a RunnableCall. The value is representing how often the call is performed.
- LabelAccessStatistic: Describes in more detail the dynamic behavior accessing a Label by having cache misses or how often a read/write is performed.

### Modes

The next diagram shows the overall picture, the sub chapters describe the details.

Modes are mainly used in Mode Conditions to describe the conditional execution of a ModeSwitchEntry, a Runnable or a Stimulus.

#### Modes and Mode Labels

The Mode element denotes the type and the possible values of a specific system state. The subclasses EnumMode and NumericMode describe the values that are allowed for the corresponding ModeLabel. In case of a EnumMode the initialValue has to be the name of one of the contained ModeLiterals. For NumericMode the initialValue has to be the string representation of an integer.

The Mode Label element represents a concrete representation of a specific Mode. Is is described using the following attributes:

Name | Description
--- | ---
name | Name of the mode label
displayName | In addition to the name attribute, which must be unique, a mode label can also be described by an additional and optional display name. The displayName attribute must not be unique. It can be used for example to represent specification data, which can be different from the unique name (like a symbol) of an available software build.
mode | Reference to the corresponding Mode definition
initialValue | String representation of the initial value

#### Mode Changes

The value of the mode label can be changed using the set-mode-value-list of a Stimulus.

Another possibility is a write access within a Runnable via a Mode Label Access.

#### Mode Conditions

Mode conditions allow to specify dedicated states of the overall system.
Depending on the condition evaluation (via isSatisfiedBy()) switches can be executed or stimuli can be influenced.
The ModeValueMap represents the system state that has to be provided as an external input, e.g. from a simulation or analysis tool.

### Process Prototypes

In addition to the Task elements, the AMALTHEA model contains an element process prototype.
This prototype can be used to define raw data of a task. It can be used to specify access to
labels (read, write) or other runnables/functions as possible with the normal task, but not the
order of the access. These prototypes are then processed by different algorithms. The algorithms are creating the tasks, are filling, verifying or modifying the data based on their different checks. The final result of this processing are tasks, which are corresponding to the data of the prototypes.

These tasks are representing the current state and can be further processed, for example to generate code or further simulation. With the process prototypes available in the model, it is possible to define the structure of the software in an early development phase. The implementation at that moment is open and not yet completed, but the general idea can be verified.
Another issue can be the distribution to a multi-core system, coming from a single-core system. Therefore the activity graph can be analyzed and computed to get the right order and parallelization of the elements and dependencies.

### Process Chains

The following figure shows the structure which describes Process Chains in the AMALTHEA software model. A process chain is used to group task and isrs together which are executing after each other and represent an end-to-end data processing path. The processes inside a process chain are connected via Inter Process Activations.

The following attributes are describing a process chain:

Name | Description
--- | ---
name | Name of the process chain
processes | List of tasks and isrs which are included in the process chain

### Custom Entities

The CustomEntity element defines a way to add not yet available elements of the software model in a generic way. The only contained attribute defines the type of the entity by setting it as a String. Additional properties can be set using the CustomAttributes.

### Section

Section (Virtual Memory Section) is used to group the memory elements (Labels, Runnables). This is achieved by associating the Section element to Label & Runnable elements

Below are properties of Section element:

- name
- asilLevel

With this type of information available, the complexity of mapping software components to memories can be reduced. The next picture gives an overview about the general idea of the mapping with Sections.

### Data Dependencies and Runnable Parameters

#### Overview

The purpose of following model elements is to describe a high level data flow. Parameters of runnables (or services) and specific call arguments allow to model a behavior that depends on the call tree but the detailed computation and the control flow within a runnable are not taken into account. Therefore only “potential” influences are modeled. The following picture shows this data flow with dashed lines.

#### Elements with data dependency

The data flow is specified with “depends on” references. Elements that can specify a dependency are:

- LabelAccess of type "WRITE"
- CallArgument that refers to an “IN” (or “INOUT”) parameter
- RunnableParameter with direction “OUT” (or “INOUT”)

#### Data Dependency

A data dependency defines the elements that can influence a value that is written or transferred. Possible origins are:

- Label
- RunnableParameter with direction “IN” (or “INOUT”)
- CallArgument that refers to an “OUT” (or “INOUT”) parameter