plugins/org.eclipse.app4mc.amalthea.model.help/docu/model_hw.textile

h2. Hardware Model

The AMALTHEA hardware model is used to describe hardware systems which usually consist of several hierarchical elements which contain processing units, memories, connections etc. It is accessible through the __HWModel__ element and contains following top level elements:

* Definitions
* Domains
* Features
* Structures


h3. Class Diagrams

h4. Hardware model elements

!(scale)../pictures/model_hw_main.png!

h4. Hardware definitions and features

!(scale)../pictures/model_hw_definition.png!

h4. Hardware modules and access elements

!(scale)../pictures/model_hw_module.png!

h4. Hardware paths and destinations

!(scale)../pictures/model_hw_access.png!


h3. Element description

The following tables describe the different model elements and their attributes in detail. For several elements short examples are attached.

h4. HwModel

The _HwModel_ class is the root element of the hardware model. It always contains one or multiple _HwStructures, PowerDomains_ and _FrequencyDomains_ and optionally different _HWFeaturesCategories_ for the _HwModule_ definitions.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the hardware model |
| Definitions | Containment | HwDefinition | * | Definitions of ProcessingUnits, Memories, Caches and ConnectionHandlers |
| Domains | Containment | HwDomain | * | Frequency- and PowerDomains |
| FeatureCategories | Containment | HwFeatureCategory |* | FeatureCategory for the HwModel including HwFeatures|
| Structures | Containment | HwStructure |* | Hierarchical structure of the hardware model |


h4. HwDefinition

Additional information about the definition concept in general can be found in the User Guide (see <notextile><a href="./user_hw.html#user-hw-overview">General Hardware Model Overview</a></notextile>).


h5. ProcessingUnitDefinition

For specifying a compute resource a _ProcessingUnitDefinition_ is created, which is afterwards referenced by the number of _ProcessingUnit_ instances of this kind. A _ProcessingUnitDefinition_ can reference multiple _HwFeatures_ to express different costs for different operations but only one _HwFeature_ per _HwFeatureCategory_.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the processing unit definition |
| PuType | Enum | PuType | 1 | Type of the processing unit e.g. (Core, GPU, etc.) |
| Features | Reference | HwFeature | * | Hardware features of the definition |


h5. MemoryDefinition

For specifying a memory, a _MemoryDefinition_ is created, which is afterwards referenced by the number of _Memory_ instances of this kind.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the memory definition |
| AccessLatency | Containment | HwLatency | 1 | Constant or distribution of access latency in cycles |
| DataRate | Containment | DataRate | 1 | Max. data rate for the memory |
| Size | Containment | Size | 1 | Size of the memory |
| MemoryType | Enum | MemoryType | 1 | type of the memory (e.g. DRAM, Flash, SRAM, PCM) |


h5. CacheDefinition

For specifying a cache, a _CacheDefinition_ is created, which is afterwards referenced by the number of _Cache_ instances of this kind.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the memory definition |
| AccessLatency | Containment | HwLatency | 1 | Constant or distribution of access latency in cycles |
| Size | Containment | Size | 1 | Size of the memory |
| CacheType | Enum | CacheType | 1 | Cache type (e.g. data, instruction) |
| WriteStrategy | Enum | WriteStrategy | 1 | Cache write strategy (e.g. write-back) |
| Coherency | Bool | Bool | 1 | Cache coherency (default = false) |
| Exclusive | Bool | Bool | 1 | Exclusive cache (default = false) |
| Line Size | Int | Int | 1 | Line size in bits |
| Hit Rate | Double | Double | 1 | Percentage hit rate of the cache(default = 0.0) |
| NWays | Int | Int | 1 | N ways associative (default = 0) |


h5. ConnectionHandlerDefinition

For specifying a bus or Interconnect etc., a _ConnectionHandlerDefinition_ is created, which is afterwards referenced by the number of _ConnectionHandler_ instances of this kind.

!(scale)../pictures/hardware/hw_connection_handler_parallel_accesses_1.png!

The figures shows an example of the attribute _MaxConcurrentTransfers_ with the default value 1. This means that all _ConnectionHandlers_ which are referencing this _ConnectionHandlerDefinition_ can only handle 1 active transfer request at a time. All other requests have to wait until the current transfers has finished.

The next figure shows an example with a number of _MaxConcurrentTransfers_ of 3. In this case the _ConnectionHandler_ can handle up to 3 concurrent requests.

!(scale)../pictures/hardware/hw_connection_handler_parallel_accesses_3.png!

The value for _MaxConcurrentTransfers_ has to be smaller or equal then the min(initiator ports, responder ports).

The values for _DataRate_, _ReadLatency_, and WriteLatency are default values for all _ConnectionHandlers_ of this kind. For a specific _InternalConnection_ in a _ConnectionHandler_ instance other values can be assigned.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the memory definition |
| SchedPolicy | Enum | SchedPolicy | 1 | Enumeration of different scheduling policies |
| ReadLatency | Containment | HwLatency | 1 | Constant or distribution in cycles for a read access |
| WriteLatency | Containment | HwLatency | 1 | Constant or distribution in cycles for a write access |
| DataRate | Containment | DataRate | 1 | Max. data rate of the connection (value and unit) |
| MaxBurstSize | Int | Int | 1 | Maximum burst size of a ConnectionHandler (default = 1) |
| MaxConcurrentTransfers | Int | Int | 1 | Number of concurrent transfers from different initiator to responder ports (default = 1) |


h4. HwStructure


A _HwStructure_ is a hierarchical element which can contain all kind of _HwModules_, _HwConnections_ and other _HwStructures_. Different _HwStructures_ can be connected via one or more _HwPorts_ with other structures or modules of a top level _HwStructures_. By combining different _HwStructures_ any kind of hierarchical system can be expressed. By setting the structure type attribute (e.g. Cluster, ECU) the structural level in the hardware is directly expressible.

!(scale)../pictures/hardware/hw_structure_example.png!

The figure shows an example for creating a hierarchy within an E/E-architecture. The _HwStructure System_ (which is called "System") is created as top level structure within the HwModel. It contains three other structures which represents different ECUs. The structures are connected via _HwPorts_, _HwConnections_ and a _ConnectionHandler_. Usually structures in the model can be viewed as black boxes which can be connected via _HwPorts_. _ECU3_ allows a look inside, where additional structures for two SoCs are visible.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the hardware structure |
| StructureType | Enum | StructureType | 1 | Defines the type of the structure (e.g. ECU) |
| Modules | Containment | HwModule | * | Modules of the structure (e.g. Memory) |
| Ports | Containment | HwPort | * | Ports to connect the structure (always delegated Ports) |
| Structures | Containment | HwStructure | * | Hardware structure to build hierarchical designs |
| Connections | Containment | HwConnection | * | Connections within a structure |


h4. HwDomain


!(scale)../pictures/hardware/hw_domain_example.png!

The figure shows an example for _HwDomain_ (_FrequencyDomain_ and a _PowerDomain_). They are always created at the top level in the root element _HwModel_. Every basic component is able to reference a _FrequencyDomain_ and a _PowerDomain_. _(Note: The link between domains and modules are only references, there are no visible connections inside the model)_


h5. FrequencyDomain

A _FrequencyDomain_ is inherited from _HwDomain_. This element describes a frequency domain which can be referenced by all elements of the type _HwModule_ to define the default frequency value for operation. In future the _FrequencyDomain_ should also contain possibleValues which should specify the different frequencies for different operation modes.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the frequency domain |
| DefaultValue | Containment | Frequency | 1 | Default frequency value |
| Clock Gating | Boolean | Boolean | 1 | Possibility to power down the domain (default = false) |


h5. PowerDomain

A _PowerDomain_ is inherited from _HwDomain_. This element describes a power domain which can be referenced by all elements of the type _HwModule_, to define the default voltage value for operation. In future the _PowerDomain_ should also contain possibleValues which should specify the different voltages for different operation modes.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the power domain |
| DefaultValue | Containment | Voltage | 1 | Default voltage value |
| PowerGating | Boolean | Boolean | 1 | Possibility to power down the domain (default = false) |


h4. HwFeature


A _HwFeature_ is an abstract element to represent any kind of special functionality of a _ProcessingUnitDefinition_. _HwFeatures_ could be reused several times by different definitions and organized within _HwFeatureCategories_. Currently this _HwFeatureCategories_ are directly referenced out of the Software Model in future the cost function (_Recipes_) of an algorithm will be placed in an additional intermediate layer.
More information can be found in (see <notextile><a href="./user_hw.html#user-hw">Hardware Concepts</a></notextile>).

_NOTE: The concepts "Recipe" and "Hardware Features" are work in progress. Changes to the already implemented HwFeatures are probable._

!(scale)../pictures/hardware/hw_feature_example.png!

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the hardware feature |
| Value | Containment | Value | 1 | assigned factor to the corresponding feature |


h5. HwFeatureCategory

The _HwFeatureCategory_ is an element to collect the same kind of _HwFeatures_ with different values.
The _HwFeatureCategories_ can be referenced by the _ExecutionNeeds_ in the Software Model.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the hardware feature |
| Type | Enum | HwFeatureType | 1 | Type to express the purpose of the feature (performance, power, performance_and_power) |
| Description | String | String | 1 | Textual description of the hardware feature |
| HwFeature | Containment | HwFeature | * | Hardware feature with a factor |



h4. HwModule


h5. ProcessingUnit

A _ProcessingUnit_ is a _HwModule_ that can be used to model a wide set of different hardware components like a GPU, hardware accelerator, CPU, etc. The capability and the functionality of a _ProcessingUnit_ are represented by different _HwFeatures_ within the _ProcessingUnitDefinition_. The _ProcessingUnits_ are the master modules in the model and every _ProcessingUnit_ can has their own access space. The _ProcessingUnit_ can be referenced by _AccessPaths_ and _HwAccessElements_.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the processing unit instance |
| Ports | Containment | HwPort | * | Ports of the component |
| Caches | Containment |Cache | * | Included caches by the Processing Unit e.g. L1 Cache |
| AccessElements | Containment | AccessElement | * | Access element for a specific memory or processing unit |
| FrequencyDomain | Reference | FrequencyDomain | 1 | Frequency domain which supplies the module with a frequency |
| PowerDomain | Reference | PowerDomain | 1 | Power domain which supplies the module with a voltage |
| Definition | Reference | ProcessingUnitDefinition | 1 | Definition with all features for the processing unit instance |


h5. Memory

A _Memory_ is a component of type _HwModule_ to express any kind memory like SRAM (Scratchpads), DRAM, Flash, etc. in the model, caches are modeled separately. The _Memory_ element can be referenced as destination by a _HwAccessElement_.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the memory instance |
| Ports | Containment | HwPort | * | Ports of the component |
| FrequencyDomain | Reference | FrequencyDomain | 1 | Frequency domain which supplies the module with a frequency |
| PowerDomain | Reference | PowerDomain | 1 | Power domain which supplies the module with a voltage |
| Definition | Reference | MemoryDefinition | 1 | Definition with all features for the memory instance |


h5. Cache

A _Cache_ is a component of type _HwModule_ to express the special behavior of a _Cache_. It is used to create cache topologies within a system. The _Cache_ can be referenced by _AccessPaths_ to express if it is a cached or non-cached access. It is also the only _HwModule_ which can be directly contained by a _ProcessingUnit_.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the cache instance |
| Ports | Containment | HwPort | * |Ports of the component |
| FrequencyDomain | Reference | FrequencyDomain | 1 | Frequency domain which supplies the module with a frequency |
| PowerDomain | Reference | PowerDomain | 1 | Power domain which supplies the module with a voltage |
| Definition | Reference | CacheDefinition | 1 | Definition with all features for the cache instance |


h5. ConnectionHandler

A _ConnectionHandler_ is a component of type HwModule which can be used whenever multiple _HwConnections, (HwPorts)_ have to be combined. It is possible to represent whole bus systems or interconnects with a single _ConnectionHandler_, or elements like small routers within a NoC.

!(scale)../pictures/hardware/hw_connection_handler_example.png!

The figure shows an example where a _ConnectionHandler_ is used as an interconnect within a SoC. Optional it is possible to model _InternalConnections_ inside a _ConnectionHandler_ to model explicit or restrict different connections. However it is also possible to use default read and write latencies of the whole _ConnectionHandlerDefinition_, individual latencies can be attached to _InternalConnections_. A short example where a _ConnectionHandler_ is used as a CAN bus is illustrated in the structure example. For detailed models where all modules connected via _HwConnections_ and different _ConnectionHandlers_, the _ConnectionHandlers_ should be the only module where contentions in the hardware model can occur. A _ConnectionHandler_ can be referenced by _HwAccessPaths_.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String |1 | Name of the connection handler instance |
| Ports | Containment | HwPort | * | Ports of the component |
| InternalConnections | Containment | HwConnection | * | Internal connection between the ports |
| FrequencyDomain | Reference | FrequencyDomain | 1 | Frequency domain which supplies the module with a frequency |
| PowerDomain | Reference | PowerDomain | 1 | Power domain which supplies the module with a voltage |
| Definition | Reference | ConnectionHandlerDefinition | 1 | Definition with all features for the connection handler instance |


h4. HwAccessElement

A _HwAccessElement_ can be used to specify the access relationship between two _ProcessingUnits_ or a _ProcessingUnit_ and a _Memory_. With multiple _HwAccessElements_ the whole access or even address space of a _ProcessingUnit_ can be represented. A _HwAccessElement_ represents always the view from a specific _ProcessingUnit_. There exist two different approaches to express latency or a data rate for a _HwAccessElement_: 1. directly using latencies or data rates or 2. modeling the exact path to the destination by attaching a _HwAccessPath_ which references the specific connection elements like _ConnectionHandlers_, _HwConnection_, etc. For the second approach it is also possible to work directly with addresses.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the address element |
| Destination | Reference | HwDestination | 1 | Destination for the processing unit |
| AccessPaths | Containment | HwAccessPath | 1 | Access path to the destination |
| ReadLatency | Containment | HwLatency | 1 | Read latency to the destination |
| WriteLatency | Containment | HwLatency | 1 | Write latency to the destination |
| DataRate | Containment | DataRate | 1 | Max. data rate to the destination |


h4. HwPort

_HwPorts_ are elements which can be connected via _HwConnections_. Every module can contain multiple _HwPorts_. Every communication, input or output is handled via a _HwPort_ of a component. It is only allowed to have one _HwConnection_ per _HwPort_, except the _HwPort_ is categorized as delegated port which means it is just a hierarchical connection between _HwStructures_. In this case the ports can have two _HwConnections_. The second exception is if inside a _ConnectionHandler_, _InternalConnections_ are used.In this case a _HwPort_ can be directed with a _HwConnection_ and _InternalConnections_. The following figure shows an example with delegated _HwPorts_ and _InternalConnections_.

!(scale)../pictures/hardware/hw_port_example.png!

In case the _BitWidth_ becomes important (e.g. to calculate the amount of data which is transfered over an _ConnectionHandler_) the minimum _BitWidth_ of all included Ports have to be accounted.

For _HwPorts_ it's always possible to select if the port is an _initiator_ or a _responder_ port. The following example shows that an initiator port is always connected to a responder port (comparable to TLM modeling).

!(scale)../pictures/hardware/hw_port_example_i_r.png!

In case of a delegated port (which is used as hierarchical port at a _HwStructure_) the _PortType_ of the module inside the structure is reflected. The following figure shows four different examples. The ports which are delegated are marked grey.

!(scale)../pictures/hardware/hw_port_example_i_r_with_delegated_ports.png!

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the hardware port |
| BitWidth | Int | Int | 1 | Bit width e.g. 32 bit (default = 0) |
| Priority | Int | Int | 1 | Priority of the hardware port (default = 0) |
| Type | Enum | PortType | 1 | Port type (initiator, responder) |
| Delegated | Bool | Bool | 1 | Delegated ports are hierarchical structure ports |
| PortInterface | Enum | PortInterface | 1 | Type to express special interfaces for validation |


h4. HwConnection

A _HwConnection_ is an element to model structural connections between two _HwPorts_. _HwConnections_ are always placed within _HwStructures_. It is possible to directly annotate a read and write latency at a _HwConnection_. _HwConnections_ can be referenced by _HwAccessPaths_. The HwConnection do not have a reference to a _FrequencyDomain_, the frequency is always provided by the element which is in front of the _HwConnection_ in the _HwAccessPath_.

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String |1 | Name of the hardware connection |
| Port1 | Reference | HwPort | 1 | Port1 for the connection |
| Port2 | Reference | HwPort | 1 | Port2 for the connection |
| ReadLatency | Containment | HwLatency | 1 | Constant or distribution in cycles for a read access |
| WriteLatency | Containment | HwLatency | 1 | Constant or distribution in cycles for a write access |
| DataRate | Containment | DataRate | 1 | Max. data rate of the connection (value and unit) |


h4. HwAccessPath

A _HwAccessPath_ is an element to describe the connection route of a _ProcessingUnit_ to its destination (_Memory_ or _ProcessingUnit_). The _HwAccessPath_ is defined through an ordered list of IPaths interface elements (_HWConnections, Caches_ and _ConnectionHandlers_) and is a containment of an _HwAccessElement_. The figure shows an example of an _HwAccessPath_, how a _ProcessingUnit_ is connected via two _HwConnections_ and a _ConnectionHandler_ with a _Memory_.

!(scale)../pictures/hardware/hw_access_path_example.png!

In the following example the possible memOffset attribute is explained. Every _ProcessingUnit_ can access a _Memory_ or other _ProcessingUnit_ over a different address. The size of the _Memory_ has to be equal or greater than _endAddress_ minus the _startAddress_.

* memory_size >= endAddress - startAddress

In the case the the _ProcessingUnit_ should not start at address 0 (from the memory point of view) the _memOffset_ attribute can be used. With help of this attribute the access area for the memory can be changed, the following figure shows an example.

!(scale)../pictures/hardware/hw_memory_address_example.png!

table(classic).
|_. Attribute |_. Type |_. Value |_. Mul. |_. Description |
| Name | String | String | 1 | Name of the hardware access path |
| PathElements | Reference | HwPath | * |Path elements for the access path |
| StartAddress | Long | Long | 1 | Start address for the memory |
| EndAddress | Long | Long | 1 | End address for the memory |
| MemOffset | Long | Long | 1 | Offset for accessing only a partition of a memory |

h4. Enumerations

In the following all enums are listed. In the case an enum is used by any class the default value of that enum is always _undefined_. That means that in case of an enum there are no default values for interfaces or other kind of types. Moreover only new enums are explicitly mentioned in this report. Enums and classes which are already part of the existing Amalthea meta model are not described.

*StructureType:*

* <notextile>_undefined_</notextile>, System, ECU, Microcontroller, SoC, Cluster, Group, Array, Area, Region

*CacheType:*

* <notextile>_undefined_</notextile>, instruction, data, unified

*VoltageUnit:*

* <notextile>_undefined_</notextile>, V, mV, uV

*PortType:*

* <notextile>_undefined_</notextile>, initiator, responder

*SchedPolicy:*

* <notextile>_undefined_</notextile>, RoundRobin, FCFS, PriorityBased

*WriteStrategy:*

* <notextile>_undefined_</notextile>, none, writeback, writethrough

*PuType:*

* <notextile>_undefined_</notextile>, GPU, CPU, Accelerator

*PortInterfaces:*

* <notextile>_undefined_</notextile>, custom, can, flexray, lin, most, ethernet, spi, i2c, axi, ahb, apb, swr

*HwFeatureType:*

* <notextile>_undefined_</notextile>, performance, power, performance_and_power

*MemoryType:*
* <notextile>_undefined_</notextile>, DRAM, SRAM, FLASH, PCM