= GIET-VM / Context Handler =

[[PageOutline]]

The [source:soft/giet_vm/giet_kernel/ctx_handler.c ctx_handler.c] and [source:soft/giet_vm/giet_kernel/ctx_handler.h ctx_handler.h] files define the data structure and functions used to handle threads contexts. They are prefixed by "_" to remind that they can only be executed by a processor in kernel mode.


== __thread context definition__ ==

A thread context is an array of 64 words = 256 bytes. 
It contains copies of processor registers (when the thread is preempted):
 * GPR[i] : generally stored in slot (i). $0, $26 & $27 are not saved.
 * HI & LO registers : used by multiply/divide instructions.
 * CP0 registers : EPC, SR, CR, BVAR 
 * CP2 registers : PTPR 

It contains some general informations associated to the task:
 * TTY   : TTY channel allocated to the task
 * NIC_RX  : NIC_RX channel allocated to the task 
 * NIC_TX  : NIC_TX channel allocated to the task
 * CMA_RX  : CMA channel for NIC_RX allocated to the task
 * CMA_TX  : CMA channel for NIC_TX allocated to the task
 * CBA_FB   : CMA channel for FBF display allocated to the task
 * HBA  : HBA channel local index
 * TIM  : TIM channel local index
 * PTAB  : page table virtual base address 
 * LTID  : Task local index (in scheduler)
 * VSID  : Virtual space index
 * N0RUN    : bit-vector defining the task state ( blocked if non zero ) 
 * TRDID  : Thread index (in vspace)
 * SIGNAL  : bit-vector (inter-tasks signalisation)
 * ENTRY  : Virtual address of task entry point
 * COPROC  : cluster_xy defines the coordinates of coprocessor allocated to the thread

|| [0] ***   || [8]   $8    || [16] $16   || [24] $24  || [32] EPC    || [40] TTY         || [48] TRDID      ||
|| [1] $1    || [9]   $9    || [17] $17  || [25] $25  || [33] CR      || [41] CMA_FB  || [49] GTID        ||
|| [2] $2    || [10] $10  || [18] $18  || [26]  LO   || [34] SR      || [42] CMA_RX  || [50] NORUN   ||
|| [3] $3    || [11] $11  || [19] $19  || [27]  HI    || [35] BVAR  || [43] CMA_TX  || [51] COPROC ||
|| [4] $4    || [12] $12  || [20] $20  || [28] $28   || [36] PTAB  || [44] NIC_RX   || [52] ENTRY     ||
|| [5] $5    || [13] $13  || [21] $21  || [29] SP    || [37] LTID    || [45] NIC_TX   || [53] SIGNAL    ||
|| [6] $6    || [14] $14  || [22] $22  || [30] $30   || [38] VSID   || [46] TIM         || [54] ***            ||   
|| [7] $7    || [15] $15  || [23] $23  || [31] RA    || [39] PTPR  || [47] HBA        || [55] ***            ||

== __thread states__ ==

A thread is statically allocated to a physical processor, as defined in the mapping, and the GIET-VM does not support thread migration. There is one scheduler per processor, and the max number of threads on one single processor cannot be larger than 13.  The giet VM supports both user threads, that can dymamically activated by the applications using the POSIX threads API, and kernel threads that are statically created at kernel init, to support background tasks.

Both User and Kernel threads can be in three different states:
 * '''RUNNING''' the thread is currently executed.
 * '''RUNNABLE''' the thread is not running, but can be selected for execution at the next TICK. 
 * '''BLOCKED''' the thread is blocked, waiting on a condition defined in the NORUN context slot.

The various blocking causes are defined below:
|| nmnemonic                || cause                          ||
|| NORUN_MASK_THREAD        || thread not activated           ||
|| NORUN_MASK_IOC           || blocked on IOC transfer        ||
|| NORUN_MASK_COPROC        || blocked on COPROC transfer     ||
|| NORUN_MASK_TTY           || blocked on TTY_RX transfer     ||
|| NORUN_MASK_NIC_RX_FULL   || blocked on NIC RX FIFO full    ||
|| NORUN_MASK_NIC_RX_EMPTY  || blocked on NIC TX QUEUE empty  ||
|| NORUN_MASK_NIC_TX_FULL   || blocked on NIC RX QUEUE full   ||
|| NORUN_MASK_NIC_TX_EMPTY  || blocked on NIC TX FIFO empty   ||


== __acccess functions__ ==

 === void '''_ctx_block'''( unsigned int norun_cause ) ===
This function set one (or several) bit(s) in the CTX_NORUN bit-vector of the calling thread, and deschedule the calling thread.
 * '''norun_cause''' : all non-zero bits in this 32 bits word are set.

 === void '''_ctx_unblock'''( unsigned int trdid, unsigned int norun_cause ) ===
This function reset one (or several) bit(s) in the CTX_NORUN bit-vector of the thread identified by the <trdid> argument. This function can be called by an ISR or another thread.
 * '''trdid''' : target thread identifier.
 * '''norun_cause''' : all non-zero bits in this 32 bits word are reset.

 === void '''_ctx_switch'''() ===
This function performs a context switch between the running (calling) thread and  another runnable thread, using a round-robin sheduling policy between all threads allocated to a given processor (static allocation).
It selects the next runable thread to resume execution. 
If the only runnable task is the current task, return without context switch.
If there is no runable task, the scheduler switch to the default "idle" thread.
The return address contained in $31 is saved in the current thread context (in the ctx[31] slot), and the function actually returns to the address contained in the ctx[31] slot of the next thread context.

 === void '''_ctx_eret'''() ===
The address of this function is used to initialise the return address in the "idle" task context.

 === void '''_idle_thread'''() ===
This function is executed when no other thread can be executed.