L4Re - L4 Runtime Environment
vcon
Go to the documentation of this file.
1 // vi:set ft=cpp: -*- Mode: C++ -*-
2 /**
3  * \file
4  * Virtual console interface.
5  */
6 /*
7  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
8  * Alexander Warg <warg@os.inf.tu-dresden.de>,
9  * Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
10  * economic rights: Technische Universit├Ąt Dresden (Germany)
11  *
12  * This file is part of TUD:OS and distributed under the terms of the
13  * GNU General Public License 2.
14  * Please see the COPYING-GPL-2 file for details.
15  *
16  * As a special exception, you may use this file as part of a free software
17  * library without restriction. Specifically, if other files instantiate
18  * templates or use macros or inline functions from this file, or you compile
19  * this file and link it with other files to produce an executable, this
20  * file does not by itself cause the resulting executable to be covered by
21  * the GNU General Public License. This exception does not however
22  * invalidate any other reasons why the executable file might be covered by
23  * the GNU General Public License.
24  */
25 #pragma once
26 
27 #include <l4/sys/icu>
28 #include <l4/sys/vcon.h>
29 #include <l4/sys/capability>
30 
31 namespace L4 {
32 
33 /**
34  * C++ L4 Vcon interface.
35  *
36  * L4::Vcon is a virtual console for simple character-based input and output.
37  * The interrupt for read events is provided by the virtual key interrupt.
38  *
39  * \includefile{l4/sys/vcon}
40  *
41  * See the \ref l4_vcon_api for the C interface.
42  */
43 class Vcon :
44  public Kobject_t<Vcon, Icu, L4_PROTO_LOG>
45 {
46 public:
47  /**
48  * Send data to `this` virtual console.
49  *
50  * \param buf Pointer to the data buffer.
51  * \param size Size of the data buffer in bytes.
52  * \param utcb UTBC pointer of the calling thread.
53  *
54  * \return Syscall return tag
55  *
56  * \note Size must not exceed #L4_VCON_WRITE_SIZE, a proper value of the
57  * `size` parameter is NOT checked. Also, this function is a send only
58  * operation, this means there is no return value except for a failed
59  * send operation. Use l4_ipc_error() to check for send errors, do not
60  * use l4_error(), as l4_error() will always return an error.
61  */
62  l4_msgtag_t
63  send(char const *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const throw()
64  { return l4_vcon_send_u(cap(), buf, size, utcb); }
65 
66  /**
67  * Write data to `this` virtual console.
68  *
69  * \param buf Pointer to the data buffer.
70  * \param size Size of the data buffer in bytes.
71  * \param utcb UTCB pointer of the calling thread.
72  *
73  * \retval <0 Error.
74  * \retval >=0 Number of bytes written to the virtual console.
75  */
76  long
77  write(char const *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const throw()
78  { return l4_vcon_write_u(cap(), buf, size, utcb); }
79 
80  /**
81  * Read data from `this` virtual console.
82  *
83  * \param[out] buf Pointer to data buffer.
84  * \param size Size of the data buffer in bytes.
85  * \param utcb UTCB pointer of the calling thread.
86  *
87  * \retval <0 Error code.
88  * \retval >size More bytes to read, `size` bytes are in the buffer `buf`.
89  * \retval <=size Number of bytes read.
90  *
91  * \note Size must not exceed #L4_VCON_READ_SIZE.
92  */
93  int
94  read(char *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const throw()
95  { return l4_vcon_read_u(cap(), buf, size, utcb); }
96 
97  /**
98  * Read data from `this` virtual console which also returns flags.
99  *
100  * \param[out] buf Pointer to data buffer.
101  * \param size Size of the data buffer in bytes.
102  * \param utcb UTCB pointer of the calling thread.
103  *
104  * \retval <0 Error code.
105  * \retval >size More bytes to read, `size` bytes are in the buffer `buf`.
106  * \retval <=size Number of bytes read.
107  *
108  * If this function returns a positive value the caller can check the
109  * #L4_VCON_READ_STAT_BREAK flag bit for a break condition. The bytes read
110  * can be obtained by masking the return value with #L4_VCON_READ_SIZE_MASK.
111  *
112  * If a break condition is signaled, it is always the first event in the
113  * transmitted content, i.e. all characters supplied by this read call follow
114  * the break condition.
115  *
116  * \note Size must not exceed #L4_VCON_READ_SIZE.
117  */
118  int
119  read_with_flags(char *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const throw()
120  { return l4_vcon_read_with_flags_u(cap(), buf, size, utcb); }
121 
122  /**
123  * Set the attributes of `this` virtual console.
124  *
125  * \param attr Attribute structure with the attributes for the virtual
126  * console.
127  * \param utcb UTCB pointer of the calling thread.
128  *
129  * \return Syscall return tag.
130  */
131  l4_msgtag_t
132  set_attr(l4_vcon_attr_t const *attr, l4_utcb_t *utcb = l4_utcb()) const throw()
133  { return l4_vcon_set_attr_u(cap(), attr, utcb); }
134 
135  /**
136  * Get attributes of `this` virtual console.
137  *
138  * \param[out] attr Attribute structure. Contains the attributes after a
139  * successfull call of this function.
140  * \param utcb UTCB pointer of the calling thread.
141  *
142  * \return Syscall return tag.
143  */
144  l4_msgtag_t
145  get_attr(l4_vcon_attr_t *attr, l4_utcb_t *utcb = l4_utcb()) const throw()
146  { return l4_vcon_get_attr_u(cap(), attr, utcb); }
147 
148  typedef L4::Typeid::Raw_ipc<Vcon> Rpcs;
149 };
150 
151 }