source: trunk/hal/tsar_mips32/drivers/soclib_mty.h @ 672

Last change on this file since 672 was 570, checked in by alain, 6 years ago

Introduction of the soclib_mty driver for the TSAR-LETI architecture.
File size: 8.4 KB
Line 
1/*
2 * soclib_mty.c - soclib_mty driver definition (used in TSAR-LETI architecture).
3 *
4 * Author  Alain Greiner (2016,2017,2018)
5 *
6 * Copyright (c)  UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#include <dev_txt.h>
25#include <chdev.h>
26
27
28/****************************************************************************************
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 *
43 * It implements the generic TXT device API:
44 * - transfer one single character from TTY to command "buffer" if to_mem is non-zero.
45 * - 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
58 ***************************************************************************************/
59
60#define MTY_WRITE              0
61#define MTY_STATUS             1
62#define MTY_READ               2
63#define MTY_CONFIG             3
64
65/****************************************************************************************
66 * masks for MTY_STATUS and MTY_CONFIG registers
67 ***************************************************************************************/
68
69#define MTY_STATUS_RX_FULL     1          // TTY_READ_REG full if 1
70
71#define MTY_CONFIG_RX_ENABLE   1          // RX_IRQ enable if 1
72
73/****************************************************************************************
74 * This structure is used for both the RX_FIFO and the TX_FIFO.
75 ***************************************************************************************/
76
77#define MTY_FIFO_DEPTH  128
78
79typedef struct mty_fifo_s
80{
81    char          data[MTY_FIFO_DEPTH];   // one char per slot
82    unsigned int  ptr;                    // next free slot index
83    unsigned int  ptw;                    // next full slot index
84    unsigned int  sts;                    // number of full slots
85}
86mty_fifo_t;
87
88/****************************************************************************************
89 * This function masks the TTY_RX IRQ.
90 ****************************************************************************************
91 * @ chdev     : pointer on the TXT chdev descriptor.
92 ***************************************************************************************/
93void soclib_mty_init( chdev_t * chdev );
94
95/****************************************************************************************
96 * This function implements both the TXT_READ & TXT_WRITE commands registered in the
97 * client thread descriptor (in the txt_cmd field), even if ALMOS-MKH defines two
98 * different chdevs (and consequently two diffeerent server threads) for the RX and TX
99 * directions. The client thread is identified by the <thread_xp> argument.
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.
106 * ****************************************************************************************
107 * @ thread_xp : extended pointer on client thread descriptor.
108 ***************************************************************************************/
109void soclib_mty_cmd( xptr_t thread_xp );
110
111/****************************************************************************************
112 * This function implements the TXT_SYNC_WRITE command registered in the txt_aux_t
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.
115 * It is used by the kernel do display debug messages on TXT0 terminal, without
116 * interference with another TXT access to another terminal done by the same thread.
117 ****************************************************************************************
118 * @ thread_xp : pointer on the txt_aux_t structure containing the arguments.
119 ***************************************************************************************/
120void soclib_mty_aux( void * args );
121
122/****************************************************************************************
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).
128 *
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.
132 *
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.
149 *
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).
153 ****************************************************************************************
154 * @ chdev     : local pointer on TXT chdev descriptor.
155 ***************************************************************************************/
156void soclib_mty_isr( chdev_t * chdev );
157
Note: See TracBrowser for help on using the repository browser.