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:

Only IRQ line 0 is supported, no MSI vectors.
The IRQ is edge-triggered and the IRQ mode cannot be changed.
As the IRQ is edge-triggered, it does not have to be explicitly unmasked.

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>

vcon.h
Virtual console interface.

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

Typedef Documentation

◆ l4_vcon_attr_t

typedef struct l4_vcon_attr_t 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

enum 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

enum 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

enum 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

enum 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

	vcon	Vcon object.
[out]	attr	Attribute 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

	vcon	Capability index of the vcon object.
[out]	attr	Attribute structure. Contains the attributes after a successful call of this function.
	utcb	UTCB 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

	vcon	Vcon object.
[out]	buf	Pointer to data buffer.
	size	Size of buffer in bytes.

Return values

-L4_EPERM	The Vcon instance requires the L4_CAP_FPAGE_W right on the `vcon` capability and this right is not present.
>size	More bytes to read, `size` bytes are in the buffer `buf`.
<=size	Number 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

	vcon	Capability index of the vcon object.
[out]	buf	Pointer to data buffer.
	size	Size of the data buffer in bytes.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Return values

-L4_EPERM	The Vcon instance requires the L4_CAP_FPAGE_W right on the capability used to invoke this operation and this right is not present.
>size	More bytes to read, `size` bytes are in the buffer `buf`.
<=size	Number 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

	vcon	Vcon object.
[out]	buf	Pointer to data buffer.
	size	Size 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_EPERM	The Vcon instance requires the L4_CAP_FPAGE_W right on the `vcon` capability and this right is not present.
>size	More bytes to read, `size` bytes are in the buffer `buf`.
<=size	Number 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

vcon	Vcon object.
buf	Pointer to data buffer.
size	Size 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

vcon	Capability index of the Vcon object.
buf	Pointer to the data buffer.
size	Size of the data buffer in bytes.
utcb	UTCB 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

vcon	Vcon object.
attr	Attribute 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] attr Attribute 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

vcon	Capability index of the vcon object.
attr	Attribute structure with the attributes for the virtual console.
utcb	UTCB 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

vcon	Vcon object.
buf	Pointer to data buffer.
size	Size of buffer in bytes.

Return values

<0	Error.
>=0	Number 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

vcon	Capability index of the vcon object.
buf	Pointer to the data buffer.
size	Size of the data buffer in bytes.
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Return values

<0	Error.
>=0	Number 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:

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ l4_vcon_attr_t

Enumeration Type Documentation

◆ L4_vcon_i_flags

◆ L4_vcon_l_flags

◆ L4_vcon_o_flags

◆ L4_vcon_size_consts

Function Documentation

◆ l4_vcon_get_attr()

◆ l4_vcon_get_attr_u()

◆ l4_vcon_read()

◆ l4_vcon_read_u()

◆ l4_vcon_read_with_flags()

◆ l4_vcon_send()

◆ l4_vcon_send_u()

◆ l4_vcon_set_attr()

◆ l4_vcon_set_attr_raw()

◆ l4_vcon_set_attr_u()

◆ l4_vcon_write()

◆ l4_vcon_write_u()