Loading...
Searching...
No Matches
Virtual Console
Base API » Kernel Objects

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 208 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 230 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 219 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 95 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 435 of file vcon.h.

References L4_NOTHROW, 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 417 of file vcon.h.

References l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_NOTHROW, 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 | Insufficient permissions; see precondition.
  >size | More bytes to read, size bytes are in the buffer buf.
  <=size | Number of bytes read.

Precondition
  The capability vcon must have the permission L4_CAP_FPAGE_W.

Note
  Size must not exceed L4_VCON_READ_SIZE.

Examples
  examples/sys/isr/main.c.

Definition at line 391 of file vcon.h.

References L4_NOTHROW, 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 | Insufficient permissions; see precondition.
  >size | More bytes to read, size bytes are in the buffer buf.
  <=size | Number of bytes read.

Precondition
  The invoked Vcon capability must have the permission L4_CAP_FPAGE_W.

Note
  Size must not exceed L4_VCON_READ_SIZE.

Definition at line 381 of file vcon.h.

References L4_NOTHROW, and 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 | Insufficient permissions; see precondition.
  >size | More bytes to read, size bytes are in the buffer buf.
  <=size | Number of bytes read.

Precondition
  The capability vcon must have the permission L4_CAP_FPAGE_W.

Definition at line 375 of file vcon.h.

References L4_NOTHROW, and 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 315 of file vcon.h.

References L4_NOTHROW, 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 302 of file vcon.h.

References l4_bytes_to_mwords(), L4_IPC_NEVER, l4_ipc_send(), l4_msgtag(), L4_MSGTAG_SCHEDULE, L4_NOTHROW, 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 411 of file vcon.h.

References L4_NOTHROW, 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 441 of file vcon.h.

References L4_NOTHROW.

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 397 of file vcon.h.

References l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_NOTHROW, 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 336 of file vcon.h.

References L4_NOTHROW, 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 321 of file vcon.h.

References l4_error(), l4_msgtag_has_error(), L4_NOTHROW, 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: