= Hardware Platform Definition =

[[PageOutline]]

ALMOS-MKH has been designed to support clustered manycore architectures. It can be 32 bits cores (such as the MIPS32 based TSAR architecture), or 64 bits cores (such as the multi-cores Intel/AMD architectures). Each cluster containing at least one core, one physical memory bank, and an interrupt controller unit will host one kernel instance. 

All relevant parameters describing the clustered multi-core architecture must be defined in the binary '''arch_info.bin''' file.
This binary file is exploited by the ALMOS-MKH boot-loader to configure ALMOS-MK. It can be generated by a specific  '''arch_info.py''' python scrip, for each target architecture.

== __1)  Cluster and cores identification__  ==

=== 1.1) Cluster identification ===

To identify a cluster in the clustered architecture, ALMOS-MKH uses an unique cluster identifier '''cxy'''. ALMOS-MK does not make any
assumption on the clusters topology, but makes the assumption that the '''cxy''' binary value can be directly concatenated to the local physical address (address inside a cluster) to build a global physical address. Warning: The cluster identifier '''cxy''' is NOT a continuous index, and cannot be used to index a cluster array.

The size of the local physical address space (inside a cluster) is defined by a global parameter, that is the number of bits in a local physical address. The value of this parameter is 32 in architectures using 32 bits cores, but it can be larger in architectures using 64 bits cores. A physical address is coded on 64 bits in ALMOS-MKH.

Note : In architectures where the clusters are organized as a 2D mesh topology, is is generally possible to derive the [x,y] cluster coordinates from the '''cxy''' cluster identifier, and ALMOS-MK can use it to optimize placement and improve locality, but this optimisation is NOT mandatory, and ALMOS-MK supports architectures where the set of cluster is simply a linear vector of clusters.

=== 1.2) Core identification ===

ALMOS-MK makes the assumption that each physical core contains an hardware addressable register defining an unique global identifier (called '''gid''') with the only constraint that two different cores have two different '''gid'''.

To identify a specific core in the clustered architecture, ALMOS-MK does not use directly this physical '''gid''', but uses a composite index '''[cxy,lid]''', where '''cxy''' is the cluster identifier, and '''lid''' is a local core index. This '''lid''' index is a continuous index in [0,N-1], where N can depend on the cluster, but cannot be larger than the global parameter CONFIG_MAX_CORE_PER_CLUSTER_NR.

The association of a composite index '''[cx,lid]''' to a global physical identifier '''gid''', is defined in the '''arch_info.bin''' file.

== __2) Hardware architecture description__ ==

For ALMOS-MKH, the target hardware architecture is described in the binary file '''arch_info.bin'''.
This file is loaded from disk by the ALMOS-MKH boot-loader. 

=== 2.1) General assumptions ===

 * Each cluster contains a variable number of cores, a variable number of peripherals, and a physical memory bank.
 * The number of clusters is variable (can be one). 
 * The cluster topology is variable (2D mesh or vector)
 * The number of cores per cluster is variable (can be zero). 
 * The number of addressable peripherals per cluster is variable.
 * The size of the physical memory bank per cluster is variable.
 * Each cluster cover a fixed size segment in the physical address space.

 === 2.2) the arch_info_t structure ===

The binary file '''arch_info.bin''' is a BLOB containing the binary form of the C arch_info_t structure.
This structure has a three levels hierarchical organisation: 
 *  the architecture contains a variable number of clusters.
 *  each cluster contains a variable number of cores and a variable number of addressable devices.
 *  some devices contains a variable number of input IRQs.

An addressable device can be a physical memory bank, or a peripheral containing addressable registers.

The '''arch_info.bin''' BLOB is organised as the concatenation of a fixed size header, and 4 variable size arrays of fixed size objects:
 *  archinfo_cluster_t  cluster[]  
 *  archinfo_core_t     core[]  
 *  archinfo_device_t   device[]
 *  archinfo_irq_t      irq[]   

These four C structures are defined in the  [source:almos-work/tools/arch_info/arch_info.h arch_info.h] file. The access functions are defined in the  [source:almos-work/tools/arch_info/arch_info.c arch_info.c] file. 

== __3) The python script__ ==

This section defines the python constructs that can be used to generate  the '''arch_info.bin''' binary file. 
These Python classes are defined in the [source:soft/almos-work/tools/python/genarch.py genarch.py] file.

The target hardware architecture must be defined in the ''arch.py'' file , you must use the following constructors:

=== 3.1) architecture  ===

The Archi( ) constructor build an ''archi'' object and defines the target architecture general parameters:

|| '''name'''               || target architecture name ||
|| '''x_size'''              || number of clusters in a row (for a 2D mesh) ||
|| '''y_size'''              || number of clusters in a column (for a 2D mesh) ||              
|| '''x_width'''           || number of bits to encode X coordinate in CXY  ||
|| '''y_width'''            || number of bits to encode Y coordinate in CXY  ||
|| '''cores_max'''      || max number of cores per cluster ||     
|| '''cluster_span'''     || number of bits in local physical address ||  
|| '''irq_per_proc'''     || number of IRQ lines between XCU and one core || 
|| '''use_ramdisk'''     || Boolean true if the architecture contains a RamDisk ||
|| '''io_cxy'''               || io_cluster identifier ||         
|| '''boot_cxy'''           || boot_cluster identifier ||            
|| '''reset_address'''   || physical base address of the ROM containing the preloader code ||

=== 3.2) Processor core ===

The '''archi.addProc( )''' construct adds one processor core in a cluster. It associates a core composite index (cry, lid) to the core hardware index, and has has the following arguments:
|| '''cxy'''  || cluster identifier ||
|| '''lid'''    ||  local core index ||
|| '''gid'''   || core hardware identifier ||

=== 3.3) Physical memory bank ===

The '''archi.addRam( )''' construct adds one physical memory segment in a cluster. It has the following arguments:
|| '''cxy'''        || cluster identifier ||
|| '''base'''       || local physical base address ||
|| '''size'''        || segment size (bytes) ||

=== 3.4) Peripherals ===

The '''archi.addDevive( )''' construct adds one peripheral in a cluster. ALMOS-MK supports multi-channels peripherals.
ALMOS-MK supports multi-channels peripherals.
This construct has the following arguments:
|| '''cxy'''         || cluster identifier ||
|| '''base'''       || local physical base address ||
|| '''size'''        || segment size (bytes) ||
|| '''ptype'''     || Peripheral type ||
|| '''channels''' || number of channels for multi-channels peripherals ||
|| '''arg0'''        || optional argument depending on peripheral type ||
|| '''arg1'''        || optional argument depending on peripheral type ||
|| '''arg2'''          || optional argument depending on peripheral type ||
|| '''arg3'''          || optional argument depending on peripheral type ||

The peripheral type defines actually a composite index containing a functional type (func-type), and an implementation type (impl_type).
The supported peripheral types are defined in the [source:almos-work/tools/arch_info/arch_classes.py arch_classes.py] file.

The following peripheral components require specific arguments with the following semantic:
||               || Frame Buffer                    || Interrupt controller      || Generic DMA Controller               ||
|| ptype     ||   FBF                                 ||   XCU                           ||   MWR                                         ||
|| arg0       || number of pixels per line || Number of HWI inputs || number of TO_COPROC ports      ||
|| arg1       || number of lines                || Number of PTI inputs  || number of FROM_COPROC ports  ||
|| arg2       || unused                             || Number of WTI inputs  || number of CONFIG registers       ||
|| arg3       || unused                             || Number of IRQ outputs  || number of STATUS registers       ||

Hardware coprocessors using the Generic DMA controller to access memory are described as peripherals. They must be defined with the MWR ''func_ptype'' argument, and the ''impl_type'' argument defines the coprocessor type. 

=== 3.5) Interrupt line ===

The '''archi.addIrq()''' construct is used to describe the hardware interrupts routing from an output interrupt port in a physical peripheral, to an input interrupt port in an interrupt concentrator. This construct adds one input IRQ line to an XCU peripheral, or to a PIC peripheral. It has the following arguments:
|| '''dst_dev'''   || destination device (XCU or PIC)  ||
|| '''index'''    || input port index in destination device ||
|| '''src_dev'''  || source device ||
|| '''channel'''  || source device channel (default value is 0) ||
|| '''is_rx''' || source device direction (default value is False) ||


== __4) The boot_info_t structure__ ==

The ALMOS-MKH boot-loader  uses the informations found in '''arch_info.bin''' to build one '''boot_info_t''' structure in each cluster. This generic  '''boot_info_t''' structure is used by the kernel to build in each cluster its own representation of the hardware.
Therefore, the '''boot_info_t''' structure defines the generic (hardware independent) interface between the hardware specific boot-loader and the kernel.  

It is defined in the [source:almos-work/tools/arch_info/boot_info.h boot_info.h] file.