= 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.

The GIET_VM threads try to implement the POSIX threads. 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. A thread 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.

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] ***            ||


 === 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.