Changeset 570 for trunk/hal/tsar_mips32/drivers/soclib_tty.h

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:

• trunk/hal/tsar_mips32/drivers/soclib_tty.h (modified) (5 diffs)

trunk/hal/tsar_mips32/drivers/soclib_tty.h

@@ -1 +1 @@
 /*
- * soclib_tty.c - soclib tty driver definition.
+ * soclib_tty.c - soclib_tty driver definition (used in the TSAR_IOB architecture).
  *
  * Author  Alain Greiner (2016,2017,2018)
@@ -24 +24 @@
 #include <dev_txt.h>
 #include <chdev.h>
-#include <spinlock.h>
 
 
 /****************************************************************************************
  * This driver supports the vci_tty_tsar component.
- * Regarding read/write request, it implements the generic TXT device API:
+ *
+ * 1) This hardware component handles several hardware channels, supporting directly
+ *    several kernel TXT channels.
+ * 2) For received characters, the hardware support one RX_IRQ, and one bit 
+ *    in the STATUS register to signal that the READ register is full. 
+ * 3) For transmitted characters, the hardware supports one RX_IRQ, and one bit
+ *    in STATUS register to signal that the WRITE register is empty.
+ * 
+ * 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.
+ * - 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).
  ***************************************************************************************/
 
@@ -56 +69 @@
 
 /****************************************************************************************
- * This Rstructure is used by the soclib_tty_isr for the RX channel.
+ * This structure is used for both the RX_FIFO and the TX_FIFO.
  ***************************************************************************************/
 
 #define TTY_FIFO_DEPTH  128
 
-typedef struct tty_fifo_s     // 32 bytes
+typedef struct tty_fifo_s 
 {
     char          data[TTY_FIFO_DEPTH];   // one char per slot
@@ -67 +80 @@
     unsigned int  ptw;                    // next full slot index
     unsigned int  sts;                    // number of full slots
-} tty_fifo_t;
- 
+} 
+tty_fifo_t;
 
 /****************************************************************************************
@@ -83 +96 @@
  * 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.