Index: trunk/kernel/devices/dev_pic.h
===================================================================
--- trunk/kernel/devices/dev_pic.h	(revision 14)
+++ trunk/kernel/devices/dev_pic.h	(revision 188)
@@ -1,4 +1,4 @@
 /*
- * dev_pic.h - PIC (External Interrupt Controler) generic device API definition.
+ * dev_pic.h - PIC (Programmable Interrupt Controler) generic device API definition.
  *
  * Authors   Alain Greiner  (2016)
@@ -29,21 +29,46 @@
 
 /*****************************************************************************************
- *     Generic External Interrupt Controler definition
- *
- * The PIC generic device describes an external interrupt Controler, that translates 
- * N input IRQs generated by external peripherals to N WTI IRQs, that will be routed 
- * to a dynamically allocated WTI mailbox in a given cluster. 
- *
- * The max number of input IRQs is defined by the CONFIG_MAX_IRQS_PER_PIC parameter. 
- * The actual number of connected IRQs is defined in the ''arch_info'' file, and stored 
- * in the PIC device extension.  
- * The "source" device for each input IRQ is also defined in the ''arch_info'' file,
- * and are stored in the ''chdev_input_irq'' global variable in kernel initialization.
- *
- * This external peripheral does not execute I/O operations, but is just acting as a 
- * dynamically configurable interrupt router for another I/O operation. Therefore, 
- * ALMOS-MKH does not use the PIC device waiting queue, but call directly the relevant 
- * driver blocking functions to dynamically "bind" or "unbind" an external IRQ to a
- * WTI mailbox.
+ *     Generic Programmable Interrupt Controler definition
+ *
+ * The PIC generic device describes the the programmable hardware infrastructure used
+ * to route a given IRQ to a given core, in a given cluster, and to help the interrupt
+ * handler to select  and execute the relevant ISR (Interrupt Service Routine).
+ * It handles the following type of interrupts:
+ * - External IRQs generated by the external (shared) peripherals.
+ * - Internal IRQs generated by the internal (replicated) peripherals.
+ * - Timer IRQs generated by the timers (one timer per core).
+ * - Inter Processor IRQs (IPI) generated by software.
+ *
+ * In most supported manycores architectures, the PIC device contains two types 
+ * of hardware components: 
+ * - the IOPIC is an external component, handling all external peripherals IRQs.
+ * - The LAPIC is an internal component, replicated in each cluster, handling local
+ *   peripherals IRQS, Timer IRQs and IPIs (inter-processor-interupts).
+ *
+ * The "source" device for each input IRQ to the external IOPIC component, is defined
+ * in the "arch_info" file, and registered in the "iopic_input" global variable
+ * at kernel initialization.
+ *
+ * The "source" device for each input IRQ to the replicated LAPIC components, is defined
+ * in the "arch_info" file, and stored in the "lapic_input" global variable
+ * at kernel initialization.
+ *
+ * The PIC device defines 4 generic commands that can be used by each kernel instance,
+ * - to create in local cluster the PIC implementation specific interupt vector(s),
+ * - to bind a given IRQ (internal or external IRQ to a given core in the local cluster,
+ * - to configure and activate the TICK timer for a given core in the local cluster,
+ * - to allows the software to send an IPI to any core in any cluster. 
+ * This API is detailed below, and must be implemented by all PIC implementations.
+ *
+ * In each cluster, a PIC implementation specific structure can be linked to the
+ * cluster manager or to the core descriptors to register the interrupt vectors
+ * used by the kernel to select the relevant ISR when an interrupt is received 
+ * by a given core in agiven cluster.
+ 
+ * This PIC device does not execute itself I/O operations. It is just acting as a 
+ * configurable interrupt router for I/O operation executed by other peripherals.
+ * Therefore, ALMOS-MKH does not use the PIC device waiting queue, does not creates
+ * a server thread for the PIC device, and does not register the command in the calling 
+ * thread descriptor, but call directly the relevant driver function.
  ****************************************************************************************/
  
@@ -53,15 +78,66 @@
 
 /*****************************************************************************************
- * This defines the (implementation independant) extension for the PIC device.
- ****************************************************************************************/
-
+ * This defines the specific extension for the PIC chdev descriptor.
+ * It contains four function pointers on the four PIC command types, 
+ * that must be implemented by all drivers. 
+ ****************************************************************************************/
+
+typedef void   (pic_bind_t)    ( lid_t lid , struct chdev_s * src_chdev );   
+typedef void   (pic_enable_t)  ( struct chdev_s * src_chdev );   
+typedef void   (pic_disable_t) ( struct chdev_s * src_chdev );   
+typedef void   (pic_timer_t)   ( uint32_t period );   
+typedef void   (pic_ipi_t)     ( cxy_t cxy , lid_t lid ); 
+typedef void   (pic_init_t)    ( uint32_t * lapic_base ); 
+  
 typedef struct pic_extend_s
 {
-    uint32_t    irq_nr;     /*! actual number of input IRQs to the PIC device           */
+    pic_bind_t    * bind_irq;      /*! pointer on the driver "bind_irq" function        */ 
+    pic_enable_t  * enable_irq;    /*! pointer on the driver "enable_irq" function      */ 
+    pic_disable_t * disable_irq;   /*! pointer on the driver "disable_irq" function     */ 
+    pic_timer_t   * enable_timer;  /*! pointer on the driver "enable_timer" function    */
+    pic_ipi_t     * send_ipi;      /*! pointer on the driver "send_ipi" function        */
+    pic_init_t    * extend_init;   /*! pointer on the driver "init_extend" function     */
 }
 pic_extend_t;
 
-/*****************************************************************************************
- * This enum defines the various implementations of the PIC external interrupt controller.
+/******************************************************************************************
+ * This structure defines the input IRQS for the external IOPIC controller, that is used 
+ * by external peripherals (IOC, NIC, TXT, etc.) to signal completion of an I/O operation.
+ * It describes the hardware wiring of IRQs between external peripherals and the IOPIC,
+ * as each entry contains the input IRQ index in IOPIC. 
+ * For a multi-channels peripheral, there is one chdev and one IRQ per channel.
+ * This structure is replicated in each cluster. It is allocated as a global variable
+ * in the kernel_init.c file.
+ *****************************************************************************************/
+
+typedef struct iopic_input_s
+{
+    uint32_t   txt[CONFIG_MAX_TXT_CHANNELS];
+    uint32_t   ioc[CONFIG_MAX_IOC_CHANNELS];
+    uint32_t   nic_rx[CONFIG_MAX_NIC_CHANNELS];
+    uint32_t   nic_tx[CONFIG_MAX_NIC_CHANNELS];
+    uint32_t   iob;
+}
+iopic_input_t;
+
+/******************************************************************************************
+ * This structure defines the input IRQS for the internal LAPIC controllers, that are used
+ * by internal peripherals IRQS (DMA, MMC) to signal completion of an I/O operation. 
+ * It describes the hardware wiring of IRQs between internal peripherals and ICU, 
+ * as each entry contains the input IRQ index in the LAPIC component.
+ * For a multi-channels peripheral, there is one chdev and one IRQ per channel.
+ * This structure is replicated in each cluster. It is allocated as a global variable
+ * in the kernel_init.c file.
+ *****************************************************************************************/
+
+typedef struct lapic_input_s
+{
+    uint32_t   dma[CONFIG_MAX_DMA_CHANNELS];
+    uint32_t   mmc;                             // MMC is single channel
+}
+lapic_input_t;
+
+/*****************************************************************************************
+ * This enum defines the various implementations of the PIC device.
  * This array must be kept consistent with the define in arch_info.h file
  ****************************************************************************************/
@@ -69,5 +145,5 @@
 enum pic_impl_e
 {
-    IMPL_PIC_SOC =   0,     
+    IMPL_PIC_SCL =   0,     
     IMPL_PIC_I86 =   1,
 }
@@ -75,34 +151,76 @@
 
 /*****************************************************************************************
- * This function makes two initialisations:
+ * This function makes two initialisations :
  * - It initializes the PIC specific fields of the chdev descriptor.
- * - it initializes the implementation specific PIC hardware device.
- * It must be executed once in the kernel initialisation phase.
- *****************************************************************************************
- * @ xp_dev     : extended pointer on PIC device descriptor.
- * @ uint32_t   : actual number of input IRQs.
- ****************************************************************************************/
-void dev_pic_init( struct chdev_s * chdev,
-                   uint32_t         irq_nr );
-
-/*****************************************************************************************
- * This function link a WTI mailbox to the PIC input IRQ identified by its index,
- * and unmask the selected input IRQ, calling the relevant driver.
- *****************************************************************************************
- * @ irq_id    : input IRQ index.
- * @ cxy       : WTI mailbox cluster.
- * @ wti_id    : WTI mailbox index in cluster.
- ****************************************************************************************/
-void dev_pic_bind_irq( uint32_t   irq_id,
-                       cxy_t      cxy,
-                       uint32_t   wti_id );
-
-/*****************************************************************************************
- * This function mask a PIC input IRQ identified by its index, calling te relevant driver.
- *****************************************************************************************
- * @ irq_id    : input IRQ index.
- ****************************************************************************************/
-void dev_pic_unbind_irq( uint32_t   irq_id );
-                        
+ * - it initializes the implementation specific PIC hardware registers.
+ * It is executed once in cluster containing the PIC chdev, during kernel initialisation.
+ * The calling core goes to sleep in case of failure.
+ *****************************************************************************************
+ * @ pic        : local pointer on PIC device descriptor.
+ ****************************************************************************************/
+void dev_pic_init( struct chdev_s * pic );
+
+/*****************************************************************************************
+ * This function completes the PIC infrastructure initialisation in each cluster.
+ * It allocates memory for the local PIC extensions in the core descriptors and/or
+ * in the cluster manager, as required by the specific PIC implementation.
+ * This function is called by CPO in all clusters, during kernel initialisation phase.
+ * The calling core goes to sleep in case of failure.
+ *****************************************************************************************
+ * @ lapic_base  : local pointer on LAPIC component segment base.
+ ****************************************************************************************/
+void dev_pic_extend_init( uint32_t * lapic_base );
+
+/*****************************************************************************************
+ * This function configure the PIC device to route the IRQ generated by a local chdev,
+ * defined by the <src_chdev> argument, to a local core identified by the <lid> argument.
+ * This is a static binding, defined during kernel init: IRQ can be enabled/disabled,
+ * but the binding cannot be released. It can be used for both internal & external IRQs.
+ * WARNING : the IRQ must be explicitely enabled by the dev_pic_enable_irq() function.
+ *****************************************************************************************
+ * @ lid        : target core local index.
+ * @ src_chdev  : local pointer on source chdev descriptor.
+ ****************************************************************************************/
+void dev_pic_bind_irq( lid_t            lid,
+                       struct chdev_s * src_chdev );
+
+/*****************************************************************************************
+ * This function disables the IRQ generated by a local chdev, defined by the <src_chdev> 
+ * argument. It can be used for both internal & external IRQs.
+ *****************************************************************************************
+ * @ lid        : target core local index.
+ * @ src_chdev  : local pointer on source chdev descriptor.
+ ****************************************************************************************/
+void dev_pic_disable_irq( lid_t            lid,
+                          struct chdev_s * src_chdev );
+
+/*****************************************************************************************
+ * This function enables the IRQ generated by a local chdev, defined by the <src_chdev> 
+ * argument. It can be used for both internal & external IRQs.
+ *****************************************************************************************
+ * @ lid        : target core local index.
+ * @ src_chdev  : local pointer on source chdev descriptor.
+ ****************************************************************************************/
+void dev_pic_enable_irq( lid_t            lid,
+                         struct chdev_s * src_chdev );
+
+/*****************************************************************************************
+ * This function activates the TICK timer for the calling core.
+ * The <period> argument define the number of cycles between IRQs.
+ *****************************************************************************************
+ * @ period      : number of cycles between IRQs.
+ ****************************************************************************************/
+void dev_pic_enable_timer( uint32_t period );
+
+/*****************************************************************************************
+ * This function allows the calling thread to send an IPI to any core in any cluster.
+ * The target core is identified by the <cxy> & <lid> arguments.
+ *****************************************************************************************
+ * @ cxy        : target core cluster.
+ * @ lid        : target core local index.
+ ****************************************************************************************/
+void dev_pic_send_ipi( cxy_t  cxy,
+                       lid_t  lid );
+
 
 #endif  /* _DEV_PIC_H_ */
