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 | |
---|
32 | struct chdev_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 | |
---|
52 | enum txt_impl_e |
---|
53 | { |
---|
54 | IMPL_TXT_TTY = 0, |
---|
55 | IMPL_TXT_X86 = 1, |
---|
56 | } |
---|
57 | txt_impl_t; |
---|
58 | |
---|
59 | /****************************************************************************************** |
---|
60 | * This defines the (implementation independant) command passed to the driver. |
---|
61 | *****************************************************************************************/ |
---|
62 | |
---|
63 | enum |
---|
64 | { |
---|
65 | TXT_READ = 0, |
---|
66 | TXT_WRITE = 1, |
---|
67 | TXT_SYNC_WRITE = 2, |
---|
68 | }; |
---|
69 | |
---|
70 | typedef 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 | } |
---|
78 | txt_command_t; |
---|
79 | |
---|
80 | /****************************************************************************************** |
---|
81 | * This function completes the TXT chdev descriptor initialisation, |
---|
82 | i * namely the link with the implementation specific driver. |
---|
83 | * The func, impl, channel, is_rxt, base fields have been 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 and allocates a WTI from local ICU. |
---|
87 | * It must de executed by a local thread. |
---|
88 | ****************************************************************************************** |
---|
89 | * @ chdev : local pointer on TXT device descriptor. |
---|
90 | *****************************************************************************************/ |
---|
91 | void dev_txt_init( struct chdev_s * chdev ); |
---|
92 | |
---|
93 | /****************************************************************************************** |
---|
94 | * This blocking function read a single character from the terminal identified |
---|
95 | * by the "channel" argument. The corresponding request is actually registered in the |
---|
96 | * chdev requests queue, and the calling thread is descheduled, blocked until |
---|
97 | * transfer completion. |
---|
98 | * It must be called in the client cluster. |
---|
99 | ****************************************************************************************** |
---|
100 | * @ channel : TXT channel index. |
---|
101 | * @ buffer : local pointer on destination buffer for the character. |
---|
102 | * @ returns 0 if success / returns EINVAL if error. |
---|
103 | *****************************************************************************************/ |
---|
104 | error_t dev_txt_read( uint32_t channel, |
---|
105 | char * buffer ); |
---|
106 | |
---|
107 | /****************************************************************************************** |
---|
108 | * This blocking function writes a character string on the terminal identified |
---|
109 | * by the "channel" argument. The corresponding request is actually registered in the |
---|
110 | * chdev requests queue, and the calling thread is descheduled, blocked until |
---|
111 | * transfer completion. |
---|
112 | * It must be called in the client cluster. |
---|
113 | ****************************************************************************************** |
---|
114 | * @ channel : TXT channel index. |
---|
115 | * @ buffer : local pointer on source buffer containing the string. |
---|
116 | * @ count : number of characters. |
---|
117 | * @ returns 0 if success / returns EINVAL if error. |
---|
118 | ****************************************************************************************/ |
---|
119 | error_t dev_txt_write( uint32_t channel, |
---|
120 | char * buffer, |
---|
121 | uint32_t count ); |
---|
122 | |
---|
123 | /*************************************************************************************** |
---|
124 | * This low-level blocking function is used by the kernel to display one string on a |
---|
125 | * given TXT channel without descheduling the calling thread, without registering it |
---|
126 | * in the TXT device waiting queue, and without using the TXT irq. |
---|
127 | **************************************************************************************** |
---|
128 | * @ channel : TXT channel index. |
---|
129 | * @ buffer : local pointer on source buffer containing the string. |
---|
130 | * @ count : number of characters. |
---|
131 | * @ returns 0 if success / returns EINVAL if error. |
---|
132 | ***************************************************************************************/ |
---|
133 | error_t dev_txt_sync_write( uint32_t channel, |
---|
134 | char * buffer, |
---|
135 | uint32_t count ); |
---|
136 | |
---|
137 | |
---|
138 | #endif /* _DEV_TXT_H_ */ |
---|