Index: trunk/hal/tsar_mips32/drivers/soclib_mty.h
===================================================================
--- trunk/hal/tsar_mips32/drivers/soclib_mtty.h	(revision 534)
+++ trunk/hal/tsar_mips32/drivers/soclib_mty.h	(revision 570)
@@ -1,6 +1,6 @@
 /*
- * soclib_multi_tty.c - soclib tty driver definition.
+ * soclib_mty.c - soclib_mty driver definition (used in TSAR-LETI architecture).
  *
- * Author  Alain Greiner (2016)
+ * Author  Alain Greiner (2016,2017,2018)
  *
  * Copyright (c)  UPMC Sorbonne Universites
@@ -24,61 +24,72 @@
 #include <dev_txt.h>
 #include <chdev.h>
-#include <spinlock.h>
 
 
 /****************************************************************************************
- * This driver supports the soclib_multi_tty component.
+ * This driver supports the "backup" TTY controler implemented in cluster 0
+ * of the TSAR-LETI architecture, that is actually an over-simplified version
+ * of the vci_tty_tsar component:
+ *
+ * 1) This hardware component handles only ONE TTY physical channel, that must 
+ *    be virtualized by the driver to support several kernel TXT devices.
+ * 2) For received characters, the hardware support one RX_IRQ, and one bit 
+ *    in the MTY_STATUS register to signal that the MTY_READ register is full. 
+ * 3) For transmitted characters, the hardware does NOT provide a TX_IRQ, 
+ *    and does NOT provide status information about the MTY_WRITE register,
+ *    but implement a low-level flow control mechanism: the response to the
+ *    VCI write request in MTY_WRITE register is blocked until this register
+ *    can be actually written...
+ *
  * It implements the generic TXT device API:
  * - transfer one single character from TTY to command "buffer" if to_mem is non-zero.
  * - transfer "count" characters from command "buffer" to TTY if "to_mem is zero.
+ *
+ * It handles asynchronous control characters (^C / ^Z), that are translated to signals
+ * transmited to the TXT owner process (foreground process).
+ *
+ * This driver implements one TX_FIFO for the transmited characters, writen by the "cmd"
+ * function, and read by the "isr" function).
+ * This driver implements one RX_FIFO for the received characters, writen by the "isr"
+ * function, and read by the "cmd" function).
+***************************************************************************************/
+
+/****************************************************************************************
+ *     SOCLIB_MTY registers offsets and masks
  ***************************************************************************************/
 
+#define MTY_WRITE              0
+#define MTY_STATUS             1
+#define MTY_READ               2
+#define MTY_CONFIG             3
+
 /****************************************************************************************
- *     SOCLIB_TTY registers offsets
+ * masks for MTY_STATUS and MTY_CONFIG registers
  ***************************************************************************************/
 
-#define MTTY_WRITE              0
-#define MTTY_STATUS             1
-#define MTTY_READ               2
-#define MTTY_CONFIG             3
+#define MTY_STATUS_RX_FULL     1          // TTY_READ_REG full if 1
 
-#define MTTY_SPAN               4  
+#define MTY_CONFIG_RX_ENABLE   1          // RX_IRQ enable if 1
 
 /****************************************************************************************
- * masks for TTY_STATUS_REG
+ * This structure is used for both the RX_FIFO and the TX_FIFO.
  ***************************************************************************************/
 
-#define MTTY_STATUS_RX_FULL     1       // TTY_READ_REG full if 1
-#define MTTY_STATUS_TX_FULL     2       // TTY_WRITE_REG full if 1
+#define MTY_FIFO_DEPTH  128
 
-/****************************************************************************************
- * masks for TTY_CONFIG_REG
- ***************************************************************************************/
-
-#define MTTY_CONFIG_RX_ENABLE   1       // TTY_RX IRQ enabled if 1
-#define MTTY_CONFIG_TX_ENABLE   2       // TTY_TX IRQ enabled if 1
-
-/****************************************************************************************
- * This Rstructure is used by the soclib_multi_tty_isr for the RX channel.
- ***************************************************************************************/
-
-#define MTTY_FIFO_DEPTH  128
-
-typedef struct mtty_fifo_s     // 32 bytes
+typedef struct mty_fifo_s 
 {
-    char          data[MTTY_FIFO_DEPTH];   // one char per slot
+    char          data[MTY_FIFO_DEPTH];   // one char per slot
     unsigned int  ptr;                    // next free slot index
     unsigned int  ptw;                    // next full slot index
     unsigned int  sts;                    // number of full slots
-} mtty_fifo_t;
- 
+}
+mty_fifo_t;
 
 /****************************************************************************************
- * This function masks both the TTY_RX and TTY_TX IRQs.
- * These IRQs are unmasked by the soclib_multi_tty_cmd() function.
+ * This function masks the TTY_RX IRQ.
  ****************************************************************************************
  * @ chdev     : pointer on the TXT chdev descriptor.
  ***************************************************************************************/
-void soclib_mtty_init( chdev_t * chdev );
+void soclib_mty_init( chdev_t * chdev );
 
 /****************************************************************************************
@@ -87,15 +98,19 @@
  * different chdevs (and consequently two diffeerent server threads) for the RX and TX
  * directions. The client thread is identified by the <thread_xp> argument.
- * Depending on the command type, it unmasks the relevant TTY_RX / TTY_TX IRQ,
- * and blocks the TXT device server thread on the THREAD_BLOCKED_DEV_ISR, as the data
- * transfer is done by the ISR.
+ * These functions are supposed to be called by the server thread associated at a
+ * given TXT channel for a given direction (TX or RX).
+ * Depending on the command type, it access the TX_FIFO or RX_FIFO, and blocks the TXT
+ * device server thread on the THREAD_BLOCKED_DEV_ISR, if the RX_FIFO is empty (for a
+ * READ), or if the TX_FIFO is full for a WRITE). 
+ * The actual transfer between the FIFOs and the TTY device registers is done by the ISR.
  * ****************************************************************************************
  * @ thread_xp : extended pointer on client thread descriptor.
  ***************************************************************************************/
-void soclib_mtty_cmd( xptr_t thread_xp );
+void soclib_mty_cmd( xptr_t thread_xp );
 
 /****************************************************************************************
  * This function implements the TXT_SYNC_WRITE command registered in the txt_aux_t
- * structure, using a busy waiting policy, without using the TTY IRQ.
+ * structure. As the MTY hardware component does not provide any status information,
+ * it relies on the "blocking write" mechanism to the MTY_REGISTER for flow-control. 
  * It is used by the kernel do display debug messages on TXT0 terminal, without
  * interference with another TXT access to another terminal done by the same thread.
@@ -103,54 +118,40 @@
  * @ thread_xp : pointer on the txt_aux_t structure containing the arguments.
  ***************************************************************************************/
-void soclib_mtty_aux( void * args );
+void soclib_mty_aux( void * args );
 
 /****************************************************************************************
- * This ISR is executed to handle both the TTY_TX_IRQ and the TTY_RX_IRQ, even if
- *   The RX_IRQ is activated as soon as the TTY_STATUS_RX_FULL bit is 1 in the
- *   TTY_STATUS register, when the TTY_RX_IRQ_ENABLE is non zero, indicating that
- *   the TTY_READ buffer is full and can be read.
- *   The TX_IRQ is activated as soon as the TTY_STATUS_TX_FULL bit is 0 in the
- *   TTY_STATUS register, when the TTY_TX_IRQ_ENABLE is non zero, indicating that
- *   the TTY_WRITE buffer is empty, and can be written.
- * WARNING : In ALMOS-MKH, the RX_IRQ is always enabled to catch the control signals,
- * but the TX_IRQ is dynamically enabled by the TXT_WRITE command, and disabled when
- * the command is completed.
+ * This ISR is executed to handle both TX and RX transfers:
+ * It is also in charge of multiplexing / demultiplexing the characters between
+ * one single physical channel, and several virtual channels.
+ * There is one couple of TX_FIFO / RX_FIFO per virtual channel, and each FIFO can be
+ * located in a different cluster (in the same cluster as the associated chdev).
  *
- * 1) The ISR first read the TTY_STATUS to get the current state of the TTY_READ and
- *   the TTY_WRITE buffers.
+ * For both TX and TX, a character on the physical channel is encoded as two bytes:
+ * The first byte contains the virtual channel index. The second byte contains 
+ * the ascii character value. 
  *
- * 2) It try to read the first command registered in the server thread queue associated 
- *    to the TTY channel
+ * - For RX, this ISR is called to move one character from the MTY_READ register to
+ *   the relevant RX_FIFO when the MTY_RX_IRQ is activated (when the MTY_STATUS_RX_FULL 
+ *   bit, and the MTY_CONFIG_RX_ENABLE bit are both set), indicating that the MTY_READ
+ *   register is full and can be read. As there is one single physical channel,
+ *   there is one single MTY_RX_IRQ, that is routed to one single core that dispatch
+ *   each received character to the relevant (likely remote) RX_FIFO.
+ *   This core is supposed to be located in the same cluster as the MTY peripheral.
+ *    
+ * - For TX, there is no TX_IRQ handled by the MTY controller, and no status bit.
+ *   Therefore, this ISR is called to move one character from one TX_FIFO to the
+ *   MTY_WRITE register at each TICK event, and relies on the "blocking write"
+ *   mechanism to the MTY_REGISTER for flow-control. 
+ *   As there is one single physical channel, this ISR is executed by one single core 
+ *   that scan the (likely remote) TX_FIFOs associated to all virtual channels, 
+ *   and transmit the first found character, with a round_robin policy between channels.
+ *   This core is supposed to be located in the same cluster as the MTY peripheral.
  *
- * 2) The ISR handles the RX when the TTY_READ buffer is full :
- *   . it read the available character from the TTY_READ buffer, and this
- *     acknowledges the RX_IRQ.
- *   . if it is a control character ( ^C / ^D / ^Z ) it translate it to the proper
- *     signal and execute the relevant sigaction for the foreground process.
- *   . if it is a normal character, it try to get the first command registered in the 
- *     server thread queue. If it is a TXT_READ, it returns this character to the 
- *     command buffer in the client thread.
- * 
- * 3) The ISR handles the TX when the TTY_WRITE buffer is empty and a TXT_WRITE
- *   . it try to get it copies the
- *     character to the command buffer, acknowledges the TTY_RX_IRQ, and unblock the 
- *     associated server thread.
-     
- *   . the control characters ^C / ^D / ^Z  are directly handled by the ISR and
- *     translated to the foreground process.
-
- * - the 
- the TXT_READ and TXT_WRITE commands.
- * It gets the command arguments from the first client thread in the TXT chdev queue:
- * - if TXT_READ, it transfers one byte from the TTY_READ_REG to the command buffer.
- *   It simply returns for retry if TTY_READ_REG is empty.
- * - if TXT_WRITE, it tries to transfer several bytes from the command buffer to the
- *   TTY_WRITE_REG. If the TTY_WRITE_REG is full, it updates the "count" and "buffer"
- *   command arguments and returns for retry.
- * When the I/O operation is completed, it sets the status field in the command, unblocks
- * the server thread, and unblocks the client thread.
+ * The RX_IRQ is always enabled to catch the control characters (^C / ^D / ^Z),
+ * that are not copied in the RX_FIFO, but directly analysed by the ISR
+ * and signaled to the TXT owner process (foreground process).
  ****************************************************************************************
  * @ chdev     : local pointer on TXT chdev descriptor.
  ***************************************************************************************/
-void soclib_mtty_isr( chdev_t * chdev );
+void soclib_mty_isr( chdev_t * chdev );
 
