Index: trunk/hal/tsar_mips32/drivers/soclib_tty.h
===================================================================
--- trunk/hal/tsar_mips32/drivers/soclib_tty.h	(revision 436)
+++ trunk/hal/tsar_mips32/drivers/soclib_tty.h	(revision 457)
@@ -2,5 +2,5 @@
  * soclib_tty.c - soclib tty driver definition.
  *
- * Author  Alain Greiner (2016)
+ * Author  Alain Greiner (2016,2017,2018)
  *
  * Copyright (c)  UPMC Sorbonne Universites
@@ -29,7 +29,9 @@
 /****************************************************************************************
  * This driver supports the vci_tty_tsar component.
- * It implements the generic TXT device API:
+ * Regarding read/write request, 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).
  ***************************************************************************************/
 
@@ -101,47 +103,45 @@
 /****************************************************************************************
  * 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
+ * there is two different channel devices for TX and RX transfers.
+ *
+ * As the <chdev> argument is a local pointer, this ISR is always executed by a core
+ * that is in the same cluster as the core running the DEV server thread.
+ *
+ * - 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
+ * - 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,
+ *
+ * The RX_IRQ is always enabled to catch the control characters (^Z / ^C),
  * but the TX_IRQ is dynamically enabled by the TXT_WRITE command, and disabled when
  * the command is completed.
  *
- * 1) The ISR first read the TTY_STATUS to get the current state of the TTY_READ and
- *   the TTY_WRITE buffers.
+ * For normal characters The ISR uses two private TTY_RX and TTY_TX software FIFOs
+ * (two FIFOs per channel) to communicates with the DEV server thread executing the 
+ * soclib_tty_cmd() function.
+
+ * For an RX transfer, this ISR executes a while loop moving bytes until the source
+ * TTY_READ buffer is empty:
+ *   1) The ISR read one byte from the TTY_READ register and acknowledge the RX_IRQ.
+ *   2) if the byte is a ^Z character, it uses a multicast RPC to block all treads of
+ *      the TXT owner process, and transfer TXT ownership to another process of the group.
+ *   3) if the byte is a ^C character, it removes the process from the TXT group, and send
+ *      a multicast RPC to delete all threads of the TXT owner process.
+ *   4) if the byte is a normal character and the destination TTY_RX_FIFO is not full,
+ *      it writes the byte to this FIFO, unblock the TXT_RX server thread, and send an IPI
+ *      to this server thread (only if it is running on another core than the ISR). 
+ *   5) It discards the byte if the TTY_RX_FIFO is full, with a warning message on TXT0.
  *
- * 2) It try to read the first command registered in the server thread queue associated 
- *    to the TTY channel
- *
- * 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.
+ * For a TX transfer, this ISR executes a while loop moving bytes until the source
+ * TTY_TX_FIFO is empty:
+ *   1) if the destination TTY_WRITE register is not full, it moves the byte from the
+ *      TTY_TX_FIFO to the TTY_WRITE register.
+ *   2) if the TTY_WRITE register is full, it polls (busy waiting) the TTY_STATUS register,
+ *      until the TTY_WRITE register is empty.
+ *   3) when the source TTY_TX_FIFO is empty, this ISR disable the TTY_TX_IRQ, unblock
+ *      the TXT_TX server thread, and send an IPI to this server thread (only if it is
+ *      running on another core than the ISR). 
  ****************************************************************************************
  * @ chdev     : local pointer on TXT chdev descriptor.
