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

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

First import
File size: 7.7 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 <almos_config.h>
28#include <hal_types.h>
29
30/****  Forward declarations  ****/
31
32struct device_s ;
33
34/******************************************************************************************
35 *     Generic Text Terminal device definition.
36 *
37 * This multi-channels generic TXT device provide access to a text terminal.
38 * It supports three operation types :
39 * - TXT_READ : read a single character from the text terminal identified by its channel
40 *   index, using a descheduling strategy for the calling thread.
41 * - TXT_WRITE : write a character string to the text terminal identified by its channel
42 *   index, using a descheduling strategy for the calling thread.
43 * - TXT_SYNC_WRITE : write a character string to the terminal identified by its channel
44 *   index, using a busy waiting strategy for the calling thread.
45 *****************************************************************************************/
46
47/******************************************************************************************
48 * This enum defines the various implementations of the generic TXT peripheral.
49 * This array must be kept consistent with the define in arch_info.h file
50 *****************************************************************************************/
51
52enum txt_impl_e
53{
54    IMPL_TXT_TTY =   0,     
55    IMPL_TXT_X86 =   1, 
56}
57txt_impl_t;
58
59/******************************************************************************************
60 * This defines the (implementation independant) command passed to the driver.
61 *****************************************************************************************/
62
63enum
64{
65    TXT_READ       = 0,
66    TXT_WRITE      = 1,
67    TXT_SYNC_WRITE = 2,
68};
69
70typedef struct txt_command_s
71{
72    xptr_t      dev_xp;    /*! extended pointer on the relevant TXT device descriptor    */
73    uint32_t    type;      /*! TXT_READ / TXT_WRITE / TXT_SYNC_WRITE                     */
74    xptr_t      buf_xp;    /*! extended pointer on characters array                      */
75    uint32_t    count;     /*! number of characters in buffer (must be 1 if to_mem)      */
76    uint32_t    error;     /*! operation status (0 if success)                           */
77}
78txt_command_t;
79
80/******************************************************************************************
81 * This function completes the TXT device descriptor initialisation,
82 * namely the link with the implementation specific driver.
83 * The func, impl, channel, is_rxt, base, and size fields must be previously initialised.
84 * It calls the specific driver initialisation function, to initialise the hardware
85 * device and the driver specific data structures when required.
86 * It creates the associated server thread.
87 * It can be executed in another cluster than cluster containing the device descriptor
88 * or the hardware device itself.
89 ******************************************************************************************
90 * @ xp_dev     : extended pointer on TXT device descriptor.
91 *****************************************************************************************/
92void dev_txt_init( xptr_t xp_dev );
93
94/******************************************************************************************
95 * This blocking function read a single character from the terminal identified
96 * by the "channel" argument. The corresponding request is actually registered in the
97 * device pending requests queue, and the calling thread is descheduled, blocked until
98 * transfer completion.
99 * It must be called in the client cluster.
100 ******************************************************************************************
101 * @ channel   : TXT channel index.
102 * @ buffer    : local pointer on destination buffer for the character.
103 * @ returns 0 if success / returns EINVAL if error.
104 *****************************************************************************************/
105error_t dev_txt_read( uint32_t        channel,
106                      char          * buffer );
107
108/******************************************************************************************
109 * This blocking function writes a character string on the terminal identified
110 * by the "channel" argument. The corresponding request is actually registered in the
111 * device pending 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 source buffer containing the string.
117 * @ count     : number of characters.
118 * @ returns 0 if success / returns EINVAL if error.
119 ****************************************************************************************/
120error_t dev_txt_write( uint32_t        channel,
121                       char          * buffer,
122                       uint32_t        count );
123
124 /***************************************************************************************
125 * This low-level blocking function is used by the kernel to display one character on a
126 * given TXT channel without descheduling the calling thread,  without registering it
127 * in the TXT device waiting queue, and without using the TXT irq.
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_sync_write( uint32_t   channel,
135                            char     * buffer,
136                            uint32_t   count );
137
138/******************************************************************************************
139 * This function is executed by the server thread associated to the TXT device descriptor.
140 * This thread is created and lauched by the dev_txt_init() function, and is used
141 * by the TXT_READ and TXT_WRITE operation types. It executes an infinite loop to handle
142 * sequencially all commands registered by the client threads in the device waiting queue.
143 * 
144 * The driver CMD function is blocking, and returns only when the command is completed.
145 * can use a busy waiting policy, or block the server thread on the THREAD_BLOCKED_IO_ISR
146 * condition and deschedule, using the ISR to reactivate the server thread.
147 *
148 * When the waiting queue is empty, the server thread blocks on the THREAD_BLOCKED_IO_CMD
149 * condition and deschedule. It is re-activated by a client thread registering a command.
150 ******************************************************************************************
151 * @ dev     : local pointer on device descriptor.
152 *****************************************************************************************/
153void dev_txt_server( struct device_s * dev );
154
155
156#endif  /* _DEV_TXT_H_ */
Note: See TracBrowser for help on using the repository browser.