= 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 );