= IOC device API =

[[PageOutline]]

== A) General principles ==

This device provide access to various external mass storage peripherals such as a magnetic hard disk or a SD card, that can store blocks of data in a linear array of sectors indexed by a simple lba (logic block address).
It supports two command types of I/O operations:
 * '''READ'''  : move a given number of contiguous blocks from device to a memory buffer.
 * '''WRITE''' : move a given number of contiguous blocks from a memory buffer to device.

An I/O operation requires dynamic ressource allocation for IRQ routing to the dore running the client thread. It is always blocking for the client thread. The general scenario is detailed below:
 1.  The client thread start the I/O operation, by calling the dev_ioc_read() or the dev_ioc_write() kernel functions that perform the following actions: 
   * it get a free WTI mailbox from the client cluster WTI allocator.
   * it enables the WTI IRQ on the client cluster ICU and update the WTI interrupt vector.
   * it access the PIC to link the WTI mailbox to the IOC IRQ.
   * it builds the command descriptor stored in the thread descriptor.
   * the client thread registers in the IOC device waiting queue, block on the THREAD_BLOCKED_IO condition, and deschedule.
 1. The server thread attached to the IOC device descriptor handles all commands registered in the IOC device waiting queue, calling the IOC driver CMD function to start the I/O operation. 
 1. The IOC driver ISR (Interrupt Service Routine) signaling the I/O operation completion reactivates the client thread, that releases the allocated resources:
   * it access the PIC to unlink the IOC IRQ.
   * it disables the WTI IRQ in the client cluster ICU and reset the interrupt vector entry.
   * it releases the WTI mailbox to the client cluster WTI allocator.

Most hardware implementation have a DMA capability, but some implementations, such as the RDK (Ram Disk) implementation does not use DMA, and don't use IRQ.

== B) Access functions ==