Ignore:
Timestamp:
Oct 22, 2019, 1:48:51 PM (5 years ago)
Author:
alain
Message:

...miscelaneous...

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/kernel/devices/dev_ioc.h

    r627 r647  
    3838 * magnetic hard disk or a SD card, that can store blocks of data in a linear array
    3939 * of sectors indexed by a simple lba (logic block address).
     40 *
    4041 * It supports four command types:
    4142 * - READ       : move blocks from device to memory, with a descheduling policy.
    … …  
    4344 * - SYNC_READ  : move blocks from device to memory, with a busy waiting policy.
    4445 * - SYNC_WRITE : move blocks from memory to device, with a busy waiting policy.
    45 
    46  * The READ or WRITE operations require dynamic ressource allocation. The calling thread
    47  * is descheduled, and the work is done by the server thread associated to IOC device.
    48  * The general scenario is detailed below.
    49  * A) the client thread start the I/O operation, by calling the dev_ioc_read()
    50  *    or the dev_ioc_write() kernel functions that perform the following actions:
    51  *    1) it get a free WTI mailbox from the client cluster WTI allocator.
    52  *    2) it enables the WTI IRQ on the client cluster ICU and update interrupt vector.
    53  *    3) it access the PIC to link the WTI mailbox to the IOC IRQ.
    54  *    4) it builds the command descriptor.
    55  *    5) it registers in the IOC device waiting queue.
    56  *    6) itblock on the THREAD_BLOCKED_IO condition and deschedule.
    57  * B) The server thread attached to the IOC device descriptor handles the commands
    58  *    registered in the waiting queue, calling the IOC driver function.
    59  *    Most hardware implementation have a DMA capability, but some implementations,
    60  *    such as the RDK (Ram Disk) implementation does not use DMA.
    61  * C) The ISR signaling the I/O operation completion reactivates the client thread,
    62  *    that releases the allocated resources:
    63  *    1) access the PIC to unlink the IOC IRQ.
    64  *    2) disable the WTI IRQ in the client cluster ICU and update interrupt vector.
    65  *    3) release the WTI mailbox to the client cluster WTI allocator.
     46 *
     47 * For the he READ or WRITE operations, the client thread is descheduled, and the work
     48 * is done by the server thread associated to the IOC device:
     49 * The client thread calls the dev_ioc_move_data() kernel functions that (i) registers
     50 * the command in the client thread descriptor, (ii) registers the client thread
     51 * in the IOC device waiting queue, and (iii) blocks on the THREAD_BLOCKED_IO condition
     52 * and deschedules.
     53 * The server thread attached to the IOC device descriptor handles the commands
     54 * registered in the waiting queue, calling the IOC driver function.
     55 * Most IOC device implementations have a DMA capability, but some implementations,
     56 * such as the RDK (Ram Disk) implementation does not use DMA.
     57 * When the server thread completes an I/O operation, it reactivates the client thread.
    6658 *
    6759 * The SYNC_READ and SYNC_WRITE operations are used by the kernel in the initialisation
    6860 * phase, to update the FAT (both the FAT mapper and the FAT on IOC device), or to update
    6961 * a directory on IOC device when a new file is created.
    70  * - These synchronous operations do not not use the IOC device waiting queue,
    71  *   the server thread, and the IOC IRQ, but implement a busy-waiting policy
    72  *   for the calling thread.
    73  * - As the work
     62 * These synchronous operations do not not use the IOC device waiting queue,
     63 * the server thread, and the IOC IRQ. The client thread does not deschedules:
     64 * it registers the command in the thread descriptor, calls directly the IOC driver,
     65 * and uses a busy-waiting policy to poll the IOC device status.
    7466 *****************************************************************************************/
    7567
    … …  
    116108{
    117109    xptr_t      dev_xp;     /*! extended pointer on IOC device descriptor                */
    118     uint32_t    type;       /*! IOC_READ / IOC_WRITE / IOC_SYNC_READ                     */
     110    uint32_t    type;       /*! command type above                                       */
    119111    uint32_t    lba;        /*! first block index                                        */
    120112    uint32_t    count;      /*! number of blocks                                         */
    … …  
    146138
    147139/******************************************************************************************
    148  * This blocking function moves one or several contiguous blocks of data
    149  * from the block device to a local memory buffer. The corresponding request is actually
    150  * registered in the device pending request queue, and the calling thread is descheduled,
    151  * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
    152  * It must be called by a local thread.
     140 * This blocking function moves <count> contiguous blocks of data between the block device
     141 * starting from block defined by the <lba> argument and a kernel memory buffer, defined
     142 * by the <buffer_xp> argument. The transfer direction and mode are defined by the
     143 * <cmd_type> argument. The request is always registered in the calling thread descriptor.
     144 * - In synchronous mode, the calling thread is not descheduled, and directly calls the
     145 *   IOC driver, polling the IOC status to detect transfer completion.
     146 * - In asynchronous mode, the calling thread blocks and deschedules, and the IOC driver
     147 *   is called by the server thread associated to the IOC device.
    153148 ******************************************************************************************
    154  * @ buffer    : local pointer on target buffer in memory (must be block aligned).
     149 * @ cmd_type  : IOC_READ / IOC_WRITE / IOC_SYNC_READ / IOC_SYN_WRITE.
     150 * @ buffer_xp : extended pointer on kernel buffer in memory (must be block aligned).
    155151 * @ lba       : first block index on device.
    156152 * @ count     : number of blocks to transfer.
    157153 * @ returns 0 if success / returns -1 if error.
    158154 *****************************************************************************************/
    159 error_t dev_ioc_read( uint8_t      * buffer,
    160                       uint32_t       lba,
    161                       uint32_t       count );
    162 
    163 /******************************************************************************************
    164  * This blocking function moves one or several contiguous blocks of data
    165  * from a local memory buffer to the block device. The corresponding request is actually
    166  * registered in the device pending request queue, and the calling thread is descheduled,
    167  * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
    168  * It must be called by a local thread.
    169  ******************************************************************************************
    170  * @ buffer    : local pointer on source buffer in memory (must be block aligned).
    171  * @ lba       : first block index on device.
    172  * @ count     : number of blocks to transfer.
    173  * @ returns 0 if success / returns -1 if error.
    174  *****************************************************************************************/
    175 error_t dev_ioc_write( uint8_t      * buffer,
    176                        uint32_t       lba,
    177                        uint32_t       count );
    178 
    179 /******************************************************************************************
    180  * This blocking function moves one or several contiguous blocks of data
    181  * from the block device to a - possibly remote - memory buffer.
    182  * It uses an extended pointer, because the target buffer is generally a remote mapper.
    183  * It does  not uses the IOC device waiting queue and server thread, and does not use
    184  * the IOC IRQ, but call directly the relevant IOC driver, implementing a busy-waiting
    185  * policy for the calling thread.
    186  * It can be called by a thread running in any cluster.
    187  ******************************************************************************************
    188  * @ buffer_xp : extended pointer on target buffer in memory (must be block aligned).
    189  * @ lba       : first block index on device.
    190  * @ count     : number of blocks to transfer.
    191  * @ returns 0 if success / returns -1 if error.
    192  *****************************************************************************************/
    193 error_t dev_ioc_sync_read( xptr_t         buffer_xp,
    194                            uint32_t       lba,
    195                            uint32_t       count );
    196 
    197 /******************************************************************************************
    198  * This blocking function moves one or several contiguous blocks of data
    199  * from a - possibly remote - memory buffer to the block device.
    200  * It uses an extended pointer, because the target buffer is generally a remote mapper.
    201  * It does  not uses the IOC device waiting queue and server thread, and does not use
    202  * the IOC IRQ, but call directly the relevant IOC driver, implementing a busy-waiting
    203  * policy for the calling thread.
    204  * It can be called by a thread running in any cluster.
    205  ******************************************************************************************
    206  * @ buffer_xp : extended pointer on source buffer in memory (must be block aligned).
    207  * @ lba       : first block index on device.
    208  * @ count     : number of blocks to transfer.
    209  * @ returns 0 if success / returns -1 if error.
    210  *****************************************************************************************/
    211 error_t dev_ioc_sync_write( xptr_t         buffer_xp,
    212                             uint32_t       lba,
    213                             uint32_t       count );
     155error_t dev_ioc_move_data( uint32_t  cmd_type,
     156                           xptr_t    buffer_xp,
     157                           uint32_t  lba,
     158                           uint32_t  count );
    214159
    215160#endif  /* _DEV_IOC_H */
Note: See TracChangeset for help on using the changeset viewer.