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
31namespace 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 * The Vcon interface inherits from L4::Icu and L4::Irq_eoi for managing the
40 * virtual key interrupt which, in contrast to hardware IRQs, implements a
41 * limited functionality:
42 *  - Only IRQ line 0 is supported, no MSI vectors.
43 *  - The IRQ is edge-triggered and the IRQ mode cannot be changed.
44 *  - As the IRQ is edge-triggered, it does not have to be explicitly unmasked.
45 *
46 * \includefile{l4/sys/vcon}
47 *
48 * See the \ref l4_vcon_api for the C interface.
49 */
50class Vcon :
51  public Kobject_t<Vcon, Icu, L4_PROTO_LOG>
52{
53public:
54  /**
55   * Send data to `this` virtual console.
56   *
57   * \param buf   Pointer to the data buffer.
58   * \param size  Size of the data buffer in bytes.
59   * \param utcb  UTBC pointer of the calling thread.
60   *
61   * \return Syscall return tag
62   *
63   * \note Size must not exceed #L4_VCON_WRITE_SIZE, a proper value of the
64   *       `size` parameter is NOT checked. Also, this function is a send only
65   *       operation, this means there is no return value except for a failed
66   *       send operation. Use l4_ipc_error() to check for send errors, do not
67   *       use l4_error(), as l4_error() will always return an error.
68   */
69  l4_msgtag_t
70  send(char const *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const noexcept
71  { return l4_vcon_send_u(cap(), buf, size, utcb); }
72
73  /**
74   * Write data to `this` virtual console.
75   *
76   * \param buf   Pointer to the data buffer.
77   * \param size  Size of the data buffer in bytes.
78   * \param utcb  UTCB pointer of the calling thread.
79   *
80   * \retval <0   Error.
81   * \retval >=0  Number of bytes written to the virtual console.
82   */
83  long
84  write(char const *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const noexcept
85  { return l4_vcon_write_u(cap(), buf, size, utcb); }
86
87  /**
88   * Read data from `this` virtual console.
89   *
90   * \param[out] buf   Pointer to data buffer.
91   * \param      size  Size of the data buffer in bytes.
92   * \param      utcb  UTCB pointer of the calling thread.
93   *
94   * \retval <0      Error code.
95   * \retval >size   More bytes to read, `size` bytes are in the buffer `buf`.
96   * \retval <=size  Number of bytes read.
97   *
98   * \note Size must not exceed #L4_VCON_READ_SIZE.
99   */
100  int
101  read(char *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const noexcept
102  { return l4_vcon_read_u(cap(), buf, size, utcb); }
103
104  /**
105   * Read data from `this` virtual console which also returns flags.
106   *
107   * \param[out] buf   Pointer to data buffer.
108   * \param      size  Size of the data buffer in bytes.
109   * \param      utcb  UTCB pointer of the calling thread.
110   *
111   * \retval <0      Error code.
112   * \retval >size   More bytes to read, `size` bytes are in the buffer `buf`.
113   * \retval <=size  Number of bytes read.
114   *
115   * If this function returns a positive value the caller can check the
116   * #L4_VCON_READ_STAT_BREAK flag bit for a break condition. The bytes read
117   * can be obtained by masking the return value with #L4_VCON_READ_SIZE_MASK.
118   *
119   * If a break condition is signaled, it is always the first event in the
120   * transmitted content, i.e. all characters supplied by this read call follow
121   * the break condition.
122   *
123   * \note Size must not exceed #L4_VCON_READ_SIZE.
124   */
125  int
126  read_with_flags(char *buf, unsigned size, l4_utcb_t *utcb = l4_utcb()) const noexcept
127  { return l4_vcon_read_with_flags_u(cap(), buf, size, utcb); }
128
129  /**
130   * Set the attributes of `this` virtual console.
131   *
132   * \param attr  Attribute structure with the attributes for the virtual
133   *              console.
134   * \param utcb  UTCB pointer of the calling thread.
135   *
136   * \return Syscall return tag.
137   */
138  l4_msgtag_t
139  set_attr(l4_vcon_attr_t const *attr, l4_utcb_t *utcb = l4_utcb()) const noexcept
140  { return l4_vcon_set_attr_u(cap(), attr, utcb); }
141
142  /**
143   * Get attributes of `this` virtual console.
144   *
145   * \param[out] attr  Attribute structure. Contains the attributes after a
146   *                   successful call of this function.
147   * \param      utcb  UTCB pointer of the calling thread.
148   *
149   * \return Syscall return tag.
150   */
151  l4_msgtag_t
152  get_attr(l4_vcon_attr_t *attr, l4_utcb_t *utcb = l4_utcb()) const noexcept
153  { return l4_vcon_get_attr_u(cap(), attr, utcb); }
154
155  typedef L4::Typeid::Raw_ipc<Vcon> Rpcs;
156};
157
158}
159