rte_posix_osadapter.h File Reference

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

#include "rte/utils/status/rte_status.h"
#include "rte/oal/timer/rte_timer.h"
#include "rte_osadapter/timer/rte_osadapter_timer.h"
#include "rte/oal/mutex/rte_mutex.h"
#include "rte_osadapter/mutex/rte_osadapter_mutex.h"
#include "rte/oal/ipc/rte_ipc.h"
#include "rte_osadapter/ipc/rte_osadapter_ipc.h"
#include "rte/oal/netlink/rte_netlink.h"
#include "rte_osadapter/netlink/rte_osadapter_netlink.h"
#include "rte/oal/task/rte_task.h"
#include "rte_osadapter/task/rte_osadapter_task.h"
#include "rte/oal/log/rte_log.h"
#include "rte_osadapter/log/rte_osadapter_log.h"
#include "rte/oal/nvm/rte_nvm.h"
#include "rte_osadapter/nvm/rte_osadapter_nvm.h"
#include "rte/oal/reboot/rte_reboot.h"
#include "rte_osadapter/reboot/rte_osadapter_reboot.h"
#include "rte/oal/memory/rte_memory.h"
#include "rte_osadapter/memory/rte_osadapter_memory.h"
#include "rte/oal/platform/rte_platform.h"
#include "rte_osadapter/platform/rte_osadapter_platform.h"
#include "rte/oal/random/rte_random.h"
#include "rte_osadapter/random/rte_osadapter_random.h"
#include "rte/posix_osadapter/rte_posix_osadapter_channel_service.h"
#include "rte_osadapter/rte_osadapter.h"

Include dependency graph for rte_posix_osadapter.h:

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

Go to the source code of this file.

Functions
rte_status_t	rte_posix_osadapter_register_all (void)
	Registers this file's POSIX OSAdapter with every OAL service in one call. Call once at process startup, before any other rte_<service>_* function. Creates the memory OSAdapter's priority-inheritance pool lock (rte_posix_osadapter_memory_init()) before registering that OSAdapter.
const rte_os_socket_ops_t *	rte_posix_osadapter_socket_ops (void)
	The POSIX raw OS socket operations vtable (UDP and TCP).
const rte_osadapter_timer_t *	rte_posix_osadapter_timer (void)
	The POSIX rte_timer OSAdapter (one pthread per timer).
const rte_osadapter_mutex_t *	rte_posix_osadapter_mutex (void)
	The POSIX rte_mutex OSAdapter (a thin pthread_mutex_t wrapper, ADR-033).
const rte_osadapter_ipc_t *	rte_posix_osadapter_ipc (void)
	The POSIX rte_ipc OSAdapter (pipe() per channel).
const rte_osadapter_netlink_t *	rte_posix_osadapter_netlink (void)
	The POSIX rte_netlink OSAdapter (TCP sockets, LISTEN/CONNECT).
const rte_osadapter_task_t *	rte_posix_osadapter_task (void)
	The POSIX rte_task OSAdapter (one pthread per task).
const rte_osadapter_log_t *	rte_posix_osadapter_log (void)
	The POSIX rte_log OSAdapter (non-blocking write to stderr).
const rte_osadapter_nvm_t *	rte_posix_osadapter_nvm (void)
	The POSIX rte_nvm OSAdapter (file-backed, FNV-1a-64 integrity).
const rte_osadapter_reboot_t *	rte_posix_osadapter_reboot (void)
	The POSIX rte_reboot OSAdapter (execv() re-exec of the current process image, self-path resolved portably per-OS - see rte_posix_osadapter_reboot.c's file header).
void	rte_posix_osadapter_reboot_set_argv (int argc, char *const argv[])
	Registers the original process argv[] the POSIX reboot OSAdapter 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 rte_osadapter_memory_t *	rte_posix_osadapter_memory (void)
	The POSIX rte_memory OSAdapter (static arena, no malloc). Its operations return RTE_STATUS_INVALID_STATE until rte_posix_osadapter_memory_init() has succeeded.
rte_status_t	rte_posix_osadapter_memory_init (void)
	Creates the memory OSAdapter's pool lock as a priority-inheritance mutex (OSA rule R2, REQ-OAL-MUTEX-004). Composition-root wiring: rte_posix_osadapter_register_all() calls it before it registers the memory OSAdapter; a caller that registers rte_posix_osadapter_memory() on its own calls it first. Call at single-threaded startup, before any thread uses the pools.
const rte_osadapter_platform_t *	rte_posix_osadapter_platform (void)
	The POSIX rte_platform OSAdapter (ADR-035): real-time bring-up via mlockall() + SCHED_FIFO, best-effort, on Linux; a no-op returning RTE_STATUS_OK on any other POSIX host. Register it (directly or via rte_posix_osadapter_register_all()) and call rte_platform_realtime_init() through the framework rather than reaching for an OSAdapter symbol - see safeAPIFreamwork's docs/architecture/ADR-035-platform-realtime-init.md.
const rte_osadapter_random_t *	rte_posix_osadapter_random (void)
	The POSIX rte_random OSAdapter: the kernel CSPRNG via getentropy(); fails (never falls back) if it is unavailable - REQ-OAL-RANDOM-001.

Detailed Description

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

A single rte_posix_osadapter_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 rte_appmanager already uses elsewhere. Individual rte_posix_osadapter_<service>() accessors are also exposed for callers who want to register only some services with the real OSAdapter and mock/stub the rest (e.g. in tests, or a hybrid deployment).

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

Definition in file rte_posix_osadapter.h.

Function Documentation

rte_posix_osadapter_ipc()

const rte_osadapter_ipc_t * rte_posix_osadapter_ipc

(

void

)

The POSIX rte_ipc OSAdapter (pipe() per channel).

A bounded queue of whole messages (OSA rule R5). create returns RTE_STATUS_NOT_SUPPORTED for a message_size above PIPE_BUF (4096 on Linux, 512 on macOS), RTE_STATUS_INVALID_PARAM if message_size * queue_depth overflows, RTE_STATUS_RESOURCE_EXHAUSTED if the pipe cannot hold queue_depth messages (Linux: the pipe size set and read back; other hosts: RTE_POSIX_IPC_PIPE_CAPACITY, default 16384 bytes) and RTE_STATUS_INTERNAL_ERROR if a pipe end cannot be made non-blocking; on every error *out_handle is unwritten. send takes exactly message_size bytes (else RTE_STATUS_INVALID_PARAM) and returns RTE_STATUS_TIMEOUT while queue_depth messages stay queued for the whole timeout (exact for one sender per channel; N concurrent senders can overshoot by N-1). receive needs a buffer of at least message_size bytes (else RTE_STATUS_INVALID_PARAM) and reads exactly one message.

Returns

Pointer to the static IPC OSAdapter vtable; never NULL.

Global functions

Definition at line 519 of file rte_posix_osadapter_ipc.c.

rte_posix_osadapter_log()

const rte_osadapter_log_t * rte_posix_osadapter_log

(

void

)

The POSIX rte_log OSAdapter (non-blocking write to stderr).

Global variables declarations Global functions

Definition at line 37 of file rte_posix_osadapter_log.c.

rte_posix_osadapter_memory()

const rte_osadapter_memory_t * rte_posix_osadapter_memory

(

void

)

The POSIX rte_memory OSAdapter (static arena, no malloc). Its operations return RTE_STATUS_INVALID_STATE until rte_posix_osadapter_memory_init() has succeeded.

Global variables declarations Global functions

Definition at line 110 of file rte_posix_osadapter_memory.c.

rte_posix_osadapter_memory_init()

rte_status_t rte_posix_osadapter_memory_init

(

void

)

Creates the memory OSAdapter's pool lock as a priority-inheritance mutex (OSA rule R2, REQ-OAL-MUTEX-004). Composition-root wiring: rte_posix_osadapter_register_all() calls it before it registers the memory OSAdapter; a caller that registers rte_posix_osadapter_memory() on its own calls it first. Call at single-threaded startup, before any thread uses the pools.

Idempotent: once it has succeeded, a further call returns RTE_STATUS_OK and does not create the lock again. There is no fallback to a plain mutex: if the host refuses priority inheritance the pool stays uninitialised (every rte_osadapter_memory_t operation keeps returning RTE_STATUS_INVALID_STATE) and the refusal is reported as DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE.

Returns

RTE_STATUS_OK if the lock exists (created now or by an earlier call); RTE_STATUS_INTERNAL_ERROR if pthread_mutexattr_init(), pthread_mutexattr_setprotocol(PTHREAD_PRIO_INHERIT) or pthread_mutex_init() failed.

Definition at line 115 of file rte_posix_osadapter_memory.c.

rte_posix_osadapter_mutex()

const rte_osadapter_mutex_t * rte_posix_osadapter_mutex

(

void

)

The POSIX rte_mutex OSAdapter (a thin pthread_mutex_t wrapper, ADR-033).

Global variables declarations Global functions

Definition at line 65 of file rte_posix_osadapter_mutex.c.

rte_posix_osadapter_netlink()

const rte_osadapter_netlink_t * rte_posix_osadapter_netlink

(

void

)

The POSIX rte_netlink OSAdapter (TCP sockets, LISTEN/CONNECT).

Definition at line 744 of file rte_posix_osadapter_netlink.c.

rte_posix_osadapter_nvm()

const rte_osadapter_nvm_t * rte_posix_osadapter_nvm

(

void

)

The POSIX rte_nvm OSAdapter (file-backed, FNV-1a-64 integrity).

Definition at line 336 of file rte_posix_osadapter_nvm.c.

rte_posix_osadapter_platform()

const rte_osadapter_platform_t * rte_posix_osadapter_platform

(

void

)

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

Global variables declarations Global functions

Definition at line 73 of file rte_posix_osadapter_platform.c.

rte_posix_osadapter_random()

const rte_osadapter_random_t * rte_posix_osadapter_random

(

void

)

The POSIX rte_random OSAdapter: the kernel CSPRNG via getentropy(); fails (never falls back) if it is unavailable - REQ-OAL-RANDOM-001.

Definition at line 23 of file rte_posix_osadapter_random.c.

rte_posix_osadapter_reboot()

const rte_osadapter_reboot_t * rte_posix_osadapter_reboot

(

void

)

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

Definition at line 114 of file rte_posix_osadapter_reboot.c.

rte_posix_osadapter_reboot_set_argv()

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

Registers the original process argv[] the POSIX reboot OSAdapter 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 OSAdapter then falls back to its original placeholder-argv behavior (see rte_posix_osadapter_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 RTE_POSIX_REBOOT_MAX_ARGV entries are retained (the OSAdapter 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 rte_posix_osadapter_reboot.c.

rte_posix_osadapter_register_all()

rte_status_t rte_posix_osadapter_register_all

(

void

)

Registers this file's POSIX OSAdapter with every OAL service in one call. Call once at process startup, before any other rte_<service>_* function. Creates the memory OSAdapter's priority-inheritance pool lock (rte_posix_osadapter_memory_init()) before registering that OSAdapter.

Returns

RTE_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 21 of file rte_posix_osadapter.c.

rte_posix_osadapter_socket_ops()

const rte_os_socket_ops_t * rte_posix_osadapter_socket_ops

(

void

)

The POSIX raw OS socket operations vtable (UDP and TCP).

open returns a non-blocking socket (O_NONBLOCK, OSA rule R5): recv/send on it return RTE_STATUS_TIMEOUT instead of blocking; set_nonblocking(false) switches it to blocking. If O_NONBLOCK cannot be set, open closes the socket, leaves *out_handle unwritten and returns RTE_STATUS_INTERNAL_ERROR.

Returns

The adapter's static vtable (never NULL).

Definition at line 371 of file rte_posix_osadapter_socket.c.

rte_posix_osadapter_task()

const rte_osadapter_task_t * rte_posix_osadapter_task

(

void

)

The POSIX rte_task OSAdapter (one pthread per task).

Priority scale: rte_task_config_t::priority is a SCHED_FIFO priority, clamped into [sched_get_priority_min(SCHED_FIFO), sched_get_priority_max(SCHED_FIFO)]. It is set on the thread attributes (PTHREAD_EXPLICIT_SCHED) together with the stack size before pthread_create (OSA rule R1). Where SCHED_FIFO is refused (no privilege), start reports DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE and the thread runs with inherited scheduling (ADR-018).

Every thread start creates is joined (OSA rule R2): by suspend and destroy, also after a run-once entry has returned, and by a restart (start on a started task) before the new thread is created. A failed pthread_join returns RTE_STATUS_INTERNAL_ERROR and keeps the thread for a later suspend or destroy. From the task's own entry (periodic or run-once), suspend and destroy only end the task (RTE_STATUS_OK, entry not called again; the next start, suspend or destroy from another thread joins the thread) and start returns RTE_STATUS_NOT_SUPPORTED without changing anything. The entry's own thread is recognised through thread-specific data (one pthread key per process, created by the first create and never deleted): create returns RTE_STATUS_INTERNAL_ERROR if the key cannot be created, and a task thread that cannot store its mark reports DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE and calls no entry. Suspend and destroy wake a periodic task thread that waits for its next period (the same process-wide wake object as the timer OSAdapter's; create returns RTE_STATUS_INTERNAL_ERROR if it cannot be created), so they do not wait for the rest of the period. The join is an unbounded wait for the entry in progress.

Returns

Pointer to the static task OSAdapter vtable; never NULL.

Definition at line 481 of file rte_posix_osadapter_task.c.

rte_posix_osadapter_timer()

const rte_osadapter_timer_t * rte_posix_osadapter_timer

(

void

)

The POSIX rte_timer OSAdapter (one pthread per timer).

The expiry callback runs on the timer's own thread. Start sets on the thread attributes, before pthread_create (OSA rule R1), a fixed stack size (RTE_POSIX_TIMER_STACK_SIZE, default 8 MiB) and PTHREAD_EXPLICIT_SCHED with the scheduling policy and priority of the thread calling start. Where that is refused, start reports DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE and the thread runs with inherited scheduling (ADR-018).

Every thread start creates is joined (OSA rule R2): by stop and destroy, also after a one-shot timer has fired, and by a restart (start on a started timer) before the new thread is created. A failed pthread_join returns RTE_STATUS_INTERNAL_ERROR and keeps the thread for a later stop or destroy. From the timer's own callback, stop and destroy only end the timer (RTE_STATUS_OK, no further callback; the next stop, start or destroy from another thread joins the thread) and start returns RTE_STATUS_NOT_SUPPORTED without changing anything. The callback's own thread is recognised through thread-specific data (one pthread key per process, created by the first create and never deleted): create returns RTE_STATUS_INTERNAL_ERROR if the key cannot be created, and a timer thread that cannot store its mark reports DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE and runs no callback. Stop and destroy wake a timer thread that waits for its next expiry (one process-wide priority-inheritance mutex and condition variable, created by the first timer or task create and never deleted; create returns RTE_STATUS_INTERNAL_ERROR and reports DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE once if it cannot be created), so they do not wait for the rest of the period. The join is an unbounded wait for the callback in progress.

Returns

Pointer to the static timer OSAdapter vtable; never NULL.

Global variables declarations Global functions

Definition at line 182 of file rte_posix_osadapter_timer.c.