Kernel runtime API

Kernel core runtime shell with basic commands and stdio included. More...

Data Structures
struct	command_s
	Command descriptor structure. More...
struct	console_key_s
	Console key event data. More...
union	evt_data_u
	Event payload container. More...
struct	service_s
	Service descriptor structure. More...

Macros
#define	_SHELL_COMMAND(name, callback)
	Declares and registers a shell command.
#define	SIG_SETMASK   0
	Replace current signal mask.
#define	SIG_BLOCK   1
	Add signals to current mask (block).
#define	SIG_UNBLOCK   2
	Remove signals from current mask (unblock).
#define	SIGHUP   1
	Signal numeric identifiers.
#define	_SERVICE(name, service_main)
	Declares and registers a system service.
#define	MAJOR   (1)
	Kernel version major number.
#define	MINOR   (0)
	Kernel version minor number.
#define	PATCH   (0)
	Kernel patch number.
#define	REVISION   ("alpha")
	Kernel revision label.

Typedefs
typedef struct command_s	command_t
	Command descriptor type alias.
typedef __sigset_t	sigset_t
	Signal set type.
typedef union evt_data_u	evt_data_t
	Event payload alias.
typedef struct console_key_s	console_key_t
	Console key event payload alias.
typedef void(*	evt_subscriber_t) (evt_data_t const *evtData)
	Event subscriber callback prototype.
typedef struct service_s	service_t
	Service descriptor alias.

Enumerations
enum	user_events_e { EVT_USERCON_KEY = 50 , EVT_SYS_USER_EVENTS }
	User-level event identifiers. More...
enum	kernel_events_e { EVT_ONESHOT_TICK , EVT_PERIODIC_TICK , EVT_KERNEL_DTC , EVT_KERNEL_EVENTS }
	Kernel-level event identifiers. More...

Functions
void	_kernel_pipeline (void)
	Executes the kernel event pipeline.
void	_kernel_pubEvt (uint8_t id, evt_data_t *data)
	Publishes an event to the kernel event system.
void	_kernel_subEvt (uint8_t id, evt_subscriber_t subscriber)
	Registers a subscriber callback for a specific event.
void	_kernel_exec_f (int(*exec_func)(const int argc, const char **argv), const int argc, const char **argv)
	Executes a function in kernel context with argument forwarding.
void const *	_kernel_service (void const *svc, char const **svc_name)
	Retrieves next kernel service descriptor.
int	_kernel_raise (int sgl)
	Sends a signal to the current execution context.
int	_kernel_sigpending (sigset_t *set)
	Retrieves pending signals.
int	_kernel_sigwait (const sigset_t *set, int *sgl)
	Waits synchronously for a signal.
int	_kernel_sigprocmask (int what, const sigset_t *set, sigset_t *oldset)
	Examines or modifies signal mask.
int	_kernel_sigemptyset (sigset_t *set)
	Initializes a signal set to empty.
int	_kernel_sigaddset (sigset_t *set, const int sgl)
	Adds a signal to a set.
bool	_kernel_sigismember (sigset_t *set, const int sgl)
	Tests whether a signal is a member of a set.
void	_kernel_stdio (void)
	Initializes kernel standard I/O subsystem.
void	_kernel_outLn (void)
	Outputs a newline sequence.
void	_kernel_outTab (void)
	Outputs a horizontal tab.
void	_kernel_outChar (const char code)
	Outputs a single character.
void	_kernel_outString (const char *str)
	Outputs a null-terminated string.
void	_kernel_outStringFormat (const char *fmt,...)
	Outputs a formatted string.
void	_kernel_stringFormat (char *s, char const *fmt,...)
	Formats a string into a buffer.
void	_kernel_vstringFormat (char *s, char const *fmt, va_list args)
	Formats a string using a va_list argument.
void	_kernel_getKey (console_key_t *key)
	Retrieves a key event (blocking).
bool	_kernel_tryGetKey (console_key_t *key)
	Attempts to retrieve a key event (non-blocking).
size_t	text_monitor (char const *s)
	Outputs a null-terminated text string to the console.
size_t	hex_monitor (void const *mem, const size_t s)
	Outputs a memory region as hexadecimal values to the console.
void	_shell_start (void)
	Starts the system shell.

Detailed Description

Kernel core runtime shell with basic commands and stdio included.

Macro Definition Documentation

_SERVICE

#define _SERVICE	(		name,
			service_main
	)

Value:

    __attribute__((used, section(".service_table"))) \
    static const service_t name = { #name, service_main }

Declares and registers a system service.

Parameters

name	Identifier of the service object. The same identifier string is used as the service name.
service_main	Pointer to the service entry function.

Defines a static constant service_t instance and places it into the ".service_table" linker section.

The linker aggregates all registered services into a contiguous table that can be iterated during system services runtime.

The object is marked with the "used" attribute to prevent removal by linker garbage collection.

Warning

Requires linker script support defining the ".service_table" section and its boundary symbols.

Example

static void logger_service(void)
{
    // Service implementation
}
 
_SERVICE(logger, logger_service);

Linker Requirements

The linker script must expose start/end symbols for ".service_table" to allow iteration.

_SHELL_COMMAND

#define _SHELL_COMMAND	(		name,
			callback
	)

Value:

    __attribute__((used, section(".cmd_table"))) \
    static const command_t name = { #name, callback }

Declares and registers a shell command.

Defines a static constant command_t instance and places it in the ".cmd_table" linker section.

The linker aggregates all such entries into a contiguous table used by the shell subsystem for command lookup.

Parameters

name	Identifier of the command object. The same identifier string is used as the command name.
callback	Pointer to the command handler function.

Note

• The command object is marked as used to prevent removal by linker garbage collection.
• Requires linker script support for ".cmd_table" section.

Warning

The handler function must match the required prototype: int handler(const int argc, const char **argv);

Linker Requirements

The linker script must define start and end symbols for the ".cmd_table" section to enable iteration.

Example

static int cmd_hello(const int argc, const char **argv)
{
    (void)argc;
    (void)argv;
    return 0;
}
 
_SHELL_COMMAND(hello, cmd_hello);

MAJOR

#define MAJOR   (1)

Kernel version major number.

Indicates the major version of the kernel. Incremented for incompatible API changes or major feature updates.

MINOR

#define MINOR   (0)

Kernel version minor number.

Indicates the minor version of the kernel. Incremented for backward-compatible functionality additions.

PATCH

#define PATCH   (0)

Kernel patch number.

Indicates the patch or bugfix level. Incremented for backward-compatible bug fixes or minor improvements.

REVISION

#define REVISION   ("alpha")

Kernel revision label.

Provides an optional string indicating the release stage (e.g., "alpha", "beta", "rc1", "stable").

Note

Useful for pre-release or development builds.

SIG_BLOCK

#define SIG_BLOCK   1

Add signals to current mask (block).

Used with _kernel_sigprocmask() to block specified signals.

SIG_SETMASK

#define SIG_SETMASK   0

Replace current signal mask.

Used with _kernel_sigprocmask() to set the calling context's signal mask to the provided set.

SIG_UNBLOCK

#define SIG_UNBLOCK   2

Remove signals from current mask (unblock).

Used with _kernel_sigprocmask() to unblock specified signals.

SIGHUP

#define SIGHUP   1

Signal numeric identifiers.

Defines supported kernel signal identifiers. Numeric values are implementation-defined but fixed for ABI compatibility. Hangup.

Typedef Documentation

evt_subscriber_t

typedef void(* evt_subscriber_t) (evt_data_t const *evtData)

Event subscriber callback prototype.

Parameters

[in]

evtData

Pointer to event data payload.

Function type for event subscribers registered with the kernel event dispatcher.

The meaning of evtData depends on the event identifier associated with the callback invocation.

Precondition

• evtData can be NULL. In such a case an event has no payload
• Subscriber can block unless mandatory not to block by the event consumer design.

Note

Callback will not execute in interrupt context a kernel makes sure of that Implementation shall be reentrant and time-bounded.

sigset_t

typedef __sigset_t sigset_t

Signal set type.

Represents a bitmask of signals. Each bit corresponds to one signal number.

Enumeration Type Documentation

kernel_events_e

enum kernel_events_e

Kernel-level event identifiers.

Defines internal kernel event types generated by the kernel space services.

Note

These events are typically dispatched by the kernel event manager and must not overlap with user events.

Enumerator
EVT_ONESHOT_TICK	One-shot timer tick event.
EVT_PERIODIC_TICK	Periodic timer tick event.
EVT_KERNEL_DTC	Kernel data traction code arrival event.
EVT_KERNEL_EVENTS	Upper boundary marker for kernel events.

user_events_e

enum user_events_e

User-level event identifiers.

Defines event codes reserved for user-space

Note

Event values starting at 50 are reserved for user events to avoid collision with kernel-reserved event identifiers.

Enumerator
EVT_USERCON_KEY	Console key input event.
EVT_SYS_USER_EVENTS	Upper boundary marker for user events.

Function Documentation

_kernel_exec_f()

void _kernel_exec_f	(	int(*)(const int argc, const char **argv)	exec_func,
		const int	argc,
		const char **	argv
	)

Executes a function in kernel context with argument forwarding.

Parameters

[in]	exec_func	Pointer to the function to execute. Must match the signature int func(int argc, const char **argv).
[in]	argc	Number of arguments to pass to the function.
[in]	argv	Array of null-terminated argument strings.

Precondition

• exec_func must not be NULL.
• argv must not be NULL if argc > 0.
  

This function provides a safe wrapper to execute a user-supplied function within kernel or privileged context, forwarding the specified arguments.

The provided function is expected to:

• Return an integer status code.
• Handle the arguments correctly.

Postcondition

• The exec_func is invoked with the specified arguments.

Side Effects:

• Executes arbitrary code in kernel context; may modify global or hardware state depending on exec_func implementation.

Warning

• exec_func must be reentrant if called from concurrent contexts.
• Misbehaving functions may compromise kernel stability.

_kernel_getKey()

void _kernel_getKey

(

console_key_t *

key

)

Retrieves a key event (blocking).

Parameters

[out]

key

Structure receiving key information.

Precondition

key must not be NULL.

Blocks until a console key event is available. Populates the provided console_key_t structure.

Warning

May block calling context indefinitely.

_kernel_outChar()

void _kernel_outChar

(

const char

code

)

Outputs a single character.

Parameters

[in]

code

Character to output.

Side Effects:

Writes to console or debug output device.

_kernel_outLn()

void _kernel_outLn

(

void

)

Outputs a newline sequence.

Advances output cursor to the next line.

_kernel_outString()

void _kernel_outString

(

const char *

str

)

Outputs a null-terminated string.

Parameters

[in]

str

String to output.

Precondition

str must not be NULL.

_kernel_outStringFormat()

void _kernel_outStringFormat	(	const char *	fmt,
			...
	)

Outputs a formatted string.

Parameters

[in]	fmt	Format string.
[in]	...	Variable arguments.

Precondition

fmt must not be NULL.

Formats the string according to implementation-defined formatting rules (printf-like) and writes it to output.

Warning

Supported format specifiers are implementation-defined.

_kernel_outTab()

void _kernel_outTab

(

void

)

Outputs a horizontal tab.

Advances output cursor to the next tab stop.

_kernel_pipeline()

void _kernel_pipeline

(

void

)

Executes the kernel event pipeline.

Processes all pending events in the kernel event queue, dispatching them to registered subscribers.

This function is typically called in the main kernel loop or from a dedicated event task.

Side Effects:

• Invokes subscriber callbacks for pending events.
• May modify internal kernel event queue state.

Warning

• Subscribers must be reentrant if pipeline is executed from multiple contexts.
• Long-running callbacks may delay event processing.

_kernel_pubEvt()

void _kernel_pubEvt	(	uint8_t	id,
		evt_data_t *	data
	)

Publishes an event to the kernel event system.

Parameters

[in]	id	Event identifier (kernel or user event code).
[in]	data	Pointer to event data payload.

Precondition

• data may be NULL if the event has no payload.

Adds the event to the kernel event queue for later processing by _kernel_pipeline().

Side Effects:

• Updates internal kernel event queue.
• May trigger deferred execution of subscriber callbacks.

Note

• Publisher might not ensure that evt_data_t remains valid until the event is processed because a kernel makes a deep copy of the payload at the event enque stage

_kernel_raise()

int _kernel_raise

(

int

sgl

)

Sends a signal to the current execution context.

Parameters

[in]

sgl

Signal number.

Returns

0 on success, negative value on error.

Precondition

• sgl must be a valid signal number (< _NSIG).

_kernel_service()

void const * _kernel_service	(	void const *	svc,
		char const **	svc_name
	)

Retrieves next kernel service descriptor.

Parameters

[in]	svc	Opaque pointer used for service table iteration. May be NULL to retrieve the first service. Then passing a service descriptor shall return a next one or NULL
[out]	svc_name	Pointer receiving the service name.

Returns

Pointer to a service descriptor or NULL if no further services are available or lookup fails.

Precondition

• svc_name must be a valid writable pointer.

Provides access to statically registered kernel services, typically stored in a dedicated linker section.

This function may be used to:

• Iterate through all registered services
• Retrieve metadata associated with a service

The iteration mechanism is implementation-defined. Commonly, callers pass NULL to obtain the first service and then pass the previously returned pointer to retrieve the next one.

Postcondition

• If a non-NULL value is returned *svc_name points to a valid null-terminated string.

Side Effects:

• None expected (read-only access to service table).

Warning

• Returned pointer refers to statically allocated memory.
• Must not be modified by the caller.

_kernel_sigaddset()

int _kernel_sigaddset	(	sigset_t *	set,
		const int	sgl
	)

Adds a signal to a set.

Parameters

[in,out]	set	Signal set.
[in]	sgl	Signal number to add.

Returns

0 on success, negative value on error.

_kernel_sigemptyset()

int _kernel_sigemptyset

(

sigset_t *

set

)

Initializes a signal set to empty.

Parameters

[out]

set

Signal set to initialize.

Returns

0 on success, negative value on error.

_kernel_sigismember()

bool _kernel_sigismember	(	sigset_t *	set,
		const int	sgl
	)

Tests whether a signal is a member of a set.

Parameters

[in]	set	Signal set.
[in]	sgl	Signal number.

Return values

true	Signal is a member.
false	Signal is not a member.

_kernel_sigpending()

int _kernel_sigpending

(

sigset_t *

set

)

Retrieves pending signals.

Parameters

[out]

set

Signal set receiving pending signals.

Returns

0 on success, negative value on error.

Precondition

• set must not be NULL.

_kernel_sigprocmask()

int _kernel_sigprocmask	(	int	what,
		const sigset_t *	set,
		sigset_t *	oldset
	)

Examines or modifies signal mask.

Parameters

[in]	what	Operation type (SIG_SETMASK, SIG_BLOCK, SIG_UNBLOCK).
[in]	set	Signal set to apply.
[out]	oldset	Previous signal mask (may be NULL to retrieve old mask).

Returns

0 on success, negative value on error.

_kernel_sigwait()

int _kernel_sigwait	(	const sigset_t *	set,
		int *	sgl
	)

Waits synchronously for a signal.

Parameters

[in]	set	Signal set to wait for.
[out]	sgl	Pointer receiving delivered signal number.

Returns

0 on success, negative value on error.

Precondition

• set and sgl must not be NULL.

Warning

Might block calling context if no signals from the set are raised yet at the moment of calling this function

_kernel_stdio()

void _kernel_stdio

(

void

)

Initializes kernel standard I/O subsystem.

Prepares console output, input handling, and any required internal buffers. Must be invoked before using any _kernel_out* or input-related functions.

Postcondition

• Console output is operational.
• Keyboard/input subsystem is ready.

Side Effects:

• Initializes internal state.
• May register event subscribers.

_kernel_stringFormat()

void _kernel_stringFormat	(	char *	s,
		char const *	fmt,
			...
	)

Formats a string into a buffer.

Parameters

[out]	s	Output buffer.
[in]	fmt	Format string.
[in]	...	Variable arguments.

Precondition

• s must not be NULL.
• fmt must not be NULL.

Writes formatted output into the provided buffer. Buffer size management is implementation-defined.

_kernel_subEvt()

void _kernel_subEvt	(	uint8_t	id,
		evt_subscriber_t	subscriber
	)

Registers a subscriber callback for a specific event.

Parameters

[in]	id	Event identifier to subscribe to.
[in]	subscriber	Function pointer to callback invoked when the event is published.

Precondition

• subscriber must not be NULL.

Adds the subscriber to the internal subscription list for the specified event.

Side Effects:

• Modifies internal kernel subscription table.

Warning

• Subscriber execution can be blocking but should be time bounded.

_kernel_tryGetKey()

bool _kernel_tryGetKey

(

console_key_t *

key

)

Attempts to retrieve a key event (non-blocking).

Parameters

[out]

key

Structure receiving key information.

Return values

true	A key event was retrieved.
false	No key available.

Precondition

key must not be NULL.

Non-blocking version of _kernel_getKey().

_kernel_vstringFormat()

void _kernel_vstringFormat	(	char *	s,
		char const *	fmt,
		va_list	args
	)

Formats a string using a va_list argument.

Parameters

[out]	s	Output buffer.
[in]	fmt	Format string.
[in]	args	Argument list.

Precondition

• s must not be NULL.
• fmt must not be NULL.

Equivalent to _kernel_stringFormat() but accepts a prebuilt va_list. Intended for internal use or wrapper functions.

_shell_start()

void _shell_start

(

void

)

Starts the system shell.

Initializes and launches the shell or command-line interface subsystem. Typically, this function:

• Initializes shell state and buffers
• Displays the initial prompt
• Enters the main shell execution loop

Precondition

• Underlying console or I/O system must be initialized.
• Any required system services or drivers must be ready.

Postcondition

• Control enters the shell loop and remains there until the shell exits or the system shuts down.

Side Effects:

• May modify console state and internal shell buffers.
• Starts event handling for shell commands.

Warning

• This function typically does not return under normal operation.
• Must not be called before system initialization is complete.

hex_monitor()

size_t hex_monitor	(	void const *	mem,
		const size_t	s
	)

Outputs a memory region as hexadecimal values to the console.

Parameters

[in]	mem	Pointer to memory buffer.
[in]	s	Size of memory region in bytes.

Returns

Number of bytes processed and written in hexadecimal form.

Return values

0	No output generated (e.g., mem is NULL or s == 0).

Precondition

• mem must not be NULL.
• s > 0.

Reads the specified memory region and writes its contents to the console formatted as hexadecimal values.

Output formatting (grouping, spacing, line width) is implementation-defined.

Side Effects:

• Produces formatted diagnostic output.

Warning

Caller must ensure that the memory region is valid and accessible. Undefined behavior may occur if invalid memory is provided or there is no region access fault / exception handler exists

text_monitor()

size_t text_monitor

(

char const *

s

)

Outputs a null-terminated text string to the console.

Parameters

[in]

s

Pointer to a null-terminated character string.

Returns

Number of characters written to the console.

Return values

0	No characters written (e.g., s is NULL or empty string).

Precondition

• s must not be NULL.

Writes the provided string to the console output interface. The output device is implementation-defined (e.g., tty, VGA text mode, debug console).

The function stops writing upon encountering the null terminator.

Side Effects:

• Produces output on console interface (see console.h).