Ignore:
Timestamp:
Jul 12, 2017, 8:12:41 PM (7 years ago)
Author:
alain
Message:

Redefine the PIC device API.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/kernel/devices/dev_pic.h

    r14 r188  
    11/*
    2  * dev_pic.h - PIC (External Interrupt Controler) generic device API definition.
     2 * dev_pic.h - PIC (Programmable Interrupt Controler) generic device API definition.
    33 *
    44 * Authors   Alain Greiner  (2016)
    … …  
    2929
    3030/*****************************************************************************************
    31  *     Generic External Interrupt Controler definition
    32  *
    33  * The PIC generic device describes an external interrupt Controler, that translates
    34  * N input IRQs generated by external peripherals to N WTI IRQs, that will be routed
    35  * to a dynamically allocated WTI mailbox in a given cluster.
    36  *
    37  * The max number of input IRQs is defined by the CONFIG_MAX_IRQS_PER_PIC parameter.
    38  * The actual number of connected IRQs is defined in the ''arch_info'' file, and stored
    39  * in the PIC device extension. 
    40  * The "source" device for each input IRQ is also defined in the ''arch_info'' file,
    41  * and are stored in the ''chdev_input_irq'' global variable in kernel initialization.
    42  *
    43  * This external peripheral does not execute I/O operations, but is just acting as a
    44  * dynamically configurable interrupt router for another I/O operation. Therefore,
    45  * ALMOS-MKH does not use the PIC device waiting queue, but call directly the relevant
    46  * driver blocking functions to dynamically "bind" or "unbind" an external IRQ to a
    47  * WTI mailbox.
     31 *     Generic Programmable Interrupt Controler definition
     32 *
     33 * The PIC generic device describes the the programmable hardware infrastructure used
     34 * to route a given IRQ to a given core, in a given cluster, and to help the interrupt
     35 * handler to select  and execute the relevant ISR (Interrupt Service Routine).
     36 * It handles the following type of interrupts:
     37 * - External IRQs generated by the external (shared) peripherals.
     38 * - Internal IRQs generated by the internal (replicated) peripherals.
     39 * - Timer IRQs generated by the timers (one timer per core).
     40 * - Inter Processor IRQs (IPI) generated by software.
     41 *
     42 * In most supported manycores architectures, the PIC device contains two types
     43 * of hardware components:
     44 * - the IOPIC is an external component, handling all external peripherals IRQs.
     45 * - The LAPIC is an internal component, replicated in each cluster, handling local
     46 *   peripherals IRQS, Timer IRQs and IPIs (inter-processor-interupts).
     47 *
     48 * The "source" device for each input IRQ to the external IOPIC component, is defined
     49 * in the "arch_info" file, and registered in the "iopic_input" global variable
     50 * at kernel initialization.
     51 *
     52 * The "source" device for each input IRQ to the replicated LAPIC components, is defined
     53 * in the "arch_info" file, and stored in the "lapic_input" global variable
     54 * at kernel initialization.
     55 *
     56 * The PIC device defines 4 generic commands that can be used by each kernel instance,
     57 * - to create in local cluster the PIC implementation specific interupt vector(s),
     58 * - to bind a given IRQ (internal or external IRQ to a given core in the local cluster,
     59 * - to configure and activate the TICK timer for a given core in the local cluster,
     60 * - to allows the software to send an IPI to any core in any cluster.
     61 * This API is detailed below, and must be implemented by all PIC implementations.
     62 *
     63 * In each cluster, a PIC implementation specific structure can be linked to the
     64 * cluster manager or to the core descriptors to register the interrupt vectors
     65 * used by the kernel to select the relevant ISR when an interrupt is received
     66 * by a given core in agiven cluster.
     67 
     68 * This PIC device does not execute itself I/O operations. It is just acting as a
     69 * configurable interrupt router for I/O operation executed by other peripherals.
     70 * Therefore, ALMOS-MKH does not use the PIC device waiting queue, does not creates
     71 * a server thread for the PIC device, and does not register the command in the calling
     72 * thread descriptor, but call directly the relevant driver function.
    4873 ****************************************************************************************/
    4974 
    … …  
    5378
    5479/*****************************************************************************************
    55  * This defines the (implementation independant) extension for the PIC device.
    56  ****************************************************************************************/
    57 
     80 * This defines the specific extension for the PIC chdev descriptor.
     81 * It contains four function pointers on the four PIC command types,
     82 * that must be implemented by all drivers.
     83 ****************************************************************************************/
     84
     85typedef void   (pic_bind_t)    ( lid_t lid , struct chdev_s * src_chdev );   
     86typedef void   (pic_enable_t)  ( struct chdev_s * src_chdev );   
     87typedef void   (pic_disable_t) ( struct chdev_s * src_chdev );   
     88typedef void   (pic_timer_t)   ( uint32_t period );   
     89typedef void   (pic_ipi_t)     ( cxy_t cxy , lid_t lid );
     90typedef void   (pic_init_t)    ( uint32_t * lapic_base );
     91 
    5892typedef struct pic_extend_s
    5993{
    60     uint32_t    irq_nr;     /*! actual number of input IRQs to the PIC device           */
     94    pic_bind_t    * bind_irq;      /*! pointer on the driver "bind_irq" function        */
     95    pic_enable_t  * enable_irq;    /*! pointer on the driver "enable_irq" function      */
     96    pic_disable_t * disable_irq;   /*! pointer on the driver "disable_irq" function     */
     97    pic_timer_t   * enable_timer;  /*! pointer on the driver "enable_timer" function    */
     98    pic_ipi_t     * send_ipi;      /*! pointer on the driver "send_ipi" function        */
     99    pic_init_t    * extend_init;   /*! pointer on the driver "init_extend" function     */
    61100}
    62101pic_extend_t;
    63102
    64 /*****************************************************************************************
    65  * This enum defines the various implementations of the PIC external interrupt controller.
     103/******************************************************************************************
     104 * This structure defines the input IRQS for the external IOPIC controller, that is used
     105 * by external peripherals (IOC, NIC, TXT, etc.) to signal completion of an I/O operation.
     106 * It describes the hardware wiring of IRQs between external peripherals and the IOPIC,
     107 * as each entry contains the input IRQ index in IOPIC.
     108 * For a multi-channels peripheral, there is one chdev and one IRQ per channel.
     109 * This structure is replicated in each cluster. It is allocated as a global variable
     110 * in the kernel_init.c file.
     111 *****************************************************************************************/
     112
     113typedef struct iopic_input_s
     114{
     115    uint32_t   txt[CONFIG_MAX_TXT_CHANNELS];
     116    uint32_t   ioc[CONFIG_MAX_IOC_CHANNELS];
     117    uint32_t   nic_rx[CONFIG_MAX_NIC_CHANNELS];
     118    uint32_t   nic_tx[CONFIG_MAX_NIC_CHANNELS];
     119    uint32_t   iob;
     120}
     121iopic_input_t;
     122
     123/******************************************************************************************
     124 * This structure defines the input IRQS for the internal LAPIC controllers, that are used
     125 * by internal peripherals IRQS (DMA, MMC) to signal completion of an I/O operation.
     126 * It describes the hardware wiring of IRQs between internal peripherals and ICU,
     127 * as each entry contains the input IRQ index in the LAPIC component.
     128 * For a multi-channels peripheral, there is one chdev and one IRQ per channel.
     129 * This structure is replicated in each cluster. It is allocated as a global variable
     130 * in the kernel_init.c file.
     131 *****************************************************************************************/
     132
     133typedef struct lapic_input_s
     134{
     135    uint32_t   dma[CONFIG_MAX_DMA_CHANNELS];
     136    uint32_t   mmc;                             // MMC is single channel
     137}
     138lapic_input_t;
     139
     140/*****************************************************************************************
     141 * This enum defines the various implementations of the PIC device.
    66142 * This array must be kept consistent with the define in arch_info.h file
    67143 ****************************************************************************************/
    … …  
    69145enum pic_impl_e
    70146{
    71     IMPL_PIC_SOC =   0,     
     147    IMPL_PIC_SCL =   0,     
    72148    IMPL_PIC_I86 =   1,
    73149}
    … …  
    75151
    76152/*****************************************************************************************
    77  * This function makes two initialisations:
     153 * This function makes two initialisations :
    78154 * - It initializes the PIC specific fields of the chdev descriptor.
    79  * - it initializes the implementation specific PIC hardware device.
    80  * It must be executed once in the kernel initialisation phase.
    81  *****************************************************************************************
    82  * @ xp_dev     : extended pointer on PIC device descriptor.
    83  * @ uint32_t   : actual number of input IRQs.
    84  ****************************************************************************************/
    85 void dev_pic_init( struct chdev_s * chdev,
    86                    uint32_t         irq_nr );
    87 
    88 /*****************************************************************************************
    89  * This function link a WTI mailbox to the PIC input IRQ identified by its index,
    90  * and unmask the selected input IRQ, calling the relevant driver.
    91  *****************************************************************************************
    92  * @ irq_id    : input IRQ index.
    93  * @ cxy       : WTI mailbox cluster.
    94  * @ wti_id    : WTI mailbox index in cluster.
    95  ****************************************************************************************/
    96 void dev_pic_bind_irq( uint32_t   irq_id,
    97                        cxy_t      cxy,
    98                        uint32_t   wti_id );
    99 
    100 /*****************************************************************************************
    101  * This function mask a PIC input IRQ identified by its index, calling te relevant driver.
    102  *****************************************************************************************
    103  * @ irq_id    : input IRQ index.
    104  ****************************************************************************************/
    105 void dev_pic_unbind_irq( uint32_t   irq_id );
    106                        
     155 * - it initializes the implementation specific PIC hardware registers.
     156 * It is executed once in cluster containing the PIC chdev, during kernel initialisation.
     157 * The calling core goes to sleep in case of failure.
     158 *****************************************************************************************
     159 * @ pic        : local pointer on PIC device descriptor.
     160 ****************************************************************************************/
     161void dev_pic_init( struct chdev_s * pic );
     162
     163/*****************************************************************************************
     164 * This function completes the PIC infrastructure initialisation in each cluster.
     165 * It allocates memory for the local PIC extensions in the core descriptors and/or
     166 * in the cluster manager, as required by the specific PIC implementation.
     167 * This function is called by CPO in all clusters, during kernel initialisation phase.
     168 * The calling core goes to sleep in case of failure.
     169 *****************************************************************************************
     170 * @ lapic_base  : local pointer on LAPIC component segment base.
     171 ****************************************************************************************/
     172void dev_pic_extend_init( uint32_t * lapic_base );
     173
     174/*****************************************************************************************
     175 * This function configure the PIC device to route the IRQ generated by a local chdev,
     176 * defined by the <src_chdev> argument, to a local core identified by the <lid> argument.
     177 * This is a static binding, defined during kernel init: IRQ can be enabled/disabled,
     178 * but the binding cannot be released. It can be used for both internal & external IRQs.
     179 * WARNING : the IRQ must be explicitely enabled by the dev_pic_enable_irq() function.
     180 *****************************************************************************************
     181 * @ lid        : target core local index.
     182 * @ src_chdev  : local pointer on source chdev descriptor.
     183 ****************************************************************************************/
     184void dev_pic_bind_irq( lid_t            lid,
     185                       struct chdev_s * src_chdev );
     186
     187/*****************************************************************************************
     188 * This function disables the IRQ generated by a local chdev, defined by the <src_chdev>
     189 * argument. It can be used for both internal & external IRQs.
     190 *****************************************************************************************
     191 * @ lid        : target core local index.
     192 * @ src_chdev  : local pointer on source chdev descriptor.
     193 ****************************************************************************************/
     194void dev_pic_disable_irq( lid_t            lid,
     195                          struct chdev_s * src_chdev );
     196
     197/*****************************************************************************************
     198 * This function enables the IRQ generated by a local chdev, defined by the <src_chdev>
     199 * argument. It can be used for both internal & external IRQs.
     200 *****************************************************************************************
     201 * @ lid        : target core local index.
     202 * @ src_chdev  : local pointer on source chdev descriptor.
     203 ****************************************************************************************/
     204void dev_pic_enable_irq( lid_t            lid,
     205                         struct chdev_s * src_chdev );
     206
     207/*****************************************************************************************
     208 * This function activates the TICK timer for the calling core.
     209 * The <period> argument define the number of cycles between IRQs.
     210 *****************************************************************************************
     211 * @ period      : number of cycles between IRQs.
     212 ****************************************************************************************/
     213void dev_pic_enable_timer( uint32_t period );
     214
     215/*****************************************************************************************
     216 * This function allows the calling thread to send an IPI to any core in any cluster.
     217 * The target core is identified by the <cxy> & <lid> arguments.
     218 *****************************************************************************************
     219 * @ cxy        : target core cluster.
     220 * @ lid        : target core local index.
     221 ****************************************************************************************/
     222void dev_pic_send_ipi( cxy_t  cxy,
     223                       lid_t  lid );
     224
    107225
    108226#endif  /* _DEV_PIC_H_ */
Note: See TracChangeset for help on using the changeset viewer.