Ignore:
Timestamp:
Oct 5, 2018, 12:08:35 AM (6 years ago)
Author:
alain
Message:

Introduction of the soclib_mty driver for the TSAR-LETI architecture.

File:
1 moved

Legend:

Unmodified
Added
Removed

  • trunk/hal/tsar_mips32/drivers/soclib_mty.h

    r562 r570  
    11/*
    2  * soclib_multi_tty.c - soclib tty driver definition.
     2 * soclib_mty.c - soclib_mty driver definition (used in TSAR-LETI architecture).
    33 *
    4  * Author  Alain Greiner (2016)
     4 * Author  Alain Greiner (2016,2017,2018)
    55 *
    66 * Copyright (c)  UPMC Sorbonne Universites
    … …  
    2424#include <dev_txt.h>
    2525#include <chdev.h>
    26 #include <spinlock.h>
    2726
    2827
    2928/****************************************************************************************
    30  * This driver supports the soclib_multi_tty component.
     29 * This driver supports the "backup" TTY controler implemented in cluster 0
     30 * of the TSAR-LETI architecture, that is actually an over-simplified version
     31 * of the vci_tty_tsar component:
     32 *
     33 * 1) This hardware component handles only ONE TTY physical channel, that must
     34 *    be virtualized by the driver to support several kernel TXT devices.
     35 * 2) For received characters, the hardware support one RX_IRQ, and one bit
     36 *    in the MTY_STATUS register to signal that the MTY_READ register is full.
     37 * 3) For transmitted characters, the hardware does NOT provide a TX_IRQ,
     38 *    and does NOT provide status information about the MTY_WRITE register,
     39 *    but implement a low-level flow control mechanism: the response to the
     40 *    VCI write request in MTY_WRITE register is blocked until this register
     41 *    can be actually written...
     42 *
    3143 * It implements the generic TXT device API:
    3244 * - transfer one single character from TTY to command "buffer" if to_mem is non-zero.
    3345 * - transfer "count" characters from command "buffer" to TTY if "to_mem is zero.
     46 *
     47 * It handles asynchronous control characters (^C / ^Z), that are translated to signals
     48 * transmited to the TXT owner process (foreground process).
     49 *
     50 * This driver implements one TX_FIFO for the transmited characters, writen by the "cmd"
     51 * function, and read by the "isr" function).
     52 * This driver implements one RX_FIFO for the received characters, writen by the "isr"
     53 * function, and read by the "cmd" function).
     54***************************************************************************************/
     55
     56/****************************************************************************************
     57 *     SOCLIB_MTY registers offsets and masks
    3458 ***************************************************************************************/
    3559
     60#define MTY_WRITE              0
     61#define MTY_STATUS             1
     62#define MTY_READ               2
     63#define MTY_CONFIG             3
     64
    3665/****************************************************************************************
    37  *     SOCLIB_TTY registers offsets
     66 * masks for MTY_STATUS and MTY_CONFIG registers
    3867 ***************************************************************************************/
    3968
    40 #define MTTY_WRITE              0
    41 #define MTTY_STATUS             1
    42 #define MTTY_READ               2
    43 #define MTTY_CONFIG             3
     69#define MTY_STATUS_RX_FULL     1          // TTY_READ_REG full if 1
    4470
    45 #define MTTY_SPAN               4 
     71#define MTY_CONFIG_RX_ENABLE   1          // RX_IRQ enable if 1
    4672
    4773/****************************************************************************************
    48  * masks for TTY_STATUS_REG
     74 * This structure is used for both the RX_FIFO and the TX_FIFO.
    4975 ***************************************************************************************/
    5076
    51 #define MTTY_STATUS_RX_FULL     1       // TTY_READ_REG full if 1
    52 #define MTTY_STATUS_TX_FULL     2       // TTY_WRITE_REG full if 1
     77#define MTY_FIFO_DEPTH  128
    5378
    54 /****************************************************************************************
    55  * masks for TTY_CONFIG_REG
    56  ***************************************************************************************/
    57 
    58 #define MTTY_CONFIG_RX_ENABLE   1       // TTY_RX IRQ enabled if 1
    59 #define MTTY_CONFIG_TX_ENABLE   2       // TTY_TX IRQ enabled if 1
    60 
    61 /****************************************************************************************
    62  * This Rstructure is used by the soclib_multi_tty_isr for the RX channel.
    63  ***************************************************************************************/
    64 
    65 #define MTTY_FIFO_DEPTH  128
    66 
    67 typedef struct mtty_fifo_s     // 32 bytes
     79typedef struct mty_fifo_s
    6880{
    69     char          data[MTTY_FIFO_DEPTH];   // one char per slot
     81    char          data[MTY_FIFO_DEPTH];   // one char per slot
    7082    unsigned int  ptr;                    // next free slot index
    7183    unsigned int  ptw;                    // next full slot index
    7284    unsigned int  sts;                    // number of full slots
    73 } mtty_fifo_t;
    74  
     85}
     86mty_fifo_t;
    7587
    7688/****************************************************************************************
    77  * This function masks both the TTY_RX and TTY_TX IRQs.
    78  * These IRQs are unmasked by the soclib_multi_tty_cmd() function.
     89 * This function masks the TTY_RX IRQ.
    7990 ****************************************************************************************
    8091 * @ chdev     : pointer on the TXT chdev descriptor.
    8192 ***************************************************************************************/
    82 void soclib_mtty_init( chdev_t * chdev );
     93void soclib_mty_init( chdev_t * chdev );
    8394
    8495/****************************************************************************************
    … …  
    8798 * different chdevs (and consequently two diffeerent server threads) for the RX and TX
    8899 * directions. The client thread is identified by the <thread_xp> argument.
    89  * Depending on the command type, it unmasks the relevant TTY_RX / TTY_TX IRQ,
    90  * and blocks the TXT device server thread on the THREAD_BLOCKED_DEV_ISR, as the data
    91  * transfer is done by the ISR.
     100 * These functions are supposed to be called by the server thread associated at a
     101 * given TXT channel for a given direction (TX or RX).
     102 * Depending on the command type, it access the TX_FIFO or RX_FIFO, and blocks the TXT
     103 * device server thread on the THREAD_BLOCKED_DEV_ISR, if the RX_FIFO is empty (for a
     104 * READ), or if the TX_FIFO is full for a WRITE).
     105 * The actual transfer between the FIFOs and the TTY device registers is done by the ISR.
    92106 * ****************************************************************************************
    93107 * @ thread_xp : extended pointer on client thread descriptor.
    94108 ***************************************************************************************/
    95 void soclib_mtty_cmd( xptr_t thread_xp );
     109void soclib_mty_cmd( xptr_t thread_xp );
    96110
    97111/****************************************************************************************
    98112 * This function implements the TXT_SYNC_WRITE command registered in the txt_aux_t
    99  * structure, using a busy waiting policy, without using the TTY IRQ.
     113 * structure. As the MTY hardware component does not provide any status information,
     114 * it relies on the "blocking write" mechanism to the MTY_REGISTER for flow-control.
    100115 * It is used by the kernel do display debug messages on TXT0 terminal, without
    101116 * interference with another TXT access to another terminal done by the same thread.
    … …  
    103118 * @ thread_xp : pointer on the txt_aux_t structure containing the arguments.
    104119 ***************************************************************************************/
    105 void soclib_mtty_aux( void * args );
     120void soclib_mty_aux( void * args );
    106121
    107122/****************************************************************************************
    108  * This ISR is executed to handle both the TTY_TX_IRQ and the TTY_RX_IRQ, even if
    109  *   The RX_IRQ is activated as soon as the TTY_STATUS_RX_FULL bit is 1 in the
    110  *   TTY_STATUS register, when the TTY_RX_IRQ_ENABLE is non zero, indicating that
    111  *   the TTY_READ buffer is full and can be read.
    112  *   The TX_IRQ is activated as soon as the TTY_STATUS_TX_FULL bit is 0 in the
    113  *   TTY_STATUS register, when the TTY_TX_IRQ_ENABLE is non zero, indicating that
    114  *   the TTY_WRITE buffer is empty, and can be written.
    115  * WARNING : In ALMOS-MKH, the RX_IRQ is always enabled to catch the control signals,
    116  * but the TX_IRQ is dynamically enabled by the TXT_WRITE command, and disabled when
    117  * the command is completed.
     123 * This ISR is executed to handle both TX and RX transfers:
     124 * It is also in charge of multiplexing / demultiplexing the characters between
     125 * one single physical channel, and several virtual channels.
     126 * There is one couple of TX_FIFO / RX_FIFO per virtual channel, and each FIFO can be
     127 * located in a different cluster (in the same cluster as the associated chdev).
    118128 *
    119  * 1) The ISR first read the TTY_STATUS to get the current state of the TTY_READ and
    120  *   the TTY_WRITE buffers.
     129 * For both TX and TX, a character on the physical channel is encoded as two bytes:
     130 * The first byte contains the virtual channel index. The second byte contains
     131 * the ascii character value.
    121132 *
    122  * 2) It try to read the first command registered in the server thread queue associated
    123  *    to the TTY channel
     133 * - For RX, this ISR is called to move one character from the MTY_READ register to
     134 *   the relevant RX_FIFO when the MTY_RX_IRQ is activated (when the MTY_STATUS_RX_FULL
     135 *   bit, and the MTY_CONFIG_RX_ENABLE bit are both set), indicating that the MTY_READ
     136 *   register is full and can be read. As there is one single physical channel,
     137 *   there is one single MTY_RX_IRQ, that is routed to one single core that dispatch
     138 *   each received character to the relevant (likely remote) RX_FIFO.
     139 *   This core is supposed to be located in the same cluster as the MTY peripheral.
     140 *   
     141 * - For TX, there is no TX_IRQ handled by the MTY controller, and no status bit.
     142 *   Therefore, this ISR is called to move one character from one TX_FIFO to the
     143 *   MTY_WRITE register at each TICK event, and relies on the "blocking write"
     144 *   mechanism to the MTY_REGISTER for flow-control.
     145 *   As there is one single physical channel, this ISR is executed by one single core
     146 *   that scan the (likely remote) TX_FIFOs associated to all virtual channels,
     147 *   and transmit the first found character, with a round_robin policy between channels.
     148 *   This core is supposed to be located in the same cluster as the MTY peripheral.
    124149 *
    125  * 2) The ISR handles the RX when the TTY_READ buffer is full :
    126  *   . it read the available character from the TTY_READ buffer, and this
    127  *     acknowledges the RX_IRQ.
    128  *   . if it is a control character ( ^C / ^D / ^Z ) it translate it to the proper
    129  *     signal and execute the relevant sigaction for the foreground process.
    130  *   . if it is a normal character, it try to get the first command registered in the
    131  *     server thread queue. If it is a TXT_READ, it returns this character to the
    132  *     command buffer in the client thread.
    133  *
    134  * 3) The ISR handles the TX when the TTY_WRITE buffer is empty and a TXT_WRITE
    135  *   . it try to get it copies the
    136  *     character to the command buffer, acknowledges the TTY_RX_IRQ, and unblock the
    137  *     associated server thread.
    138      
    139  *   . the control characters ^C / ^D / ^Z  are directly handled by the ISR and
    140  *     translated to the foreground process.
    141 
    142  * - the
    143  the TXT_READ and TXT_WRITE commands.
    144  * It gets the command arguments from the first client thread in the TXT chdev queue:
    145  * - if TXT_READ, it transfers one byte from the TTY_READ_REG to the command buffer.
    146  *   It simply returns for retry if TTY_READ_REG is empty.
    147  * - if TXT_WRITE, it tries to transfer several bytes from the command buffer to the
    148  *   TTY_WRITE_REG. If the TTY_WRITE_REG is full, it updates the "count" and "buffer"
    149  *   command arguments and returns for retry.
    150  * When the I/O operation is completed, it sets the status field in the command, unblocks
    151  * the server thread, and unblocks the client thread.
     150 * The RX_IRQ is always enabled to catch the control characters (^C / ^D / ^Z),
     151 * that are not copied in the RX_FIFO, but directly analysed by the ISR
     152 * and signaled to the TXT owner process (foreground process).
    152153 ****************************************************************************************
    153154 * @ chdev     : local pointer on TXT chdev descriptor.
    154155 ***************************************************************************************/
    155 void soclib_mtty_isr( chdev_t * chdev );
     156void soclib_mty_isr( chdev_t * chdev );
    156157
Note: See TracChangeset for help on using the changeset viewer.