Changes between Version 11 and Version 12 of icu_device_api

Timestamp:

Nov 6, 2016, 9:48:06 PM (8 years ago)

Author:

alain

Comment:

--

icu_device_api

@@ -37 +37 @@
 The <icu> argument is a local pointer on the ICU device descriptor.
  
-=== 2) '''error_t dev_icu_enable_irq'''( uint32_t   irq_type , uint32_t   irq_id , xptr_t  src_dev ) ===
+=== 2) '''void dev_icu_enable_irq'''( uint32_t   irq_type , uint32_t   irq_id , xptr_t  src_dev ) ===
 
 This function enables the routing of a given IRQ, defined by its type and index, to the calling core. It registers it in the calling core interrupt vector the extended pointer on the "source" device descriptor.
 The <irq_type> and <irq_id> arguments define the IRQ type and index. The <src_dev> argument is the remote pointer on the source device.
-It returns 0 if success / returns EINVAL if illegal arguments.
 
-=== 3) '''error_t dev_icu_disable_irq'''( uint32_t   irq_type , uint32_t   irq_id ) ===
+=== 3) '''void dev_icu_disable_irq'''( uint32_t   irq_type , uint32_t   irq_id ) ===
 
 This function must be executed by a thread running in the cluster containing the ICU device descriptor. It disables one IRQ defined by its type and index, for the calling core, and remove it from the interrupt vector.
 The <irq_type> and <irq_id> arguments define the IRQ type and index.
-It returns 0 if success / returns EINVAL if illegal arguments.
 
-=== 4) '''error_t dev_icu_set_period'''( core_t   * core , uint32_t   pti_id , uint32_t   period ) ===
+=== 4) '''void dev_icu_set_period'''( uint32_t   pti_id , uint32_t   period ) ===
 
 This  function set the period value for a PTI timer identified by its index in the local ICU device descriptor.
-The <core> argument is local pointer on the target core. The <pti_id> argument is the timer index. 
 The <period> argument is the period value (number of cycles).
-It returns 0 if success / returns EINVAL if illegal arguments.
 
-=== 5) '''error_t dev_icu_send_ipi'''( cxy_t    cxy , lid_t    lid ) ===
+=== 5) '''void dev_icu_ack_timer'''( uint32_t   pti_id ) ===
+
+This function acknowledge a PTI IRQ for a timer identified by the PTI index in the local ICU device descriptor.
+The <pti_id> argument is the timer index. 
+
+=== 6) '''void dev_icu_send_ipi'''( cxy_t    cxy , lid_t    lid ) ===
 
 This function send an IPI (Inter Processor Interrupt) to a core identified by its cluster identifier and local index. 
 This IPI force a context switch, and the handling of pending RPC(s).
 The <cxy> argument is the destination cluster identifier. The <lid> argument is the  destination core local index.
-It returns 0 if success / returns EINVAL if illegal arguments.
 
-=== 6) '''void dev_icu_irq_handler'''() ===
-
+=== 7) '''void dev_icu_irq_handler'''() ===
+:
 This function is called by a core when it receives an IRQ from the ICU device.
 It access the local ICU device descriptor to get the highest priority active IRQ of each type (HWI / WTI / PTI).
  * If it is a WTI or an HWI, the function uses the calling core interrupt-vectors to call the relevant ISR, registered in the source device descriptor.
  * If it is a PTI, the source device descriptor is the ICU device itself, and it call the core_clock() function to execute all operations related to the TICK event.
- ****************************************************************************************/
+
+=== 8) '''uint32_t dev_icu_wti_alloc'''() ===
+
+This function implements the WTI mailbox allocator. This mailbox is used by all I/O operations for completion signaling.
+If there is no mailbox available, the client thread must deschedule and retry later. It returns the allocated WTI mailbox index.
+If N is the total number of WTI mailboxes in a cluster, and NC the number of cores, the number of dynamically allocatable WTI mailboxes is (N-NC) because the first N WTI mailboxes are used by the IPIs (one IPI per core).
+
+=== 9) '''void dev_icu_wti_release'''( uint32_t  wti_id ) ===
+
+This function releases a dynamically allocated WTI mailbox. The <wti_id> argument is the WTI index.
+
+=== 10) ''' xptr_t dev_icu_wti_xptr'''( cxy_t  cxy  ,  uint32_t  wti_id ) ===
+
+This function returns an extended pointer on a WTI mailbox identified by its cluster identifier and local index in ICU.
+WARNING: it assumes that all ICU hardware devices have the same local base address.
+The <cxy> argument is the mailbox cluster identifier. The <wti_id> argument is the mailbox WTI index.
+It returns extended pointer on the mailbox register.