= GIET-VM / XCU Driver = 

[[PageOutline]]

The [source:soft/giet_vm/giet_drivers/xcu_driver.c xcu_driver.c] and [source:soft/giet_vm/giet_drivers/xcu_driver.h xcu_driver.h] files define the XCU driver.

The ''vci_xcu'' component is an extended interrupt controller, available in the SoCLib components library, and supporting three types of interrupts:
 * '''HWI''' : Hardware Interrupts (from hardware peripherals)
 * '''PTI''' : Programmable Timer Interrupts (contained in the XCU component)
 * '''WTI''' : Write Trigered Interrupts (from software, or from a PIC controller) 

The GIET-VM uses three 32 entries interrupt vectors (one interrupt vector for each interrupt type).

The XCU component is a replicated peripheral: it must exist one XCU per cluster, and each one can contain several channels (one channel per output IRQ).

The number of XICU channels must be larger or equal to (NB_PROCS_MAX*IRQ_PER_PROCESSOR), even if the GIET-VM uses only one channel per processor (index = IRQ_PER_PROCESSOR * lpid).

The virtual base address of the segment associated to the component is:
    vbase =  SEG_XCU_BASE + cluster_xy * PERI_CLUSTER_INCREMENT

The SEG_XCU_BASE and PERI_CLUSTER_INCREMENT values must be defined in the hard_config.h file.

The addressable registers map is defined [source:soft/giet_vm/giet_drivers/xcu_driver.h here].

 == __Access Functions__ ==

 === void '''_xcu_set_mask'''( unsigned int cluster_xy,  unsigned int channel,    unsigned int mask,   unsigned int irq_type ) ===
This function set the mask register for all IRQs of a given type. 
 * '''cluster_xy''' : cluster coordinates.
 * '''channel''' : XCU channel (output IRQ index).
 * '''mask''' : mask value : All '1' bits are set / all '0' bits are not modified.
 * '''irq_type''' : IRQ type.

 === void '''_xcu_get_index'''( unsigned int   cluster_xy,   unsigned int   channel,   unsigned int * index,  unsigned int * irq_type ) ===
 * '''cluster_xy''' : cluster coordinates.
 * '''channel''' : XCU channel (output IRQ index).
 * '''index''' : pointer on the index buffer.
 * '''irq_type''' : pointer on the IRQ type buffer.
This function returns the index and the type of the highest priority active interrupt with the following priorities: PTI > HWI > WTI.

 === void '''_xcu_send_wti'''( unsigned int cluster_xy,   unsigned int wti_index,   unsigned int wdata ) ===
This function writes a 32 bits word in a WTI mailbox.
 * '''cluster_xy''' : cluster coordinates.
 * '''wti_index''' : mailbox index.
 * '''wdata''' : written value.

 === void '''_xcu_get_wti_value'''( unsigned int   cluster_xy,   unsigned int   wti_index,   unsigned int * value ) ===
This function returns the value contained in a WTI mailbox. The corresponding WTI is acknowledged.
 * '''cluster_xy''' : cluster coordinates.
 * '''wti_index''' : mailbox index.
 * '''value''' : pointer on the destination buffer.

 === void '''_xcu_get_wti_address'''( unsigned int   wti_index,  unsigned int * address ) ===
This function returns the physical address (32 LSB bits) of the WTI mailbox identified by its index.
There is no access to a specific XCU component in a specific cluster.
 * '''wti_index''' : WTI index.
 * '''address''' : pointer on the destination buffer.

 === void '''_xcu_timer_start'''( unsigned int cluster_xy,   unsigned int pti_index,  unsigned int period ) === 
This function activates a timer contained in XCU by writing in the proper register the period value.
 * '''cluster_xy''' : cluster coordinates.
 * '''pti_index''' : mailbox index.
 * '''period''' : period value.

 === void '''_xcu_timer_stop'''( unsigned int cluster_xy,   unsigned int pti_index ) === 
This function desactivates a timer in XCU component by writing in the proper register.
 * '''cluster_xy''' : cluster coordinates.
 * '''pti_index''' : mailbox index.

 === void '''_xcu_timer_reset_irq'''( unsigned int cluster_xy,   unsigned int pti_index ) ===
This function acknowlegge a timer interrupt in XCU component by reading in the proper XCU register.
It is used by both the isr_switch() for a system timer,  or by the _isr_timer() for an user timer.
 * '''cluster_xy''' : cluster coordinates.
 * '''pti_index''' : mailbox index.

 === void '''_xcu_timer_reset_cpt'''( unsigned int cluster_xy,  unsigned int pti_index ) ===
This function resets a timer counter. To do so, it read in the TIMER_PERIOD register, and rewrite the same value in the same register, what causes the count to restart. This function is called during a context switch (user or preemptive).
 * '''cluster_xy''' : cluster coordinates.
 * '''pti_index''' : mailbox index.