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

Last change on this file since 619 was 565, checked in by alain, 5 years ago

Complete restructuration of kernel locks.

File size: 8.5 KB
RevLine 
[1]1/*
2 * dev_txt.h - TXT (Text Terminal) generic device API definition.
[49]3 *
[1]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
[14]27#include <kernel_config.h>
[457]28#include <hal_kernel_types.h>
[422]29#include <xlist.h>
[565]30#include <remote_busylock.h>
[1]31
32/****  Forward declarations  ****/
33
[3]34struct chdev_s ;
[1]35
36/******************************************************************************************
37 *     Generic Text Terminal device definition.
38 *
[49]39 * This multi-channels generic TXT device provides access to a text terminal.
[407]40 *
41 * It supports two operations that must be implemented by the driver cmd() function:
[1]42 * - TXT_READ : read a single character from the text terminal identified by its channel
43 *   index, using a descheduling strategy for the calling thread.
44 * - TXT_WRITE : write a character string to the text terminal identified by its channel
45 *   index, using a descheduling strategy for the calling thread.
[407]46 *
47 * It supports one operation, that must be implemented by the driver aux() function 
48 * - TXT_SYNC_WRITE write a character string to the TXT0 kernel terminal, using a busy
49 *   waiting strategy for the calling thread.
[1]50 *****************************************************************************************/
51
52/******************************************************************************************
[422]53 * This defines the (implementation independant) extension for the generic TXT device.
54 *****************************************************************************************/
55
56typedef struct txt_extend_s
57{
58    xptr_t            owner_xp;  /*! ext. pointer on current process owner (reference)   */
[565]59    xlist_entry_t     root;      /*! root of list of processes attached to same TXT      */
60    remote_busylock_t lock;      /*! lock protecting this list                           */
[422]61}
62txt_extend_t;
63
64/******************************************************************************************
[1]65 * This enum defines the various implementations of the generic TXT peripheral.
66 * This array must be kept consistent with the define in arch_info.h file
67 *****************************************************************************************/
68
69enum txt_impl_e
70{
[49]71    IMPL_TXT_TTY =   0,
[254]72    IMPL_TXT_RS2 =   1,
[534]73    IMPL_TXT_MTY =   2,
[1]74}
75txt_impl_t;
76
77/******************************************************************************************
[407]78 * This defines the arguments passed to the driver CMD function.
[1]79 *****************************************************************************************/
80
[527]81typedef enum
[1]82{
83    TXT_READ       = 0,
84    TXT_WRITE      = 1,
[435]85    TXT_SYNC_WRITE = 2,
[527]86} dev_txt_cmd_t;
[1]87
88typedef struct txt_command_s
89{
90    xptr_t      dev_xp;    /*! extended pointer on the relevant TXT device descriptor    */
[435]91    uint32_t    type;      /*! TXT_READ / TXT_WRITE                                      */
[1]92    xptr_t      buf_xp;    /*! extended pointer on characters array                      */
93    uint32_t    count;     /*! number of characters in buffer (must be 1 if to_mem)      */
94    uint32_t    error;     /*! operation status (0 if success)                           */
95}
96txt_command_t;
97
98/******************************************************************************************
[407]99 * This defines the arguments passed to the driver AUX function.
100 * This function implement the TXT_SYNC_WRITE operation.
101 *****************************************************************************************/
102
[435]103typedef struct txt_sync_args_s
[407]104{
[565]105    xptr_t       dev_xp;    /*! extended pointer on the TXT0_TX device descriptor        */
106    const char * buffer;    /*! local pointer on characters array                        */
107    uint32_t     count;     /*! number of characters in buffer                           */
[539]108    uint32_t    channel;   /*! channel, aka which tty to write to                        */
[407]109}
[435]110txt_sync_args_t;
[407]111
112/******************************************************************************************
[435]113 * This function returns a printable string for the comman type.
114 ******************************************************************************************
115 * @ type     : command type (TXT_READ / TXT_WRITE / TXT_SYNC_WRITE)
116 *****************************************************************************************/
[527]117const char * dev_txt_type_str( dev_txt_cmd_t type );
[435]118
119/******************************************************************************************
[3]120 * This function completes the TXT chdev descriptor initialisation,
[49]121 * namely the link with the implementation specific driver.
[3]122 * The func, impl, channel, is_rxt, base fields have been previously initialised.
[1]123 * It calls the specific driver initialisation function, to initialise the hardware
124 * device and the driver specific data structures when required.
[3]125 * It creates the associated server thread and allocates a WTI from local ICU.
126 * It must de executed by a local thread.
[1]127 ******************************************************************************************
[3]128 * @ chdev     : local pointer on TXT device descriptor.
[1]129 *****************************************************************************************/
[3]130void dev_txt_init( struct chdev_s * chdev );
[1]131
132/******************************************************************************************
[49]133 * This blocking function reads a single character from the terminal identified
[1]134 * by the "channel" argument. The corresponding request is actually registered in the
[3]135 * chdev requests queue, and the calling thread is descheduled, blocked until
[1]136 * transfer completion.
137 * It must be called in the client cluster.
138 ******************************************************************************************
139 * @ channel   : TXT channel index.
140 * @ buffer    : local pointer on destination buffer for the character.
141 * @ returns 0 if success / returns EINVAL if error.
142 *****************************************************************************************/
143error_t dev_txt_read( uint32_t        channel,
144                      char          * buffer );
145
146/******************************************************************************************
[49]147 * This blocking function writes characters on the terminal identified
[1]148 * by the "channel" argument. The corresponding request is actually registered in the
[3]149 * chdev requests queue, and the calling thread is descheduled, blocked until
[1]150 * transfer completion.
151 * It must be called in the client cluster.
152 ******************************************************************************************
153 * @ channel   : TXT channel index.
154 * @ buffer    : local pointer on source buffer containing the string.
155 * @ count     : number of characters.
156 * @ returns 0 if success / returns EINVAL if error.
157 ****************************************************************************************/
158error_t dev_txt_write( uint32_t        channel,
159                       char          * buffer,
160                       uint32_t        count );
161
[49]162/***************************************************************************************
[407]163 * This blocking function is used by the kernel to display a string on the TXT0
164 * terminal, without descheduling the calling thread, without registering it
165 * in the TXT0 device waiting queue, without using the TXT0 irq, and without
166 * interfering with another possible TXT access to another terminal.
167 * As it is used for debug, the command arguments <buffer> and <count> are registerd
168 * in a specific "dbg_cmd" field of the calling thread.
[1]169 ****************************************************************************************
170 * @ buffer    : local pointer on source buffer containing the string.
171 * @ count     : number of characters.
172 * @ returns 0 if success / returns EINVAL if error.
173 ***************************************************************************************/
[565]174error_t dev_txt_sync_write( const char     * buffer,
175                            uint32_t         count );
[1]176
177#endif  /* _DEV_TXT_H_ */
Note: See TracBrowser for help on using the repository browser.