Changes between Version 3 and Version 4 of txt_device_api


Ignore:
Timestamp:
Jan 22, 2020, 2:50:29 PM (3 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • txt_device_api

    v3 v4  
    1111The "user" API, contains the functions used  the user-level system calls, and by the kernel itself. It defines three operation types :  '''TXT_READ''', '''TXT_WRITE''', and '''TXT_SYNC_WRITE'''. This API is detailed in section C below.
    1212
    13 * The '''asynchronous''' TXT_READ and TXT_WRITE operations are not directly executed by the client thread. The requests are registered in the waiting queue rooted in the TXT chdev descriptor. These requests are actually handled by a dedicated server thread running in the cluster containing the chdev descriptor, that call the ''txt_driver_cmd()'' function. A TXT_WRITE operation (TX direction) moves N characters from a kernel buffer to the TXT terminal. A TXT_READ operation moves one single character from the TXT terminal to a kernel buffer.
     13The '''asynchronous''' TXT_READ and TXT_WRITE operations are not directly executed by the client thread. The requests are registered in the waiting queue rooted in the TXT chdev descriptor. These requests are actually handled by a dedicated server thread running in the cluster containing the chdev descriptor, that call the generic ''txt_driver_cmd()'' function for each registered request. A TXT_WRITE operation (TX direction) moves N characters from a kernel buffer to the TXT terminal. A TXT_READ operation moves one single character from the TXT terminal to a kernel buffer.
    1414
    15 * The '''synchronous''' SYNC_WRITE operation is used by the kernel to display debug messages on the TXT0. It does not use the waiting queue, and it does not use the server thread. The client thread calls directly the ''txt_driver_aux()'' function, without using the the txt_command_t structure to communicate with the driver.
     15The '''synchronous''' SYNC_WRITE operation is used by the kernel to display debug messages on the TXT0. It does not use the waiting queue, and it does not use the server thread. The client thread calls directly the ''txt_driver_aux()'' function, without using the the txt_command_t structure to communicate with the driver.
    1616
    1717Most TXT device implementations use two (hardware or software) FIFOs for asynchronous READ and WRITE operations. These FIFOs are not controlled by the kernel, but are controlled by the ''txt_driver_cmd()'' and ''txt_cxd_isr()''. When they are used by the driver, the TXT_TX_IRQ and TXT_RX_IRQ are routed to the core executing the corresponding TXT server thread. (ISR stand for Interrupt Service Routine).
    … …  
    4040* The '''dev_txt_write( uint32_t channel , char * buffer , uint32_t count  )''' function moves  <count> characters from a local kernel buffer identified by the <buffer> pointer, to the terminal identified by the <channel> argument.
    4141
    42 The kernel buffer is allocated in the kernel stack of the client thread.
    43 
    4442Almos-mkh uses these '''asynchronous''' operations, for most data transfers required by the user processes.
     43For a TX transter (TXT_WRITE), a fixed size kernel buffer is allocated in the kernel stack of the client thread.
    4544
    4645The scenario is the following :
    47 
    48  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.
    49  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. 
    50  1. When the I/O operation completed, the IOC driver ISR (Interrupt Service Routine) signaling completion reactivates the server thread.
    51  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.
     46 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 TXT chdev. Then the client thread blocks on the THREAD_BLOCKED_IO condition, and deschedules.
     47 1. The DEV server thread attached to the TXT device descriptor handles all commands registered in the TXT device waiting queue. For each pending request, it calls the ''txt_driver_cmd()'' function to move data between the kernel buffer and the TXT terminal. This ''txt_driver_cmd()'' function is itself a blocking function, returning only when the transfer is completed.
     48 1. When the ''txt_driver_cmd()'' function returns, the server thread reactivates the client thread, and handle the next request in the TXT waiting queue, or deschedules if the queue is empty.
    5249
    5350Note : 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.
    … …  
    6057kernel function, and we want to avoid any interference with another TXT I/O operation. We don't want to use the TXT device waiting queue, the associated server thread, and the ''txt_command_t'' structures used by the ''txt_driver_cmd()'' function. Therefore, this function directly call the ''txt_driver_aux()'' function, and the txt_sync_args_s structure for the arguments.
    6158 
    62 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,
    63 
    6459== __D) The "driver" API__ ==
    6560
    … …  
    7065* void '''txt_driver_aux'''( char * buffer , uint32_t count )'''
    7166
    72 The '''txt_driver_cmd()''' function arguments are registered in the ''txt_command_t'' structure embedded in the client thread descriptor. One command contains four informations:
     67The '''txt_driver_cmd()''' function is called for the TXT_READ and TXT_WRITE operations. The arguments are registered in the ''txt_command_t'' structure embedded in the client thread descriptor. One command contains three informations:
    7368 - '''type''' : operation type (TXT_READ / TXT_WRITE)
    7469 - '''buf_xp''' : extended pointer on kernel buffer.
    7570 - '''count''' : number of characters (only for TXT_WRITE).
    7671
    77 For asynchronous operations the '''txt_driver_cmd()''' function is called by the server thread, that blocks and deschedules after launching the I/O transfer. When the TXT_IRQ is raised by the hardware, the '''ioc_driver_isr()''' function reports the I/O operation status, and re-activates the server thread.
     72For these '''asynchronous''' operations, the '''txt_driver_cmd()''' function is called by the server thread:
     73 1. When the driver implements private software TX_FIFO, and RX_FIDO, the '''txt_driver_cmd()''' function move character(s) between the kernel buffer and the FIFO. TXT driver FIFO. If the TX_FIFO is full (for a WRITE), or if the TX_FIFO is empty (for a READ), the server thread blocks on the THREAD_BLOCKED_ISR condition, and deschedules. It is re-activated by the '''txt_driver_isr()''' function, when the state of the blocking FIFO is modified.
     74 1. The '''txt_driver_isr()''' function is in charge of moving the characters between the (TX or RX) FIFO and the (TX or RX) buffer in TXT terminal. It is called by the TXT_IRQ each time the TX buffer is empty, or each time the RX is FULL. ISR  stand for Interrupt Service Routine. the '''txt_driver_isr()''' function re-activates the server thread when the state of a blocking FIFO has been modified.
    7875
    79 The '''txt_driver_aux()''' function doesn't use the ''txt_command_t'' structure embedded in the thread  descriptor. The two
    80 arguments are the <buffer> pointer on the kernel buffer, and the number of characters <count>.
     76The '''txt_driver_aux()''' function is called for the TXT_SYNC_WRITE operation. The arguments  are:
     77 -  '''buffer''' : pointer on the kernel buffer.
     78 - '''count''' :  number of characters to move.
     79
     80For this '''synchronous''' operation, the '''txt_driver_cmd()''' function is called directly by the client thread. It does not use the TX_FIFO and the TXT_IRQ. It
     81polls the TX buffer status to directly move the characters, from the kernel buffer to the terminal TX buffer.