1.3. sys — System

System level functionality and definitions.

1.3.1. Example usage

This is a small example illustrating how to start an application by calling sys_start() and then print the system info and uptime on standard output.

int main()
{
    struct time_t uptime;

    sys_start();

    /* Print the system information. */
    std_printf(sys_get_info());

    /* Get the system uptime and print it. */
    sys_uptime(&uptime)
    std_printf(OSTR("System uptime: %lu s %lu ns"),
               uptime.seconds,
               uptime.nanoseconds);

    return (0);
}

1.3.2. Debug file system commands

Seven debug file system commands are available, all located in the directory kernel/sys/.

Command Description
info Print the system information.
config Print the build configuration (or at least part of it).
uptime Print the system uptime.
panic Call the panic function, stopping the system.
reboot Reboot the system.
backtrace Print a backtrace.
reset_cause Print the reset cause.

Example output from the shell:

$ kenel/sys/info
app:    shell-master built 2017-07-06 09:03 CEST by erik.
board:  Arduino Mega
mcu:    Atmel ATMega2560 AVR @ 16MHz, 8k sram, 256k flash
OK
$ kenel/sys/uptime
0.120 seconds
OK
$ kenel/sys/reset_cause
power_on
OK

Source code: src/kernel/sys.h, src/kernel/sys.c

Test code: tst/kernel/sys/main.c

Test coverage: src/kernel/sys.c


Defines

VERSION_STR
SYS_TICK_MAX

Typedefs

typedef uint32_t sys_tick_t
typedef uint32_t cpu_usage_t
typedef void (*sys_on_fatal_fn_t)(int error)

Enums

enum sys_reset_cause_t

System reset causes.

Values:

sys_reset_cause_unknown_t = 0
sys_reset_cause_power_on_t
sys_reset_cause_watchdog_timeout_t
sys_reset_cause_software_t
sys_reset_cause_external_t
sys_reset_cause_jtag_t
sys_reset_cause_max_t

Functions

static sys_tick_t t2st(const struct time_t *time_p)

Convertion from the time struct to system ticks.

static void st2t(sys_tick_t tick, struct time_t *time_p)

Convertion from system ticks to the time struct.

int sys_module_init(void)

Initialize the sys module. This function must be called before calling any other function in this module.

The module will only be initialized once even if this function is called multiple times.

Return
zero(0) or negative error code.

int sys_start(void)

Start the system and convert this context to the main thread.

This function initializes a bunch of enabled features in the simba platform. Many low level features (scheduling, timers, …) are always enabled, but higher level features are only enabled if configured.

This function must be the first function call in main().

Return
zero(0) or negative error code.

void sys_stop(int error)

Stop the system.

Return
Never returns.
Parameters
  • error: Error code.

void sys_panic(far_string_t fmt_p, ...)

System panic. Write given message, a backtrace and other port specific debug information to the console and then reboot the system.

This function may be called from interrupt context and with the system lock taken.

Return
Never returns.
Parameters
  • fmt_p: Format string.
  • ...: Variable arguments list.

void sys_reboot(void)

Reboot the system. Also known as a soft reset.

Return
Never returns.

int sys_backtrace(void **buf_p, size_t size)

Store the backtrace in given buffer.

Return
Backtrace depth.
Parameters
  • buf_p: Buffer to store the backtrace in.
  • size: Size of the buffer.

enum sys_reset_cause_t sys_reset_cause(void)

Get the system reset cause.

Return
The reset cause.

int sys_uptime(struct time_t *uptime_p)

Get the system uptime.

Return
zero(0) or negative error code.
Parameters
  • uptime_p: System uptime.

int sys_uptime_isr(struct time_t *uptime_p)

Get the system uptime from interrupt context or with the system lock taken.

Return
zero(0) or negative error code.
Parameters
  • uptime_p: System uptime.

void sys_set_on_fatal_callback(sys_on_fatal_fn_t callback)

Set the on-fatal-callback function to given callback.

The on-fatal-callback is called when a fatal error occurs. The default on-fatal-callback is sys_stop().

Return
void
Parameters
  • callback: Callback called when a fatal error occurs.

void sys_set_stdin(void *chan_p)

Set the standard input channel.

Return
void.
Parameters
  • chan_p: New standard input channel.

void *sys_get_stdin(void)

Get the standard input channel.

Return
Standard input channel.

void sys_set_stdout(void *chan_p)

Set the standard output channel.

Return
void.
Parameters
  • chan_p: New standard output channel.

void *sys_get_stdout(void)

Get the standard output channel.

Return
Standard output channel.

void sys_lock(void)

Take the system lock. Turns off interrupts.

Return
void.

void sys_unlock(void)

Release the system lock. Turn on interrupts.

Return
void.

void sys_lock_isr(void)

Take the system lock from isr. In many ports this has no effect.

Return
void.

void sys_unlock_isr(void)

Release the system lock from isr. In many ports this function has no effect.

Return
void.

far_string_t sys_get_info(void)

Get a pointer to the application information string.

The buffer contains various information about the application; for example the application name and the build date.

Return
The pointer to the application information string.

far_string_t sys_get_config(void)

Get a pointer to the application configuration string.

The buffer contains a string of all configuration variables and their values.

Return
The pointer to the application configuration string.

cpu_usage_t sys_interrupt_cpu_usage_get(void)

Get the current interrupt cpu usage counter.

Return
cpu usage, 0-100.

void sys_interrupt_cpu_usage_reset(void)

Reset the interrupt cpu usage counter.

far_string_t sys_reset_cause_as_string(enum sys_reset_cause_t reset_cause)

Get the reset cause as a far string.

Variables

struct sys_t sys
struct sys_t

Public Members

sys_on_fatal_fn_t on_fatal_callback
void *stdin_p
void *stdout_p