Changes between Version 1 and Version 2 of ioc_device_api

Timestamp:

Nov 7, 2016, 12:10:52 PM (8 years ago)

Author:

alain

Comment:

--

ioc_device_api

@@ -1 +1 @@
 = IOC device API =
 
-[[outline]]
+[[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 ==