Changes between Version 1 and Version 2 of pic_device_api

Timestamp:

Nov 6, 2016, 11:52:06 PM (8 years ago)

Author:

alain

Comment:

--

pic_device_api

@@ -1 @@
-= Generic PIC device API =
+= PIC device API =
 
+[[PageOutline]]
+
+ == A) General principles ==
+
+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_IRQ_PIC_MAX 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 ''devices_irq'' global variable in the kernel initialization phase.
+
+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-MK does not use the PIC device waiting queue, but call directly the PIC driver blocking functions to dynamically configure the PIC component.
+
+== B) Access Functions ==
+
+=== 1) '''void dev_pic_init'''( xptr_t   xp_dev ,  uint32_t irq_nr ) ===
+
+This function makes two initializations:
+It initializes the PIC specific fields of the device descriptor. It call the PIC driver to initialize the PIC hardware device.
+It is executed once in the kernel initialisation phase.
+
+=== 2) '''void dev_pic_bind_irq'''( uint32_t   irq_id ,  cxy_t  cxy ,  uint32_t   wti_id ) ===
+
+This function link a WTI mailbox to the PIC input IRQ identified by its index, and unmask the selected input IRQ.
+The <irq_id> argument is the input IRQ index. The <cxy> argument is the WTI mailbox cluster. The <wti_id>  argument
+is the WTI mailbox index in cluster.
+
+=== 3) '''void dev_pic_unbind_irq'''( uint32_t  irq_id ) ===
+
+This function mask a PIC input IRQ identified by its index. The <irq_id> argument is the input IRQ index. 
+
+/*****************************************************************************************
+ * This function mask a PIC input IRQ identified by its index.
+ *****************************************************************************************
+ * @ irq_id    : input IRQ index.
+ * @ returns 0 if success / returns EINVAL if input IRQ not found.
+ ****************************************************************************************/
+void dev_pic_unbind_irq( uint32_t   irq_id );
+