tables.h File Reference

ICARUS OS — Generic ground-loadable table engine. More...

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

Go to the source code of this file.

Data Structures
struct	tbl_descriptor_t
	Static descriptor registered by a table producer. More...

Macros
#define	TBL_MAX_REGISTERED   8
	Maximum number of registered tables
#define	TBL_MAX_SIZE   512
	Maximum bytes per table buffer
#define	TBL_NAME_LEN   12
	Maximum name length (incl.

Typedefs
typedef uint8_t	tbl_id_t
	Generic table identifier.
typedef bool(*	tbl_activate_fn) (const void *data, uint16_t len)
	Callback invoked when a staged table passes all CRC checks.

Functions
void	tbl_init (void)
	Initialise the table registry.
bool	tbl_register (const tbl_descriptor_t *desc)
	Register a table descriptor.
bool	tbl_load (tbl_id_t id, const uint8_t *data, uint16_t len, uint16_t schema_crc)
	Load raw bytes into the staging buffer for a registered table.
bool	tbl_activate (tbl_id_t id)
	Activate a staged table after CRC validation.
int16_t	tbl_dump (tbl_id_t id, uint8_t *out, uint16_t max)
	Copy the active table bytes into out.
const tbl_descriptor_t *	tbl_get_descriptor (tbl_id_t id)
	Look up a registered descriptor by id.
uint8_t	tbl_count (void)
	Return the number of registered tables.
void	__tbl_init (void)
bool	__tbl_register (const tbl_descriptor_t *desc)
bool	__tbl_load (tbl_id_t id, const uint8_t *data, uint16_t len, uint16_t schema_crc)
bool	__tbl_activate_prepare (tbl_id_t id, uint8_t *out_data, uint16_t *out_len, tbl_activate_fn *out_activate)
	Validate a staged table and copy it into a caller-provided scratch buffer for the activate callback.
bool	__tbl_activate_commit (tbl_id_t id, const uint8_t *data, uint16_t len)
	Commit a previously prepared table into the active buffer.
int16_t	__tbl_dump (tbl_id_t id, uint8_t *out, uint16_t max)
const tbl_descriptor_t *	__tbl_get_descriptor (tbl_id_t id)
uint8_t	__tbl_count (void)

Detailed Description

ICARUS OS — Generic ground-loadable table engine.

Maintains a registry of up to TBL_MAX_REGISTERED tables. Each registered slot has a staging buffer and an active buffer (double-buffered swap). Tables are validated by schema CRC and a CRC16-CCITT data checksum before the registered activate callback is called. Application-specific table-id constants live in downstream consumers; the engine itself is generic.

Author

Souham Biswas

Date

2026

Copyright

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

Definition in file tables.h.

Macro Definition Documentation

TBL_MAX_REGISTERED

#define TBL_MAX_REGISTERED   8

Maximum number of registered tables

Definition at line 32 of file tables.h.

TBL_MAX_SIZE

#define TBL_MAX_SIZE   512

Maximum bytes per table buffer

Definition at line 33 of file tables.h.

TBL_NAME_LEN

#define TBL_NAME_LEN   12

Maximum name length (incl.

NUL)

Definition at line 34 of file tables.h.

Typedef Documentation

tbl_activate_fn

typedef bool(* tbl_activate_fn) (const void *data, uint16_t len)

Callback invoked when a staged table passes all CRC checks.

Parameters

data	Pointer to the staged (validated) table bytes.
len	Number of bytes.

Returns

true on success; false to abort the swap (active unchanged).

Definition at line 54 of file tables.h.

tbl_id_t

typedef uint8_t tbl_id_t

Generic table identifier.

Downstream consumers define their own id constants (e.g. TBL_FDIR_RULES = 0x01) and pass them as tbl_id_t values into the engine.

Definition at line 43 of file tables.h.

Function Documentation

__tbl_activate_commit()

bool __tbl_activate_commit	(	tbl_id_t	id,
		const uint8_t *	data,
		uint16_t	len
	)

Commit a previously prepared table into the active buffer.

Called only after the user activate callback has succeeded.

< Maximum bytes per table buffer

Definition at line 176 of file tables.c.

References tbl_slot_t::active, tbl_slot_t::active_len, find_slot(), and TBL_MAX_SIZE.

Referenced by SVC_Handler_C(), and tbl_activate().

__tbl_activate_prepare()

bool __tbl_activate_prepare	(	tbl_id_t	id,
		uint8_t *	out_data,
		uint16_t *	out_len,
		tbl_activate_fn *	out_activate
	)

Validate a staged table and copy it into a caller-provided scratch buffer for the activate callback.

The active buffer is not touched yet.

Parameters

id	Table id.
out_data	Caller scratch buffer (must be ≥ TBL_MAX_SIZE).
out_len	[out] Number of bytes written to scratch.
out_activate	[out] Pointer to the user activate callback (or NULL).

Returns

true on validation success; false otherwise.

Definition at line 139 of file tables.c.

References tbl_descriptor_t::activate, crc16_ccitt(), tbl_slot_t::desc, find_slot(), tbl_descriptor_t::schema_crc, tbl_descriptor_t::size, tbl_slot_t::staged_data_crc, tbl_slot_t::staged_len, tbl_slot_t::staged_schema_crc, tbl_slot_t::staged_valid, and tbl_slot_t::staging.

Referenced by SVC_Handler_C(), and tbl_activate().

__tbl_count()

uint8_t __tbl_count

(

void

)

Definition at line 216 of file tables.c.

References reg_count.

Referenced by SVC_Handler_C(), and tbl_count().

__tbl_dump()

int16_t __tbl_dump	(	tbl_id_t	id,
		uint8_t *	out,
		uint16_t	max
	)

Definition at line 190 of file tables.c.

References tbl_slot_t::active, tbl_slot_t::active_len, and find_slot().

Referenced by SVC_Handler_C(), and tbl_dump().

__tbl_get_descriptor()

const tbl_descriptor_t * __tbl_get_descriptor

(

tbl_id_t

id

)

Definition at line 211 of file tables.c.

References tbl_slot_t::desc, and find_slot().

Referenced by SVC_Handler_C(), and tbl_get_descriptor().

__tbl_init()

void __tbl_init

(

void

)

Definition at line 71 of file tables.c.

References reg_count, and registry.

Referenced by SVC_Handler_C(), and tbl_init().

__tbl_load()

bool __tbl_load	(	tbl_id_t	id,
		const uint8_t *	data,
		uint16_t	len,
		uint16_t	schema_crc
	)

< Maximum bytes per table buffer

Definition at line 100 of file tables.c.

References crc16_ccitt(), tbl_slot_t::desc, find_slot(), tbl_descriptor_t::size, tbl_slot_t::staged_data_crc, tbl_slot_t::staged_len, tbl_slot_t::staged_schema_crc, tbl_slot_t::staged_valid, tbl_slot_t::staging, and TBL_MAX_SIZE.

Referenced by SVC_Handler_C(), and tbl_load().

__tbl_register()

bool __tbl_register

(

const tbl_descriptor_t *

desc

)

< Maximum number of registered tables

< Maximum bytes per table buffer

< Maximum name length (incl. NUL)

Definition at line 76 of file tables.c.

References tbl_slot_t::desc, tbl_descriptor_t::id, tbl_descriptor_t::name, reg_count, registry, tbl_descriptor_t::size, TBL_MAX_REGISTERED, TBL_MAX_SIZE, and TBL_NAME_LEN.

Referenced by SVC_Handler_C(), and tbl_register().

tbl_activate()

bool tbl_activate

(

tbl_id_t

id

)

Activate a staged table after CRC validation.

Steps:

1. Verify staged_len == descriptor.size.
2. Verify staged_schema_crc == descriptor.schema_crc.
3. Recompute CRC16-CCITT over staged data; verify against stored crc.
4. Call descriptor.activate(staged, size).
5. On success, copy staging → active buffer.

Returns

true on success; false on any validation failure or activate callback returning false.

< Maximum bytes per table buffer

Definition at line 1481 of file svc.c.

References __tbl_activate_commit(), __tbl_activate_prepare(), SVC_TBL_ACTIVATE_COMMIT, SVC_TBL_ACTIVATE_PREPARE, and TBL_MAX_SIZE.

tbl_count()

uint8_t tbl_count

(

void

)

Return the number of registered tables.

Definition at line 1583 of file svc.c.

References __tbl_count(), and SVC_TBL_COUNT.

tbl_dump()

int16_t tbl_dump	(	tbl_id_t	id,
		uint8_t *	out,
		uint16_t	max
	)

Copy the active table bytes into out.

Returns

Number of bytes copied, or -1 on error (unknown id / no active).

Definition at line 1546 of file svc.c.

References __tbl_dump(), and SVC_TBL_DUMP.

tbl_get_descriptor()

const tbl_descriptor_t * tbl_get_descriptor

(

tbl_id_t

id

)

Look up a registered descriptor by id.

Returns

Pointer to descriptor, or NULL if not found.

Definition at line 1566 of file svc.c.

References __tbl_get_descriptor(), and SVC_TBL_GET_DESCRIPTOR.

tbl_init()

void tbl_init

(

void

)

Initialise the table registry.

Must be called before any other table function.

Definition at line 1428 of file svc.c.

References __tbl_init(), and SVC_TBL_INIT.

tbl_load()

bool tbl_load	(	tbl_id_t	id,
		const uint8_t *	data,
		uint16_t	len,
		uint16_t	schema_crc
	)

Load raw bytes into the staging buffer for a registered table.

Supports chunked loads: call repeatedly with sequential offsets. The first call clears the staging buffer; subsequent calls append. Once a full descriptor-size load completes the data CRC16 is computed and the staging buffer is marked valid.

Returns

true on success; false on unknown id or out-of-bounds write.

Definition at line 1453 of file svc.c.

References __tbl_load(), and SVC_TBL_LOAD.

tbl_register()

bool tbl_register

(

const tbl_descriptor_t *

desc

)

Register a table descriptor.

Returns

true on success; false if registry is full or id is duplicate.

Definition at line 1436 of file svc.c.

References __tbl_register(), and SVC_TBL_REGISTER.