Changes between Version 12 and Version 13 of ioc_device_api

Timestamp:

Jan 21, 2020, 8:57:58 PM (4 years ago)

Author:

alain

Comment:

--

ioc_device_api

@@ -36 +36 @@
 == __C) User API__ ==
 
+
+
+These four I/O operations are blocking for the calling thread, but the blocking policy depends on the operation type.
+
+=== C.1) Asynchronous operations ===
+
 * The '''dev_ioc_read( xptr_t buffer_xp , uint32_t lba , uint32_t count )''' blocking function moves <count> contiguous blocks from the block device, starting from block defined by the <lba> argument, to a kernel buffer defined by the <buffer_xp> argument. It register the request in the IOC device waiting queue. Then it blocks and deschedules.
 * The '''dev_ioc_write( xptr_t buffer_xp , uint32_t lba , uint32_t count )''' blocking function moves <count> contiguous blocks from a kernel buffer defined by the <buffer_xp> argument to the block device, starting from block defined by the <lba> argument. It register the request in the IOC device waiting queue. Then it blocks and deschedules.
+
+Almos-mkh uses the '''asynchronous''', READ & WRITE operations, for most data transfers between the file system on the IOC, and the file system cache in memory. The detailed scenario is the following :
+ 1. When a client thread request an I/O operation, the request is registered in the ''ioc_command_t'' structure embedded in the client thread descriptor, and the client thread registers itself in the waiting queue rooted in the IOC chdev. Then the client thread blocks on the THREAD_BLOCKED_IO condition, and deschedules.
+ 1. The DEV server thread attached to the IOC device descriptor handles all commands registered in the IOC device waiting queue. For each pending request, it calls the ''ioc_driver_cmd()'' function that is itself a blocking function, returning only when the transfer is completed.
+ 1. When the hardware block device has a DMA capability, for an asynchronous request, the ''ioc_driver_cmd()'' function is supposed to lauch the DMA transfer, then blocks on the THREAD_BLOCKED_ISR condition, and deschedules. 
+ 1. When the I/O operation completes, the hardware rises the IOC_IRQ, and the the ioc_driver_isr() function reactivates the server thread.
+ 1.When the server thread resumes, it reactivates the client thread, and handle the next request in the IOC waiting queue, or deschedules if the IOC queue is empty.
+
+Note : According to the scheduler policy, the DEV threads have an higher priority than the USR threads, and a DEV thread keep blocked when the associated waiting queue is empty.
+
+=== C.2) Synchronous operations ===
+
 * The '''dev_ioc_sync_read( xptr_t buffer_xp , uint32_t lba , uint32_t count )''' blocking function moves <count> contiguous blocks from the block device, starting from block defined by the <lba> argument, to a kernel buffer defined by the <buffer_xp> argument. It calls directly the IOC driver without rescheduling, and without using the IOC device waiting queue and the server thread.
 * The '''dev_ioc_sync_write( xptr_t buffer_xp , uint32_t lba , uint32_t count )''' blocking function moves <count> contiguous blocks from a kernel buffer defined by the <buffer_xp> argument to the block device, starting from block defined by the <lba> argument. It calls directly the IOC driver without rescheduling, and without using the IOC device waiting queue and the server thread.
 
-The I/O operation is always blocking for the calling thread, but the blocking policy depends on the operation type.
+Almost-mkh uses the '''synchronous''' SYNC_READ and SYNC_WRITE operations  in the ''kernel_init()'' function, or to synchronously update the FAT (both the FAT mapper in memory, and the FAT on IOC device), or the directory files on IOC device. 
 
-=== C.1) Asynchronous operations ===
-
-Almos-mkh uses the '''asynchronous''', READ & WRITE operations, for most data transfers between the file system on the IOC, and the file system cache in memory. The scenario is the following :
- 1. When a client thread request an I/O operation, the request is registered in the ''ioc_command_t'' structure embedded in the client thread descriptor, and the client thread registers itself in the waiting queue rooted in the IOC chdev. Then the client thread blocks on the THREAD_BLOCKED_IO condition, and deschedules.
- 1. The DEV server thread attached to the IOC device descriptor handles all commands registered in the IOC device waiting queue. For each pending request, it calls the IOC driver CMD (command) function to ask the hardware device to do the transfer. Then, the server thread blocks on the THREAD_BLOCKED_ISR condition, and deschedules.  
- 1. When the I/O operation completed, the IOC driver reactivates the server thread.
- 1. The server thread reactivates the client thread, and handle the next request in the IOC waiting queue, or deschedules if the queue is empty.
-
-Note : According to the scheduler policy, the DEV thread has an higher priority than any user thread, but it is not selected when the associated waiting queue is empty.
-
-=== C.2) Synchronous operations ===
-
-Almost-mkh uses the '''synchronous''' SYNC_READ and SYNC_WRITE operations  in the kernel_init() function, or to synchronously update the FAT (both the FAT mapper in memory, and the FAT on IOC device), or the directory files on IOC device. 
-
-These synchronous operations use neither the IOC device waiting queue, nor the DEV server thread, and the  IRQ. The client thread does not deschedules : it registers the arguments in the IOC command structure embedded in the client thread descriptor, and calls directly the blocking IOC driver CMD function,
+These synchronous operations use neither the IOC device waiting queue, nor the DEV server thread. The client thread does not deschedules : it registers the arguments in the IOC command structure embedded in the client thread descriptor, and calls directly the blocking ''ioc_driver_cmd()'' function, that executes the command and returns only when the transfer is completed. For a synchronous request, and even if the  the hardware IOC controller has a DMA capability, the ioc_driver_cmd() function is supposed to use a polling strategy to wait the transfer completion, withoutdriver
 
 == __D) Driver API__ ==
@@ -75 +79 @@
  - '''IOC_WRITE''' : move blocks from a kernel buffer to the hardware device, with a descheduling policy.
  - '''IOC_READ''' : move blocks from the hardware device to a kernel buffer, with a descheduling policy.
- - '''IOC_SYNC_WRITE''' : move blocks from a kernel buffer to the hardware device, without descheduling.
- - '''IOC_SYNC_READ''' : move blocks from the hardware device to a kernel buffer, without descheduling.
+ - '''IOC_SYNC_WRITE''' : move blocks from a kernel buffer to the hardware device, with a polling policy.
+ - '''IOC_SYNC_READ''' : move blocks from the hardware device to a kernel buffer, with a polling policy.
 
-For asynchronous operations the ''ioc_driver_cmd()'' function is called by the server thread. It must block and deschedule after launching the I/O transfer. The I/O operation status is reported in the command by the ISR, and the server thread is re-activated by the ISR.
+For asynchronous operations the '''ioc_driver_cmd()''' function is called by the server thread. It must block and deschedule after launching the I/O transfer. When the IOC_IRQ is raised by the hardware, the '''ioc_driver_isr()''' function reports the I/O operation status is reported in the command, and reactivates the server thread.
 
-For synchronous operations, the ''ioc_driver_cmd()'' function is called by the client thread. It mask the IOC IRQ, poll the BDV status register until I/O transfer completion, and report status in the command.
+For synchronous operations, the '''ioc_driver_cmd()''' function is called by the client thread. It masks the IOC_IRQ, polls the IOC hardware status register until I/O transfer completion, and report I/O operation status in the command. The '''ioc_driver_isr()''' function is not involved.