Changes between Version 1 and Version 2 of icu_device_api


Ignore:
Timestamp:
Nov 3, 2016, 7:13:03 PM (8 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • icu_device_api

    v1 v2  
    11= ICU generic device API =
     2
     3[[PageOutline]]
     4
     5 == A) General principles ==
     6
     7The ICU (Interrupt Controller Unit) device is an ''internal'' peripheral, distributed in all clusters containing cores.
     8He is in charge of concentrating all IRQs (interrupt request)  generated by the - internal or external - peripherals to signal the completion of a given I/O operation, and routing each IRQ to the core that started the I/O operation. He is also in charge of helping the kernel to select the ISR (Interrupt Service Routine) to be executed by the target core.
     9
     10This component can be implemented as a dedicated hardware, distributed in all clusters, or emulated in software,
     11as long as it implements the API defined below.
     12
     13ALMOS-MK defines three types of IRQs, that are concentrated by the generic ICU device:
     14
     15 * '''HWI''' : The HardWare Interrupts are generated by a local internal peripheral. They are connected to the local ICU, to be routed to a given local core.
     16 * '''WTI''' : The Write Triggered Interrupts are actually mailboxes implemented in the local ICU. They can be used to implement software IPIs (Inter-Processor-Interrupts), or to route an IRQ generated by an external peripheral to a given local core.
     17 * '''PTI''' : The Programmable Timer Interrupts are actually timers generating periodic interrupts controled by softare, contained in the local ICU, and routed  to a given local core.
     18
     19The max numbers of interrupts of each type in a given cluster are defined by the CONFIG_IRQ_HWI_MAX, CONFIG_IRQ_WTI_MAX, and CONFIG_IRQ_PTI_MAX parameters. The actual numbers for a given manycore architecture are defined in the boot_info file.
     20
     21The generic ICU device provides three main services:
     22 1.  It allows the kernel to selectively enable/disable any IRQ (identified by its type and index) for a given core. It is the kernel responsibility to enable a given IRQ to the core that started the I/O operation core, as a given IRQ event should be handled by only one core.
     23 1. It makes a global OR between all enabled IRQs for a given core, to interrupt the core when at least one enabled IRQ is active. Of course, the core is interrupted only if the interrupts are not globally masked for the target core.
     24 1. It is capable to return the highest priority active IRQ of each type. The priority scheme depends on the ICU device implementation.
     25
     26To select the ISR to be executed for a given IRQ routed to a given core, the ICU device uses three interrupts vectors, implemented as three arrays (HWI/WTI/PTI) stored in the core descriptor.
     27Each entry in one interrupt vector array (defining one IRQ type and index) contains an extended pointer on the device descriptor that is the "source" of the interrupt. This device descriptor contains a link to the ISR to be executed to handle the interrupt event.
     28
     29The generic ICU device working for a single client that is the local kernel instance, it does not use the device descriptor  queue.
     30All commands are immediately executed, and use the device lock to get exclusive access to the ICU device state.
     31
     32== B) Access Functions ==
     33
     34=== '''void dev_icu_init'''( device_t * icu ) ===
     35
     36This function makes two initialisations: It initialises the ICU specific fields of the device descriptor.
     37it initialises the implementation specific ICU hardware device and associated data structures if required.
     38It must be executed once by a thread running in the cluster containing the ICU device descriptor.
     39 *****************************************************************************************
     40 * @ dev     : pointer on ICU device descriptor.
     41 ****************************************************************************************/
     42void dev_icu_init( device_t * icu );
     43
     44/*****************************************************************************************
     45 * This blocking function enable one IRQ defined by its type (HWI/WTI/PTI) and index
     46 * in the local ICU device descriptor, and register it in the proper interrupt vector
     47 * of the calling core.
     48 *****************************************************************************************
     49 * @ irq_type  : HWI/WTI/PTI.
     50 * @ irq_id    : IRQ index.
     51 * @ device    : pointer on device descriptor source of IRQ.
     52 * @ returns 0 if success / returns EINVAL if illegal arguments.
     53 ****************************************************************************************/
     54error_t dev_icu_enable_irq( uint32_t   irq_type,
     55                            uint32_t   irq_id,
     56                            device_t * src_dev );
     57
     58/*****************************************************************************************
     59 * This blocking function disable one IRQ defined by its type (HWI/WTI/PTI) and index
     60 * in the local ICU device descriptor, and remove it from the proper interrupt vector
     61 * of the calling core.
     62 *****************************************************************************************
     63 * @ irq_type  : HWI/WTI/PTI.
     64 * @ irq_id    : IRQ index.
     65 * @ returns 0 if success / returns EINVAL if illegal arguments.
     66 ****************************************************************************************/
     67error_t dev_icu_disable_irq( uint32_t   irq_type,
     68                             uint32_t   irq_id );
     69                       
     70/*****************************************************************************************
     71 * This blocking function set the period value for a timer identified by the PTI index
     72 * in the local ICU device descriptor.
     73 *****************************************************************************************
     74 * @ pti_id    : PTI index.
     75 * @ period    : number of cycles.
     76 * @ return 0 if success / returns EINVAL if illegal arguments.
     77 ****************************************************************************************/
     78error_t dev_icu_set_period( core_t   * core,
     79                            uint32_t   pti_id,
     80                            uint32_t   period );
     81
     82/*****************************************************************************************
     83 * This function send an IPI (Inter Processor Interrupt) to a core identified by
     84 * its cluster identifier and local index.
     85 * This IPI force a context switch, and the handling of pending RPC(s).
     86 *****************************************************************************************
     87 * @ cxy      : destination cluster identifier.
     88 * @ lid      : destination core local index.
     89 * @ return 0 if success (IPI registered) / returns EINVAL if illegal cxy or lid.
     90 ****************************************************************************************/
     91error_t dev_icu_send_ipi( cxy_t    cxy,
     92                          lid_t    lid );
     93
     94/*****************************************************************************************
     95 * This function is called by a core when it receives an IRQ from the ICU device.
     96 * It access the local ICU device descriptor to get the highest priority IRQ
     97 * of each type (HWI / WTI / PTI).
     98 * - If it is a WTI or an HWI, the function uses the calling core interrupt-vectors
     99 *   to call the relevant ISR, registered in the source device descriptor.
     100 * - If it is a PTI, the source device descriptor is the ICU device itself, and it
     101 *   call the core_clock() function to execute all operations related to the TICK event.
     102 ****************************************************************************************/
     103void dev_icu_irq_handler();
     104