source: trunk/kernel/devices/dev_txt.h @ 416

Last change on this file since 416 was 407, checked in by alain, 7 years ago

First implementation of fork/exec.
File size: 7.3 KB
Line 
1/*
2 * dev_txt.h - TXT (Text Terminal) generic device API definition.
3 *
4 * Author  Alain Greiner    (2016)
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#ifndef _DEV_TXT_H_
25#define _DEV_TXT_H_
26
27#include <kernel_config.h>
28#include <hal_types.h>
29
30/****  Forward declarations  ****/
31
32struct chdev_s ;
33
34/******************************************************************************************
35 *     Generic Text Terminal device definition.
36 *
37 * This multi-channels generic TXT device provides access to a text terminal.
38 *
39 * It supports two operations that must be implemented by the driver cmd() function:
40 * - TXT_READ : read a single character from the text terminal identified by its channel
41 *   index, using a descheduling strategy for the calling thread.
42 * - TXT_WRITE : write a character string to the text terminal identified by its channel
43 *   index, using a descheduling strategy for the calling thread.
44 *
45 * It supports one operation, that must be implemented by the driver aux() function 
46 * - TXT_SYNC_WRITE write a character string to the TXT0 kernel terminal, using a busy
47 *   waiting strategy for the calling thread.
48 *****************************************************************************************/
49
50/******************************************************************************************
51 * This enum defines the various implementations of the generic TXT peripheral.
52 * This array must be kept consistent with the define in arch_info.h file
53 *****************************************************************************************/
54
55enum txt_impl_e
56{
57    IMPL_TXT_TTY =   0,
58    IMPL_TXT_RS2 =   1,
59}
60txt_impl_t;
61
62/******************************************************************************************
63 * This defines the arguments passed to the driver CMD function.
64 *****************************************************************************************/
65
66enum
67{
68    TXT_READ       = 0,
69    TXT_WRITE      = 1,
70};
71
72typedef struct txt_command_s
73{
74    xptr_t      dev_xp;    /*! extended pointer on the relevant TXT device descriptor    */
75    uint32_t    type;      /*! TXT_READ / TXT_WRITE / TXT_SYNC_WRITE                     */
76    xptr_t      buf_xp;    /*! extended pointer on characters array                      */
77    uint32_t    count;     /*! number of characters in buffer (must be 1 if to_mem)      */
78    uint32_t    error;     /*! operation status (0 if success)                           */
79}
80txt_command_t;
81
82/******************************************************************************************
83 * This defines the arguments passed to the driver AUX function.
84 * This function implement the TXT_SYNC_WRITE operation.
85 *****************************************************************************************/
86
87typedef struct txt_aux_s
88{
89    xptr_t      dev_xp;    /*! extended pointer on the TXT0 device descriptor            */
90    char      * buffer;    /*! local pointer on characters array                         */
91    uint32_t    count;     /*! number of characters in buffer                            */
92}
93txt_aux_t;
94
95/******************************************************************************************
96 * This function completes the TXT chdev descriptor initialisation,
97 * namely the link with the implementation specific driver.
98 * The func, impl, channel, is_rxt, base fields have been previously initialised.
99 * It calls the specific driver initialisation function, to initialise the hardware
100 * device and the driver specific data structures when required.
101 * It creates the associated server thread and allocates a WTI from local ICU.
102 * It must de executed by a local thread.
103 ******************************************************************************************
104 * @ chdev     : local pointer on TXT device descriptor.
105 *****************************************************************************************/
106void dev_txt_init( struct chdev_s * chdev );
107
108/******************************************************************************************
109 * This blocking function reads a single character from the terminal identified
110 * by the "channel" argument. The corresponding request is actually registered in the
111 * chdev requests queue, and the calling thread is descheduled, blocked until
112 * transfer completion.
113 * It must be called in the client cluster.
114 ******************************************************************************************
115 * @ channel   : TXT channel index.
116 * @ buffer    : local pointer on destination buffer for the character.
117 * @ returns 0 if success / returns EINVAL if error.
118 *****************************************************************************************/
119error_t dev_txt_read( uint32_t        channel,
120                      char          * buffer );
121
122/******************************************************************************************
123 * This blocking function writes characters on the terminal identified
124 * by the "channel" argument. The corresponding request is actually registered in the
125 * chdev requests queue, and the calling thread is descheduled, blocked until
126 * transfer completion.
127 * It must be called in the client cluster.
128 ******************************************************************************************
129 * @ channel   : TXT channel index.
130 * @ buffer    : local pointer on source buffer containing the string.
131 * @ count     : number of characters.
132 * @ returns 0 if success / returns EINVAL if error.
133 ****************************************************************************************/
134error_t dev_txt_write( uint32_t        channel,
135                       char          * buffer,
136                       uint32_t        count );
137
138/***************************************************************************************
139 * This blocking function is used by the kernel to display a string on the TXT0
140 * terminal, without descheduling the calling thread, without registering it
141 * in the TXT0 device waiting queue, without using the TXT0 irq, and without
142 * interfering with another possible TXT access to another terminal.
143 * As it is used for debug, the command arguments <buffer> and <count> are registerd
144 * in a specific "dbg_cmd" field of the calling thread.
145 * other TXT accesses.
146 ****************************************************************************************
147 * @ buffer    : local pointer on source buffer containing the string.
148 * @ count     : number of characters.
149 * @ returns 0 if success / returns EINVAL if error.
150 ***************************************************************************************/
151error_t dev_txt_sync_write( char     * buffer,
152                            uint32_t   count );
153
154#endif  /* _DEV_TXT_H_ */
Note: See TracBrowser for help on using the repository browser.