Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/kernel/devices/dev_icu.h

    r3 r1  
    3535 * acting in all clusters containing cores. He is in charge of concentrating all IRQs
    3636 * (interrupt requests) generated by peripherals to signal the completion of an I/O
    37  * operation. Each IRQ is routed to the core that started the I/O operation.
     37 * operation. Each IRQ should be routed to the core that started the I/O operation.
    3838 * The ICU device must also help the kernel to select the ISR (Interrupt Service Routine)
    3939 * that must be executed by the target core.
    4040 *
    41  * This component can be implemented as a dedicated hardware component distributed
     41 * This component can be implemented as a dedicated hardware, centralized or distributed
    4242 * in all clusters, or emulated in software, as long as it implements the specified API.
    4343 * For the TSAR architecture, this generic ICU device is implemented by the two hardware
    4444 * components soclib_xicu and and soclib_iopic, and their associated drivers.
    4545 *
    46  * ALMOS-MKH defines three types of IRQs, that are handled by this ICU device:
     46 * ALMOS-MKH defines three types of IRQs, that are handled iby this ICU device:
    4747 * - HWI : The HardWare Interrupts are generated by local internal peripherals.
    4848 *   They are connected to the local ICU, to be routed to a given local core.
    … …  
    7272 * uses three interrupts vectors, implemented as three arrays (HWI/WTI/PTI),
    7373 * stored in the core descriptor. Each entry in one interrupt vector array contains
    74  * a pointer on the chdev descriptor that is the "source" of the interrupt.
    75  * This chdev descriptor contains a link to the ISR to be executed.
     74 * an extended pointer on the device descriptor that is the "source" of the interrupt.
     75 * This device descriptor contains a link to the ISR to be executed.
    7676 *
    7777 * The ICU peripheral does not execute I/O operations, but is just acting as a
    78  * dynamically configurable interrupt router for other I/O operations.
    79  * Therefore, ALMOS-MKH does not use the ICU device waiting queue, but calls directly
     78 * dynamically configurable interrupt router for another I/O operation.
     79 * Therefore, ALMOS-MKH does not use the iCU device waiting queue, but calls directly
    8080 * the ICU driver blocking functions, using the device lock to get exclusive access to
    8181 * the ICU device state.
    … …  
    8484/****  Forward declarations  ****/
    8585
    86 struct chdev_s;
     86struct device_s;
    8787
    8888/*****************************************************************************************
    … …  
    127127/*****************************************************************************************
    128128 * This function makes two initialisations:
    129  * - It initialises the ICU specific fields of the chdev descriptor.
     129 * - It initialises the ICU specific fields of the device descriptor.
    130130 * - it initialises the implementation specific ICU hardware device and associated
    131131 *   data structures if required.
    132  * It must be called by a local thread.
    133  *****************************************************************************************
    134  * @ icu     : pointer on ICU chdev descriptor.
    135  * @ hwi_nr  : number of HWI irqs.
    136  * @ wti_nr  : number of WTI irqs.
    137  * @ pti_nr  : number of PTI irqs.
    138  ****************************************************************************************/
    139 void dev_icu_init( struct chdev_s  * icu,
    140                    uint32_t          hwi_nr,
    141                    uint32_t          wti_nr,
    142                    uint32_t          pti_nr );
    143 
    144 /*****************************************************************************************
    145  * This function enables the routing of a given IRQ, to a given core in the local cluster.
    146  * This IRQ is identified by its type (HWI/WTI/PTI) and index in the local ICU.
     132 * It must be executed once in the cluster containing the ICU device descriptor.
     133 *****************************************************************************************
     134 * @ icu_xp     : extended pointer on ICU device descriptor.
     135 * @ hwi_nr     : number of HWI irqs.
     136 * @ wti_nr     : number of WTI irqs.
     137 * @ pti_nr     : number of PTI irqs.
     138 ****************************************************************************************/
     139void dev_icu_init( xptr_t    icu_xp,
     140                   uint32_t  hwi_nr,
     141                   uint32_t  wti_nr,
     142                   uint32_t  pti_nr );
     143
     144/*****************************************************************************************
     145 * This function enables the routing of a given IRQ, to a given core in a remote cluster.
     146 * This IRQ is identified by its type (HWI/WTI/PTI) and index in the remote ICU.
    147147 * The target core is identified by its local index.
    148  * It must be called by a local thread.
    149  * - It unmask the selected IRQ in the ICU.
    150  * - It registers the pointer on the "source" chdev descriptor in the
     148 * As it uses remote accesses, it can be executed by any thread in any cluster.
     149 * - It unmask the selected IRQ in the remote ICU.
     150 * - It registers the extended pointer on the "source" device descriptor in the
    151151 *   relevant interrupt vector of the selected core.
    152  * - It register the IRQ type and index in the "source" chdev descriptor.
    153  *****************************************************************************************
    154  * @ lid        : local index of selected core.
     152 * - It register the IRQ type and index in the "source" device descriptor.
     153 *****************************************************************************************
     154 * @ cxy        : remote cluster identifier (can be the local custer).
     155 * @ lid        : local index of selected core in remote cluster.
    155156 * @ irq_type   : HWI/WTI/PTI.
    156  * @ irq_id     : IRQ index in ICU
    157  * @ chdev      : pointer on source chdev descriptor.
    158  ****************************************************************************************/
    159 void dev_icu_enable_irq( lid_t             lid,
    160                          uint32_t          irq_type,
    161                          uint32_t          irq_id,
    162                          struct chdev_s  * chdev );
    163 
    164 /*****************************************************************************************
    165  * This function disables one given IRQ for a given core in the local cluster.
    166  * This IRQ is identified by its type (HWI/WTI/PTI) and index in the local ICU.
     157 * @ irq_id     : IRQ index in remote ICU
     158 * @ src_dev_xp : extended pointer on device descriptor source of IRQ.
     159 ****************************************************************************************/
     160void dev_icu_enable_irq( cxy_t      cxy,
     161                         lid_t      lid,
     162                         uint32_t   irq_type,
     163                         uint32_t   irq_id,
     164                         xptr_t     src_dev_xp );
     165
     166/*****************************************************************************************
     167 * This function disables one given IRQ for a given core in a remote cluster.
     168 * This IRQ is identified by its type (HWI/WTI/PTI) and index in the remote ICU.
    167169 * The core is identified by its local index.
    168  * It must be called by a local thread.
    169  * - It mask the selected IRQ in the ICU.
    170  * - It removes the pointer on the "source" chdev descriptor from the
     170 * As it uses remote accesses, it can be executed by any thread in any cluster.
     171 * - It mask the selected IRQ in the remote ICU.
     172 * - It removes the extended pointer on the "source" device descriptor from the
    171173 *   relevant interrupt vector of the selected core.
    172  * - The IRQ type and index fields are not modified in the "source" chdev descriptor.
    173  *****************************************************************************************
     174 * - The IRQ type and index fields are not modified in the "source" device descriptor.
     175 *****************************************************************************************
     176 * @ cxy       : remote cluster identifier (can be the local custer).
    174177 * @ lid       : local index of selected core in remote cluster.
    175178 * @ irq_type  : HWI/WTI/PTI.
    176179 * @ irq_id    : IRQ index.
    177180 ****************************************************************************************/
    178 void dev_icu_disable_irq( lid_t      lid,
     181void dev_icu_disable_irq( cxy_t      cxy,
     182                          lid_t      lid,
    179183                          uint32_t   irq_type,
    180184                          uint32_t   irq_id );
    … …  
    183187 * This function set the period value for a timer identified by the PTI index,
    184188 * in the local ICU device descriptor.
    185  * It must be called by a local thread.
    186189 *****************************************************************************************
    187190 * @ pti_id    : PTI index.
    … …  
    194197 * This function acknowledge a PTI IRQ for a timer identified by the PTI index,
    195198 * in the local ICU device descriptor.
    196  * It must be called by a local thread.
    197199 *****************************************************************************************
    198200 * @ pti_id    : PTI index.
    … …  
    202204/*****************************************************************************************
    203205 * This function send an IPI (Inter Processor Interrupt) to a core identified by
    204  * its cluster identifier and local index.
    205  * It can be called by any thread running in any cluster.
     206 * its cluster identifier and local index.
    206207 * This IPI force a context switch, and the handling of pending RPC(s).
    207208 *****************************************************************************************
    … …  
    225226
    226227/*****************************************************************************************
    227  * This function implements the WTI mailbox allocator for the local ICU.
    228  * These mailbox are used by I/O operations for completion signaling.
    229  * It must be called by a thread running in the cluster containing the target ICU.
     228 * This function implements the WTI mailbox allocator. It is used by all I/O operations
     229 * for completion signaling.
    230230 * If there is no mailbox available, the client thread must deschedule and retry later.
    231231 * If N is the total number of WTI mailboxes in a cluster, and NC the number of cores,
    … …  
    240240/*****************************************************************************************
    241241 * This function releases a dynamically allocated WTI mailbox.
    242  * It must be called by a thread running in the cluster containing the target ICU.
    243242 * It does not access the hardware device.
    244243 *****************************************************************************************
    … …  
    248247
    249248/*****************************************************************************************
    250  * This function returns a pointer on the WTI mailbox identified by its index
    251  * in the local ICU device.
    252  *****************************************************************************************
    253  * @ wti_id   : WTI mailbox index.
    254  * @ returns pointer on mailbox register.
    255  ****************************************************************************************/
    256 uint32_t * dev_icu_wti_ptr( uint32_t wti_id );
     249 * This function returns an extended pointer on a WTI mailbox identified by its
     250 * cluster identifier and local index in ICU.
     251 * WARNING: we assume that all ICU hardware devices have the same local base address.
     252 *****************************************************************************************
     253 * @ cxy      : mailbox cluster identifier
     254 * @ wti_id   : mailbox WTI index.
     255 * @ returns extended pointer on mailbox register.
     256 ****************************************************************************************/
     257xptr_t  dev_icu_wti_xptr( cxy_t    cxy,
     258                          uint32_t wti_id );
    257259
    258260#endif  /* _DEV_ICU_H_ */
Note: See TracChangeset for help on using the changeset viewer.