Changes between Version 6 and Version 7 of ioc_device_api


Ignore:
Timestamp:
Jan 20, 2020, 11:51:45 PM (5 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ioc_device_api

    v6 v7  
    99The block size is supposed to be 512 bytes.
    1010
    11 It 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.
     11It supports a first ''user'' API, used by the user-level system calls, implementing four operation types : the '''IOC_READ''', '''IOC_WRITE''', '''IOC_SYNC_READ''', and '''IOC_SYNC_WRITE''' operations move a given number of contiguous blocks between the block device and a kernel memory buffer. This API is detailed in section C below.
    1212
    13 The 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:
     13* The '''asynchronous''' READ and WRITE operations are not directly executed by the client thread. The READ and WRITE requests are registered in the waiting queue rooted in the IOC chdev descriptor. These requests are actually handled by a dedicated server thread running in the cluster containing the chdev descriptor, that call the ''ioc_driver_cmd()'' function.
     14
     15* The '''synchronous''' SYNC_READ and SYNC_WRITE operations does not use the waiting queue, and does not use the server thread. The client thread calls directly the ''ioc_driver_cmd()'' function.
     16
     17Most IOC device implementation have a DMA capability, and the data transfer is not done by the software, but is actually done by the hardware device. The IOC IRQ signaling the transfer completion is routed to the core executing the server thread, and handled by the
     18''ioc_driver_isr()'' function (ISR stand for Interrupt Service Routine).
     19
     20In the IOC-RDK implementation the IOC block device is actually implemented as physical memory. This IOC-RDK implementation does not use DMA, and does not use an IRQ. The data transfer is directly executed by the ''ioc_driver_cmd()''  software function.
     21
     22To access the various drivers, this FBF device defines a lower-level ''driver'' API, that is detailed in section D below.
     23
     24All IOC device structures and 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.
     25
     26== __B) Initialisation__ ==
     27
     28The IOC device '''dev_ioc_init()''' function makes the following initializations :
     29 * It selects a core in cluster containing the IOC chdev to execute the IOC server thread.
     30 * it links the IOC IRQ to the core executing the IOC server thread.
     31 * it initialises the IOC specific fields of the chdev descriptor.
     32 * it initialises the implementation specific IOC hardware device,
     33 * it initializes the specific software data structures required by a given hardware implementation.
     34It must be called by a local thread.
     35
     36== __C) User API__ ==
     37
     38The '''void dev_ioc_move_data()''' blocking function moves <count> contiguous blocks of data between the block device,
     39indexed by the <lba> argument, and a kernel buffer, identified by the <buffer_xp> argument.
     40* The '''cmd_type''' argument defines the operation type.
     41* The '''buffer_xp''' argument is an extended pointer on the kernel buffer.
     42* The '''lba''' argument is the first block index in block device.
     43* The '''count''' argument is the number of blocks to move.
     44
     45The I/O operation is always blocking for the calling thread, but the blocking policy depends on the operation type.
     46
     47=== C.1) Asynchronous operations ===
     48
     49Almos-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 :
    1450 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.
    1551 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. 
    … …  
    1753 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.
    1854
    19 Note : 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.
     55Note : 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.
    2056
    21    * it get a free WTI mailbox from the client cluster WTI allocator.
    22    * it enables the WTI IRQ on the client cluster ICU and update the WTI interrupt vector.
    23    * it access the PIC to link the WTI mailbox to the IOC IRQ.
    24    * it builds the command descriptor stored in the thread descriptor.
    25    * it access the PIC to unlink the IOC IRQ.
    26    * it disables the WTI IRQ in the client cluster ICU and reset the interrupt vector entry.
    27    * it releases the WTI mailbox to the client cluster WTI allocator.
     57=== C.2) Synchronous I/O operations ===
    2858
    29 Most 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.
     59Almost-mkh uses the '''synchronous''' SYNC_READ and SYNC_WRITE operations  in the kernel_init() function, or to update the FAT (both the FAT mapper in memory, and the FAT on IOC device), or to update a directory on IOC device when a new file is created.
    3060
    31 To access the various drivers, this FBF device defines a lower-level ''driver'' API, that must be implemented by all drivers.
    32 
    33 All 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 The '''void dev_ioc_init()''' function makes two initializations :
    38  * it initialises the IOC specific fields of the chdev descriptor.
    39  * it initialises the implementation specific IOC hardware device and associated data structures if required.
    40 It must be called by a local thread.
    41 
    42 == __C) User API__ ==
    43 
    44 === B.1) '''void dev_ioc_read()''' ===
    45 
    46 This 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.
    47 The <buffer> argument is a
    48 The <lba> argument is the first block index in block device.
    49 The <count> argument is the number of blocks to move.
    50 
    51 === 2) '''void dev_ioc_write()''' ===
    52 
    53 This 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.
    54 The <buffer> argument is...
    55 The <lba> argument is the first block index in block device.
    56 The <count> argument is the number of blocks to move.
     61These 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,
    5762
    5863== __D) Driver API__ ==
    5964
    60 The IOC device defines defines four command types to access the IOC driver(s) :
    61  - '''IOC_WRITE''' : move blocks from a kernel buffer to the IOC device, with a descheduling policy.
    62  - '''IOC_READ'''  : move blocks from the IOC device to a kernel buffer, with a descheduling policy.
    63  - '''IOC_SYNC_WRITE'''   :
    64  - '''IOC_SYNC_READ'''    :
     65The IOC device defines uses the same four command types to access the IOC driver(s) :
     66 - '''IOC_WRITE''' : move blocks from a kernel buffer to the hardware device, with a descheduling policy.
     67 - '''IOC_READ''' : move blocks from the hardware device to a kernel buffer, with a descheduling policy.
     68 - '''IOC_SYNC_WRITE''' : move blocks from a kernel buffer to the hardware device, with a polling policy.
     69 - '''IOC_SYNC_READ''' : move blocks from the hardware device to a kernel buffer, with a polling policy.
    6570
    6671These four commands use the three following arguments, that must be registered, with the command type, in the ''ioc_command_t'' structure embedded in the client thread descriptor :
    67  - '''npixels''' : number of pixels to be moved.
    68  - '''buffer''' : pointer on buffer in (can be in user space or in kernel space).
    69  - '''offset''' : offset in FBF (number of pixels).
     72 - '''count''' : number of contiguous blocks to be moved.
     73 - '''buffer_xp''' : extended pointer on kernel buffer.
     74 - '''lba''' : logic block address (index of block in hardware device).