ICARUS OS — Lightweight Software Bus (pub/sub message router) More...

#include <stdint.h>
#include <stdbool.h>

Macros
#define	SB_MAX_ROUTES 32
	Maximum number of distinct message IDs that can have subscriptions.

#define	SB_MAX_SUBS_PER_MSG 4
	Maximum subscribers per message ID.

Typedefs
typedef uint16_t	sb_msg_id_t
	Software Bus message identifier.

Functions
void	sb_init (void)
	Initialize the software bus.

bool	sb_subscribe (sb_msg_id_t msg_id, uint8_t pipe_idx)
	Subscribe a pipe to a message ID.

bool	sb_unsubscribe (sb_msg_id_t msg_id, uint8_t pipe_idx)
	Remove a subscription.

uint8_t	sb_publish (sb_msg_id_t msg_id, const uint8_t *data, uint8_t len)
	Publish a message to all subscribers of `msg_id`.

uint8_t	sb_subscriber_count (sb_msg_id_t msg_id)
	Return the number of active subscriptions for a message ID.

uint8_t	sb_route_count (void)
	Return the total number of route entries in use.

void	__sb_init (void)
	Privileged implementation of sb_init().

bool	__sb_subscribe (sb_msg_id_t msg_id, uint8_t pipe_idx)
	Privileged implementation of sb_subscribe().

bool	__sb_unsubscribe (sb_msg_id_t msg_id, uint8_t pipe_idx)
	Privileged implementation of sb_unsubscribe().

uint8_t	__sb_publish (sb_msg_id_t msg_id, const uint8_t *data, uint8_t len)
	Privileged implementation of sb_publish().

uint8_t	__sb_subscriber_count (sb_msg_id_t msg_id)
	Privileged implementation of sb_subscriber_count().

uint8_t	__sb_route_count (void)
	Privileged implementation of sb_route_count().

Detailed Description

ICARUS OS — Lightweight Software Bus (pub/sub message router)

Version: 0.1.0

A thin publish/subscribe routing layer on top of the kernel pipe IPC. Tasks subscribe to message IDs; publishers push messages by ID and the bus copies the payload into every subscriber's pipe automatically.

Design constraints:

Zero dynamic allocation — all state is static in DTCM.
Each subscription binds a (msg_id, pipe_idx) pair.
A single msg_id can have up to SB_MAX_SUBS_PER_MSG subscribers.
Publishing never blocks the caller; if a subscriber's pipe is full the message is silently dropped for that subscriber (best-effort delivery).
Hot-path functions are placed in ITCM for zero wait-state execution.

Memory placement:

Route table: DTCM_DATA_PRIV (privileged-only, zero wait-state)
Functions: ITCM_FUNC (zero wait-state instruction fetch)

See also: icarus/pipe.h for the underlying byte-stream IPC; docs/do178c/design/SDD.md Section 4.6 — Software Bus

Author: Souham Biswas

Date: 2026

Copyright: Copyright 2025-2026 Souham Biswas https://github.com/ironhide23586/icarus-os-core Licensed under the Apache License, Version 2.0

Definition in file sb.h.

Typedef Documentation

◆ sb_msg_id_t

typedef uint16_t sb_msg_id_t

Software Bus message identifier.

Application code defines the actual constants (e.g. SB_MSG_FAULT_CMD = 0x0001). The bus treats them as opaque 16-bit values.

Definition at line 86 of file sb.h.

Function Documentation

◆ __sb_init()

void __sb_init ( void )

Privileged implementation of sb_init().

Zeroes the entire route table and resets the used counter.

Definition at line 93 of file sb.c.

References route_used, and routes.

Referenced by sb_init(), and SVC_Handler_C().

◆ __sb_publish()

uint8_t __sb_publish	(	sb_msg_id_t	msg_id,
		const uint8_t *	data,
		uint8_t	len
	)

Privileged implementation of sb_publish().

Parameters

[in]	msg_id	Message identifier.
[in]	data	Payload bytes.
[in]	len	Payload length.

Returns: Number of subscribers successfully enqueued to.

Iterates all subscribers for msg_id. For each pipe, checks capacity via pipe_can_enqueue() before writing. Pipes that are full are silently skipped (best-effort).

Definition at line 173 of file sb.c.

References __pipe_can_enqueue(), __pipe_write_bytes(), sb_route_t::count, find_route(), and sb_route_t::pipes.

Referenced by sb_publish(), and SVC_Handler_C().

◆ __sb_route_count()

uint8_t __sb_route_count ( void )

Privileged implementation of sb_route_count().

Returns: Number of distinct msg_ids with at least one subscriber.

Definition at line 209 of file sb.c.

References route_used.

Referenced by sb_route_count(), and SVC_Handler_C().

◆ __sb_subscribe()

bool __sb_subscribe	(	sb_msg_id_t	msg_id,
		uint8_t	pipe_idx
	)

Privileged implementation of sb_subscribe().

Parameters

[in]	msg_id	Message identifier.
[in]	pipe_idx	Kernel pipe index to bind.

Return values

true	Subscription added.
false	Table full, subscriber limit hit, or duplicate pair.

If no route exists for msg_id a new slot is allocated. Duplicate (msg_id, pipe_idx) pairs are rejected to prevent double-delivery.

Definition at line 110 of file sb.c.

References alloc_route(), sb_route_t::count, find_route(), sb_route_t::msg_id, sb_route_t::pipes, and SB_MAX_SUBS_PER_MSG.

Referenced by sb_subscribe(), and SVC_Handler_C().

◆ __sb_subscriber_count()

uint8_t __sb_subscriber_count ( sb_msg_id_t msg_id )

Privileged implementation of sb_subscriber_count().

Parameters

[in] msg_id Message identifier.

Returns: Active subscriber count, or 0 if no route exists.

Definition at line 200 of file sb.c.

References sb_route_t::count, and find_route().

Referenced by sb_subscriber_count(), and SVC_Handler_C().

◆ __sb_unsubscribe()

bool __sb_unsubscribe	(	sb_msg_id_t	msg_id,
		uint8_t	pipe_idx
	)

Privileged implementation of sb_unsubscribe().

Parameters

[in]	msg_id	Message identifier.
[in]	pipe_idx	Pipe to remove.

Return values

true	Subscription found and removed (last-swap compaction).
false	No matching subscription.

Definition at line 144 of file sb.c.

References sb_route_t::count, find_route(), and sb_route_t::pipes.

Referenced by sb_unsubscribe(), and SVC_Handler_C().

◆ sb_init()

void sb_init ( void )

Initialize the software bus.

Clears all routes.

Precondition: Kernel must be initialized (os_init() called).

Postcondition: Route table is empty; ready for sb_subscribe() calls.

Initialize the software bus.

Clears all routes in privileged mode.

Definition at line 221 of file sb.c.

References __sb_init(), and SVC_SB_INIT.

◆ sb_publish()

uint8_t sb_publish	(	sb_msg_id_t	msg_id,
		const uint8_t *	data,
		uint8_t	len
	)

Publish a message to all subscribers of msg_id.

Parameters

[in]	msg_id	Message identifier.
[in]	data	Payload bytes (must not be NULL when len > 0).
[in]	len	Payload length in bytes.

Returns: Number of subscribers the message was successfully enqueued to. Subscribers whose pipes are full are silently skipped.

Note: Never blocks. Uses pipe_can_enqueue() to test capacity before each write.

Publish a message to all subscribers of msg_id.

Parameters

[in]	msg_id	Message identifier.
[in]	data	Payload bytes.
[in]	len	Payload length.

Returns: Number of subscribers successfully enqueued to.

Definition at line 288 of file sb.c.

References __sb_publish(), and SVC_SB_PUBLISH.

◆ sb_route_count()

uint8_t sb_route_count ( void )

Return the total number of route entries in use.

Returns: Count of distinct msg_ids that have at least one subscriber.

Return the total number of route entries in use.

Returns: Number of distinct msg_ids with at least one subscriber.

Definition at line 334 of file sb.c.

References __sb_route_count(), and SVC_SB_ROUTE_COUNT.

◆ sb_subscribe()

bool sb_subscribe	(	sb_msg_id_t	msg_id,
		uint8_t	pipe_idx
	)

Subscribe a pipe to a message ID.

Parameters

[in]	msg_id	Message identifier to subscribe to.
[in]	pipe_idx	Kernel pipe index that will receive copies of published messages with this ID. The pipe must already be initialized via pipe_init().

Return values

true	Subscription added successfully.
false	Route table full, subscriber limit reached for this msg_id, or duplicate (msg_id, pipe_idx) pair.

Subscribe a pipe to a message ID.

Parameters

[in]	msg_id	Message identifier.
[in]	pipe_idx	Kernel pipe index.

Return values

true	Subscription added.
false	Table full, limit hit, or duplicate.

Definition at line 236 of file sb.c.

References __sb_subscribe(), and SVC_SB_SUBSCRIBE.

◆ sb_subscriber_count()

uint8_t sb_subscriber_count ( sb_msg_id_t msg_id )

Return the number of active subscriptions for a message ID.

Parameters

[in] msg_id Message identifier.

Returns: Subscriber count (0 if msg_id has no route).

Return the number of active subscriptions for a message ID.

Parameters

[in] msg_id Message identifier.

Returns: Active subscriber count, or 0 if no route exists.

Definition at line 313 of file sb.c.

References __sb_subscriber_count(), and SVC_SB_SUBSCRIBER_COUNT.

◆ sb_unsubscribe()

bool sb_unsubscribe	(	sb_msg_id_t	msg_id,
		uint8_t	pipe_idx
	)

Remove a subscription.

Parameters

[in]	msg_id	Message identifier.
[in]	pipe_idx	Pipe to unsubscribe.

Return values

true	Subscription found and removed.
false	No matching subscription exists.

Remove a subscription.

Parameters

[in]	msg_id	Message identifier.
[in]	pipe_idx	Pipe to unsubscribe.

Return values

true	Subscription found and removed.
false	No matching subscription.

Definition at line 262 of file sb.c.

References __sb_unsubscribe(), and SVC_SB_UNSUBSCRIBE.

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ sb_msg_id_t

Function Documentation

◆ __sb_init()

◆ __sb_publish()

◆ __sb_route_count()

◆ __sb_subscribe()

◆ __sb_subscriber_count()

◆ __sb_unsubscribe()

◆ sb_init()

◆ sb_publish()

◆ sb_route_count()

◆ sb_subscribe()

◆ sb_subscriber_count()

◆ sb_unsubscribe()