Changes between Version 4 and Version 5 of ioc_device_api


Ignore:
Timestamp:
Jan 20, 2020, 6:36:27 PM (4 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ioc_device_api

    v4 v5  
    33[[PageOutline]]
    44
    5 == A) General principles ==
     5== __A) General principles__ ==
    66
    7 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).
    8 It supports two command types of I/O operations:
    9  * '''READ'''  : move a given number of contiguous blocks from device to a memory buffer.
    10  * '''WRITE''' : move a given number of contiguous blocks from a memory buffer to device.
     7This device allows the kernel to access 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).
    118
    12 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:
    13  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:
     9The block size is supposed to be 512 bytes.
     10
     11It supports a first ''user'' API, used by the user-level system calls, implementing two command types : the '''READ''' and '''WRITE''' operations move a given number of contiguous blocks between the block device and a kernel memory buffer.
     12
     13The I/O operation is blocking for the calling thread, but it is not done by the client thread itself. The general scenario is detailed below:
     14 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.
     15 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. 
     16 1. When the I/O operation completed, the IOC driver ISR (Interrupt Service Routine) signaling completion reactivates the server thread.
     17 1. The server thread reactivates the client thread, and handle the next request in the IOC waiting queue, or reschedules if the queue is empty.
     18
     19Note : According to the scheduling policy, the DEV thread has an higher priority than any user thread, but it is not selected when the associated waiting queue is empty.
     20
    1421   * it get a free WTI mailbox from the client cluster WTI allocator.
    1522   * it enables the WTI IRQ on the client cluster ICU and update the WTI interrupt vector.
    1623   * it access the PIC to link the WTI mailbox to the IOC IRQ.
    1724   * it builds the command descriptor stored in the thread descriptor.
    18    * the client thread registers in the IOC device waiting queue, block on the THREAD_BLOCKED_IO condition, and deschedule.
    19  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.
    20  1. The IOC driver ISR (Interrupt Service Routine) signaling the I/O operation completion reactivates the client thread, that releases the allocated resources:
    2125   * it access the PIC to unlink the IOC IRQ.
    2226   * it disables the WTI IRQ in the client cluster ICU and reset the interrupt vector entry.
    2327   * it releases the WTI mailbox to the client cluster WTI allocator.
    2428
    25 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.
     29Most IOC device implementation have a DMA capability, but some implementations, such as the RDK (Ram Disk) implementation does not use DMA, and don't use an IRQ, as the data transfers are directly executed by the driver CMD function.
    2630
    27 == B) Access functions ==
     31To access the various drivers, this FBF device defines a lower-level ''driver'' API, that must be implemented by all drivers.
     32
     33All IOC access functions are defined in the [https://www-soc.lip6.fr/trac/almos-mkh/browser/trunk/kernel/devices/dev_ioc.c  dev_ioc.c] et [https://www-soc.lip6.fr/trac/almos-mkh/browser/trunk/kernel/devices/dev_ioc.h dev_ioc.h] files.
     34
     35== __B) Initialisation__ ==
     36
     37== __C) User API__ ==
    2838
    2939=== 1) '''void dev_ioc_init'''( xptr_t    xp_dev ) ===
    3040
    31 This function makes two initialisations:
    32  * it initialises the IOC specific fields of the device descriptor.
     41The '''void dev_ioc_init()''' function makes two initializations :
     42 * it initialises the IOC specific fields of the chdev descriptor.
    3343 * it initialises the implementation specific IOC hardware device and associated data structures if required.
    3444It can be executed in another cluster than the cluster containing the IOC device descriptor or the IOC hardware device itself.
    3545The <xp_dev> argument is an extended pointer on the IOC device descriptor.
    3646
    37 === 2) '''void dev_ioc_read'''( char * buffer , uint32_t  lba , uint32_t  count ) ===
     47=== 1) '''void dev_ioc_read'''( char * buffer , uint32_t  lba , uint32_t  count ) ===
    3848
    3949This blocking function try to tranfer one or several contiguous blocks of data from the block device to a memory buffer. The calling thread is registered in the device pending request queue, and descheduled, waiting on transfer completion. It is re-activared by the IRQ signaling completion. It must be called in the client cluster.
    … …  
    4252The <count> argument is the number of blocks to move.
    4353
    44 === 3) '''void dev_ioc_write'''( char * buffer , uint32_t  lba , uint32_t  count ) ===
     54=== 2) '''void dev_ioc_write'''( char * buffer , uint32_t  lba , uint32_t  count ) ===
    4555
    4656This blocking function try to tranfer one or several contiguous blocks of data from a memory buffer to the block device. The calling thread is actually registered in the device pending request queue, and descheduled, waiting on transfer completion. It is re-activared by the IRQ signaling completion. It must be called in the client cluster.