sapi_posix_backend.h File Reference

Real POSIX/Linux backend for every OAL service (ADR-018). More...

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/oal/timer/sapi_timer.h"
#include "safeapi_backend/timer/sapi_timer_backend.h"
#include "safeapi/oal/mutex/sapi_mutex.h"
#include "safeapi_backend/mutex/sapi_mutex_backend.h"
#include "safeapi/oal/ipc/sapi_ipc.h"
#include "safeapi_backend/ipc/sapi_ipc_backend.h"
#include "safeapi/oal/netlink/sapi_netlink.h"
#include "safeapi_backend/netlink/sapi_netlink_backend.h"
#include "safeapi/oal/task/sapi_task.h"
#include "safeapi_backend/task/sapi_task_backend.h"
#include "safeapi/oal/log/sapi_log.h"
#include "safeapi_backend/log/sapi_log_backend.h"
#include "safeapi/oal/nvm/sapi_nvm.h"
#include "safeapi_backend/nvm/sapi_nvm_backend.h"
#include "safeapi/oal/reboot/sapi_reboot.h"
#include "safeapi_backend/reboot/sapi_reboot_backend.h"
#include "safeapi/oal/memory/sapi_memory.h"
#include "safeapi_backend/memory/sapi_memory_backend.h"
#include "safeapi/oal/platform/sapi_platform.h"
#include "safeapi_backend/platform/sapi_platform_backend.h"
#include "safeapi/posix_backend/sapi_posix_backend_channel_service.h"

Include dependency graph for sapi_posix_backend.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
sapi_status_t	sapi_posix_backend_register_all (void)
	Registers this file's POSIX backend with every OAL service in one call. Call once at process startup, before any other sapi_<service>_* function.
const sapi_timer_backend_t *	sapi_posix_backend_timer (void)
	The POSIX sapi_timer backend (one pthread per timer).
const sapi_mutex_backend_t *	sapi_posix_backend_mutex (void)
	The POSIX sapi_mutex backend (a thin pthread_mutex_t wrapper, ADR-033).
const sapi_ipc_backend_t *	sapi_posix_backend_ipc (void)
	The POSIX sapi_ipc backend (pipe() per channel).
const sapi_netlink_backend_t *	sapi_posix_backend_netlink (void)
	The POSIX sapi_netlink backend (TCP sockets, LISTEN/CONNECT).
const sapi_task_backend_t *	sapi_posix_backend_task (void)
	The POSIX sapi_task backend (one pthread per task).
const sapi_log_backend_t *	sapi_posix_backend_log (void)
	The POSIX sapi_log backend (non-blocking write to stderr).
const sapi_nvm_backend_t *	sapi_posix_backend_nvm (void)
	The POSIX sapi_nvm backend (file-backed, FNV-1a-64 integrity).
const sapi_reboot_backend_t *	sapi_posix_backend_reboot (void)
	The POSIX sapi_reboot backend (execv() re-exec of the current process image, self-path resolved portably per-OS - see sapi_posix_backend_reboot.c's file header).
void	sapi_posix_backend_reboot_set_argv (int argc, char *const argv[])
	Registers the original process argv[] the POSIX reboot backend should re-exec with (instead of its own placeholder argv[0]). Call once, early in main(), with the same argc/argv main() itself received - e.g. right after this project's own argv parsing (role/site), so a REBOOT-triggered re-exec restarts the SAME role for the SAME site rather than losing that information and falling back to a placeholder command line the freshly re-exec'd process cannot make sense of.
const sapi_mem_pool_backend_t *	sapi_posix_backend_memory (void)
	The POSIX sapi_memory backend (static arena, no malloc).
const sapi_platform_backend_t *	sapi_posix_backend_platform (void)
	The POSIX sapi_platform backend (ADR-035): real-time bring-up via mlockall() + SCHED_FIFO, best-effort, on Linux; a no-op returning SAPI_STATUS_OK on any other POSIX host. Register it (directly or via sapi_posix_backend_register_all()) and call sapi_platform_realtime_init() through the framework rather than reaching for a backend symbol - see safeAPIFreamwork's docs/architecture/ADR-035-platform-realtime-init.md.

Detailed Description

Real POSIX/Linux backend for every OAL service (ADR-018).

A single sapi_posix_backend_register_all() call at startup registers this file's implementation with every OAL service (timer/mutex/ipc/netlink/task/log/nvm/reboot/memory/platform) - the same "one entry point" pattern sapi_appmanager already uses elsewhere. Individual sapi_posix_backend_<service>() accessors are also exposed for callers who want to register only some services with the real backend and mock/stub the rest (e.g. in tests, or a hybrid deployment).

See safeAPIFreamwork's docs/architecture/ADR-018-posix-oal-backend.md for what "real" means for each of the original seven services and the specific, deliberate simplifications each one makes. The netlink (TCP) backend was added later, alongside safeAPIRBC2oo2's multi-process A/B/C topology - see sapi_posix_backend_netlink.c's own file header for its design notes.

Definition in file sapi_posix_backend.h.

Function Documentation

sapi_posix_backend_ipc()

const sapi_ipc_backend_t * sapi_posix_backend_ipc

(

void

)

The POSIX sapi_ipc backend (pipe() per channel).

Definition at line 211 of file sapi_posix_backend_ipc.c.

sapi_posix_backend_log()

const sapi_log_backend_t * sapi_posix_backend_log

(

void

)

The POSIX sapi_log backend (non-blocking write to stderr).

Global variables declarations Global functions

Definition at line 37 of file sapi_posix_backend_log.c.

sapi_posix_backend_memory()

const sapi_mem_pool_backend_t * sapi_posix_backend_memory

(

void

)

The POSIX sapi_memory backend (static arena, no malloc).

Global variables declarations Global functions

Definition at line 77 of file sapi_posix_backend_memory.c.

sapi_posix_backend_mutex()

const sapi_mutex_backend_t * sapi_posix_backend_mutex

(

void

)

The POSIX sapi_mutex backend (a thin pthread_mutex_t wrapper, ADR-033).

Global variables declarations Global functions

Definition at line 42 of file sapi_posix_backend_mutex.c.

sapi_posix_backend_netlink()

const sapi_netlink_backend_t * sapi_posix_backend_netlink

(

void

)

The POSIX sapi_netlink backend (TCP sockets, LISTEN/CONNECT).

Definition at line 658 of file sapi_posix_backend_netlink.c.

sapi_posix_backend_nvm()

const sapi_nvm_backend_t * sapi_posix_backend_nvm

(

void

)

The POSIX sapi_nvm backend (file-backed, FNV-1a-64 integrity).

Definition at line 336 of file sapi_posix_backend_nvm.c.

sapi_posix_backend_platform()

const sapi_platform_backend_t * sapi_posix_backend_platform

(

void

)

The POSIX sapi_platform backend (ADR-035): real-time bring-up via mlockall() + SCHED_FIFO, best-effort, on Linux; a no-op returning SAPI_STATUS_OK on any other POSIX host. Register it (directly or via sapi_posix_backend_register_all()) and call sapi_platform_realtime_init() through the framework rather than reaching for a backend symbol - see safeAPIFreamwork's docs/architecture/ADR-035-platform-realtime-init.md.

Global variables declarations Global functions

Definition at line 73 of file sapi_posix_backend_platform.c.

sapi_posix_backend_reboot()

const sapi_reboot_backend_t * sapi_posix_backend_reboot

(

void

)

The POSIX sapi_reboot backend (execv() re-exec of the current process image, self-path resolved portably per-OS - see sapi_posix_backend_reboot.c's file header).

Definition at line 114 of file sapi_posix_backend_reboot.c.

sapi_posix_backend_reboot_set_argv()

void sapi_posix_backend_reboot_set_argv	(	int	argc,
		char *const	argv[] )

Registers the original process argv[] the POSIX reboot backend should re-exec with (instead of its own placeholder argv[0]). Call once, early in main(), with the same argc/argv main() itself received - e.g. right after this project's own argv parsing (role/site), so a REBOOT-triggered re-exec restarts the SAME role for the SAME site rather than losing that information and falling back to a placeholder command line the freshly re-exec'd process cannot make sense of.

Not calling this at all is still valid - the backend then falls back to its original placeholder-argv behavior (see sapi_posix_backend_reboot.c), which is fine for a caller whose own main() takes no arguments it needs preserved across a reboot.

Parameters

argc	Argument count, as received by main(). Only the first SAPI_POSIX_REBOOT_MAX_ARGV entries are retained (the backend has no dynamic allocation - REQ-OAL-REBOOT-001's fixed-storage convention).
argv	Argument vector, as received by main(). The pointers themselves are stored (not copied) - valid because argv's string storage is guaranteed to remain valid for the whole process lifetime, same as main()'s own copy of it. Must not be NULL if argc > 0.

Global variables declarations Global functions

Definition at line 97 of file sapi_posix_backend_reboot.c.

sapi_posix_backend_register_all()

sapi_status_t sapi_posix_backend_register_all

(

void

)

Registers this file's POSIX backend with every OAL service in one call. Call once at process startup, before any other sapi_<service>_* function.

Returns

SAPI_STATUS_OK if every service registered successfully; the first non-OK status encountered otherwise (registration stops at the first failure - a partially-registered state is itself a startup fault, not something to paper over).

Local makros Local types declarations Local variables declarations Global variables declarations Local function declarations Global functions

Definition at line 20 of file sapi_posix_backend.c.

sapi_posix_backend_task()

const sapi_task_backend_t * sapi_posix_backend_task

(

void

)

The POSIX sapi_task backend (one pthread per task).

Definition at line 273 of file sapi_posix_backend_task.c.

sapi_posix_backend_timer()

const sapi_timer_backend_t * sapi_posix_backend_timer

(

void

)

The POSIX sapi_timer backend (one pthread per timer).

Global variables declarations Global functions

Definition at line 62 of file sapi_posix_backend_timer.c.