L4Re Operating System Framework
Interface and Usage Documentation
Loading...
Searching...
No Matches
Virtual Console

C Virtual console interface for simple character based input and output, see L4::Vcon for the C++ interface. More...

+ Collaboration diagram for Virtual Console:

Data Structures

struct  l4_vcon_attr_t
 Vcon attribute structure. More...
 

Typedefs

typedef struct l4_vcon_attr_t l4_vcon_attr_t
 Vcon attribute structure.
 

Enumerations

enum  L4_vcon_size_consts { L4_VCON_WRITE_SIZE = (L4_UTCB_GENERIC_DATA_SIZE - 2) * sizeof(l4_umword_t) , L4_VCON_READ_SIZE = (L4_UTCB_GENERIC_DATA_SIZE - 1) * sizeof(l4_umword_t) }
 Size constants. More...
 
enum  L4_vcon_i_flags { L4_VCON_INLCR = 000100 , L4_VCON_IGNCR = 000200 , L4_VCON_ICRNL = 000400 }
 Input flags. More...
 
enum  L4_vcon_o_flags { L4_VCON_ONLCR = 000004 , L4_VCON_OCRNL = 000010 , L4_VCON_ONLRET = 000040 }
 Output flags. More...
 
enum  L4_vcon_l_flags { L4_VCON_ICANON = 000002 , L4_VCON_ECHO = 000010 }
 Local flags. More...
 

Functions

l4_msgtag_t l4_vcon_send (l4_cap_idx_t vcon, char const *buf, unsigned size) L4_NOTHROW
 Send data to virtual console.
 
l4_msgtag_t l4_vcon_send_u (l4_cap_idx_t vcon, char const *buf, unsigned size, l4_utcb_t *utcb) L4_NOTHROW
 Send data to this virtual console.
 
long l4_vcon_write (l4_cap_idx_t vcon, char const *buf, unsigned size) L4_NOTHROW
 Write data to virtual console.
 
long l4_vcon_write_u (l4_cap_idx_t vcon, char const *buf, unsigned size, l4_utcb_t *utcb) L4_NOTHROW
 Write data to this virtual console.
 
int l4_vcon_read (l4_cap_idx_t vcon, char *buf, unsigned size) L4_NOTHROW
 Read data from virtual console.
 
int l4_vcon_read_u (l4_cap_idx_t vcon, char *buf, unsigned size, l4_utcb_t *utcb) L4_NOTHROW
 Read data from this virtual console.
 
int l4_vcon_read_with_flags (l4_cap_idx_t vcon, char *buf, unsigned size) L4_NOTHROW
 Read data from virtual console, extended version including flags.
 
l4_msgtag_t l4_vcon_set_attr (l4_cap_idx_t vcon, l4_vcon_attr_t const *attr) L4_NOTHROW
 Set attributes of a Vcon.
 
l4_msgtag_t l4_vcon_set_attr_u (l4_cap_idx_t vcon, l4_vcon_attr_t const *attr, l4_utcb_t *utcb) L4_NOTHROW
 Set the attributes of this virtual console.
 
l4_msgtag_t l4_vcon_get_attr (l4_cap_idx_t vcon, l4_vcon_attr_t *attr) L4_NOTHROW
 Get attributes of a Vcon.
 
l4_msgtag_t l4_vcon_get_attr_u (l4_cap_idx_t vcon, l4_vcon_attr_t *attr, l4_utcb_t *utcb) L4_NOTHROW
 Get attributes of this virtual console.
 
void l4_vcon_set_attr_raw (l4_vcon_attr_t *attr) L4_NOTHROW
 Set terminal attributes to disable all special processing.
 

Detailed Description

C Virtual console interface for simple character based input and output, see L4::Vcon for the C++ interface.

The interrupt for read events is provided by the virtual key interrupt which, in contrast to hardware IRQs, implements a limited functionality:

A server implementing the virtual console protocol has a queue for input events. When the first input event is added to the empty queue, the virtual key interrupt is triggered. Further events are added to the queue without generating further interrupts. The queue is emptied when a client reads all queued input events.

Include File
#include <l4/sys/vcon.h>
Virtual console interface.

See L4::Vcon for the C++ interface.

Typedef Documentation

◆ l4_vcon_attr_t

Vcon attribute structure.

The flags members can be a combination of their respective enums.

See also
L4_vcon_i_flags
L4_vcon_o_flags
L4_vcon_l_flags

Enumeration Type Documentation

◆ L4_vcon_i_flags

Input flags.

Enumerator
L4_VCON_INLCR 

Translate NL to CR.

L4_VCON_IGNCR 

Ignore CR.

L4_VCON_ICRNL 

Translate CR to NL if L4_VCON_IGNCR is not set.

Definition at line 217 of file vcon.h.

◆ L4_vcon_l_flags

Local flags.

Enumerator
L4_VCON_ICANON 

Canonical mode.

L4_VCON_ECHO 

Echo input.

Definition at line 239 of file vcon.h.

◆ L4_vcon_o_flags

Output flags.

Enumerator
L4_VCON_ONLCR 

Translate NL to CR-NL.

L4_VCON_OCRNL 

Translate CR to NL.

L4_VCON_ONLRET 

Do not output CR.

Definition at line 228 of file vcon.h.

◆ L4_vcon_size_consts

Size constants.

Enumerator
L4_VCON_WRITE_SIZE 

Maximum size that can be written with one l4_vcon_write call.

L4_VCON_READ_SIZE 

Maximum size that can be read with one l4_vcon_read* call.

Definition at line 106 of file vcon.h.

Function Documentation

◆ l4_vcon_get_attr()

l4_msgtag_t l4_vcon_get_attr ( l4_cap_idx_t  vcon,
l4_vcon_attr_t attr 
)
inline

Get attributes of a Vcon.

Parameters
vconVcon object.
[out]attrAttribute structure.
Returns
Syscall return tag
Examples
examples/sys/isr/main.c.

Definition at line 444 of file vcon.h.

References l4_utcb(), and l4_vcon_get_attr_u().

+ Here is the call graph for this function:

◆ l4_vcon_get_attr_u()

l4_msgtag_t l4_vcon_get_attr_u ( l4_cap_idx_t  vcon,
l4_vcon_attr_t attr,
l4_utcb_t utcb 
)
inline

Get attributes of this virtual console.

Parameters
vconCapability index of the vcon object.
[out]attrAttribute structure. Contains the attributes after a successful call of this function.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag.

Definition at line 426 of file vcon.h.

References l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_PROTO_LOG, L4_VCON_GET_ATTR_OP, and l4_msg_regs_t::mr.

Referenced by L4::Vcon::get_attr(), and l4_vcon_get_attr().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_vcon_read()

int l4_vcon_read ( l4_cap_idx_t  vcon,
char *  buf,
unsigned  size 
)
inline

Read data from virtual console.

Parameters
vconVcon object.
[out]bufPointer to data buffer.
sizeSize of buffer in bytes.
Return values
-L4_EPERMThe Vcon instance requires the L4_CAP_FPAGE_W right on the vcon capability and this right is not present.
>sizeMore bytes to read, size bytes are in the buffer buf.
<=sizeNumber of bytes read.
Note
Size must not exceed L4_VCON_READ_SIZE.
Examples
examples/sys/isr/main.c.

Definition at line 400 of file vcon.h.

References l4_utcb(), and l4_vcon_read_u().

+ Here is the call graph for this function:

◆ l4_vcon_read_u()

int l4_vcon_read_u ( l4_cap_idx_t  vcon,
char *  buf,
unsigned  size,
l4_utcb_t utcb 
)
inline

Read data from this virtual console.

Parameters
vconCapability index of the vcon object.
[out]bufPointer to data buffer.
sizeSize of the data buffer in bytes.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Return values
-L4_EPERMThe Vcon instance requires the L4_CAP_FPAGE_W right on the capability used to invoke this operation and this right is not present.
>sizeMore bytes to read, size bytes are in the buffer buf.
<=sizeNumber of bytes read.
Note
Size must not exceed L4_VCON_READ_SIZE.

Definition at line 390 of file vcon.h.

References L4_VCON_READ_SIZE_MASK.

Referenced by l4_vcon_read(), and L4::Vcon::read().

+ Here is the caller graph for this function:

◆ l4_vcon_read_with_flags()

int l4_vcon_read_with_flags ( l4_cap_idx_t  vcon,
char *  buf,
unsigned  size 
)
inline

Read data from virtual console, extended version including flags.

Parameters
vconVcon object.
[out]bufPointer to data buffer.
sizeSize of buffer in bytes.

If this function returns a positive value the caller can check the L4_VCON_READ_STAT_BREAK flag bit for a break condition. The bytes read can be obtained by masking the return value with L4_VCON_READ_SIZE_MASK.

If a break condition is signaled, it is always the first event in the transmitted content, i.e. all characters supplied by this read call follow the break condition.

buf might be a NULL, in this case the input data will be dropped.

Note
Size must not exceed L4_VCON_READ_SIZE.
Return values
-L4_EPERMThe Vcon instance requires the L4_CAP_FPAGE_W right on the vcon capability and this right is not present.
>sizeMore bytes to read, size bytes are in the buffer buf.
<=sizeNumber of bytes read.

Definition at line 384 of file vcon.h.

References l4_utcb().

+ Here is the call graph for this function:

◆ l4_vcon_send()

l4_msgtag_t l4_vcon_send ( l4_cap_idx_t  vcon,
char const *  buf,
unsigned  size 
)
inline

Send data to virtual console.

Parameters
vconVcon object.
bufPointer to data buffer.
sizeSize of buffer in bytes.
Returns
Syscall return tag
Note
Size must not exceed L4_VCON_WRITE_SIZE, a proper value of the size parameter is NOT checked. Also, this function is a send only operation, this means there is no return value except for a failed send operation. Use l4_ipc_error() to check for send errors, and do not use l4_error().
Examples
examples/sys/utcb-ipc/main.c.

Definition at line 324 of file vcon.h.

References l4_utcb(), and l4_vcon_send_u().

+ Here is the call graph for this function:

◆ l4_vcon_send_u()

l4_msgtag_t l4_vcon_send_u ( l4_cap_idx_t  vcon,
char const *  buf,
unsigned  size,
l4_utcb_t utcb 
)
inline

Send data to this virtual console.

Parameters
vconCapability index of the Vcon object.
bufPointer to the data buffer.
sizeSize of the data buffer in bytes.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag
Note
Size must not exceed L4_VCON_WRITE_SIZE, a proper value of the size parameter is NOT checked. Also, this function is a send only operation, this means there is no return value except for a failed send operation. Use l4_ipc_error() to check for send errors, do not use l4_error(), as l4_error() will always return an error.

Definition at line 311 of file vcon.h.

References l4_bytes_to_mwords(), L4_IPC_NEVER, l4_ipc_send(), l4_msgtag(), L4_MSGTAG_SCHEDULE, L4_PROTO_LOG, L4_VCON_WRITE_OP, and l4_msg_regs_t::mr.

Referenced by l4_vcon_send(), l4_vcon_write_u(), and L4::Vcon::send().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_vcon_set_attr()

l4_msgtag_t l4_vcon_set_attr ( l4_cap_idx_t  vcon,
l4_vcon_attr_t const *  attr 
)
inline

Set attributes of a Vcon.

Parameters
vconVcon object.
attrAttribute structure.
Returns
Syscall return tag
Examples
examples/sys/isr/main.c.

Definition at line 420 of file vcon.h.

References l4_utcb(), and l4_vcon_set_attr_u().

+ Here is the call graph for this function:

◆ l4_vcon_set_attr_raw()

void l4_vcon_set_attr_raw ( l4_vcon_attr_t attr)
inline

Set terminal attributes to disable all special processing.

Removes all flags that would mangle the read or written characters. Also disables echoing and any special processing of characters.

Parameters
[in,out]attrAttribute structure to update.

Definition at line 450 of file vcon.h.

Referenced by l4_vcon_attr_t::set_raw().

+ Here is the caller graph for this function:

◆ l4_vcon_set_attr_u()

l4_msgtag_t l4_vcon_set_attr_u ( l4_cap_idx_t  vcon,
l4_vcon_attr_t const *  attr,
l4_utcb_t utcb 
)
inline

Set the attributes of this virtual console.

Parameters
vconCapability index of the vcon object.
attrAttribute structure with the attributes for the virtual console.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag.

Definition at line 406 of file vcon.h.

References l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_PROTO_LOG, L4_VCON_SET_ATTR_OP, and l4_msg_regs_t::mr.

Referenced by l4_vcon_set_attr(), and L4::Vcon::set_attr().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_vcon_write()

long l4_vcon_write ( l4_cap_idx_t  vcon,
char const *  buf,
unsigned  size 
)
inline

Write data to virtual console.

Parameters
vconVcon object.
bufPointer to data buffer.
sizeSize of buffer in bytes.
Return values
<0Error.
>=0Number of bytes written to the virtual console

Definition at line 345 of file vcon.h.

References l4_utcb(), and l4_vcon_write_u().

+ Here is the call graph for this function:

◆ l4_vcon_write_u()

long l4_vcon_write_u ( l4_cap_idx_t  vcon,
char const *  buf,
unsigned  size,
l4_utcb_t utcb 
)
inline

Write data to this virtual console.

Parameters
vconCapability index of the vcon object.
bufPointer to the data buffer.
sizeSize of the data buffer in bytes.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Return values
<0Error.
>=0Number of bytes written to the virtual console.

Definition at line 330 of file vcon.h.

References l4_error(), l4_msgtag_has_error(), l4_vcon_send_u(), and L4_VCON_WRITE_SIZE.

Referenced by l4_vcon_write(), and L4::Vcon::write().

+ Here is the call graph for this function:
+ Here is the caller graph for this function: