Safety Primitive Violation Notification

Opt-in handler for safe-pointer/checked-cast/bounds-check violations. More...

Files
file	src/utils/safestate/rte_safety_violation.c
	See rte_safety_violation.h for behavior.

Typedefs
typedef void(*)	rte_safety_violation_handler_t(rte_safety_violation_kind_t kind, const char *file, int32_t line, const char *message)
	Handler invoked by rte_safety_violation_report().

Enumerations
enum	rte_safety_violation_kind_t { RTE_SAFETY_VIOLATION_CORRUPTION = 0 , RTE_SAFETY_VIOLATION_OVERFLOW = 1 , RTE_SAFETY_VIOLATION_OUT_OF_RANGE = 2 }
	Which safety primitive detected the violation. More...

Functions
rte_status_t	rte_safety_violation_register_handler (rte_safety_violation_handler_t handler)
	Registers the single handler invoked by rte_safety_violation_report(). Registering again replaces the previous handler (same convention as rte_safestate_register_handler()).
void	rte_safety_violation_report (rte_safety_violation_kind_t kind, const char *file, int32_t line, const char *message)
	Reports one violation to the registered handler, if any.

Detailed Description

Opt-in handler for safe-pointer/checked-cast/bounds-check violations.

Typedef Documentation

rte_safety_violation_handler_t

typedef void(*) rte_safety_violation_handler_t(rte_safety_violation_kind_t kind, const char *file, int32_t line, const char *message)

Handler invoked by rte_safety_violation_report().

Parameters

kind	Which kind of violation was detected.
file	Detection site file (see this header's own

Note

on why this is the primitive's own file, not the caller's), may be NULL.

Parameters

line	Detection site line.
message	Human-readable detail (typically includes the actual values involved), may be NULL.

Note

Unlike rte_safestate_handler_t, this handler is expected to return - it is a notification, not a fault-reaction level. Do not call rte_safestate_enter() unconditionally from inside it; that would defeat the whole point of keeping this separate from rte_safestate (see this header's own file-level doc) - make that decision deliberately, in your own handler, if that is what your application wants for a specific kind.

Definition at line 99 of file rte_safety_violation.h.

Enumeration Type Documentation

rte_safety_violation_kind_t

enum rte_safety_violation_kind_t

Which safety primitive detected the violation.

Enumerator
RTE_SAFETY_VIOLATION_CORRUPTION	rte_safe_ptr_get()/_offset() found a corrupted canary (REQ-OAL-SAFEPTR-001) - never a normal condition.
RTE_SAFETY_VIOLATION_OVERFLOW	A rte_cast_checked_add_*()/_sub_*()/_mul_*() call detected overflow or underflow (REQ-COMMON-CAST-004).
RTE_SAFETY_VIOLATION_OUT_OF_RANGE	rte_cast_bounds_check() (REQ-COMMON-CAST-005) or rte_safe_ptr_offset()'s own bounds check (REQ-OAL-SAFEPTR-002) found index/offset+length outside the valid range.

Definition at line 65 of file rte_safety_violation.h.

Function Documentation

rte_safety_violation_register_handler()

rte_status_t rte_safety_violation_register_handler

(

rte_safety_violation_handler_t

handler

)

Registers the single handler invoked by rte_safety_violation_report(). Registering again replaces the previous handler (same convention as rte_safestate_register_handler()).

Parameters

handler

Handler to invoke on every reported violation. Must not be NULL - pass a handler that does nothing if you want to temporarily stop reacting without un-instrumenting the primitives themselves (there is no "unregister").

Returns

RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM if handler is NULL.

Definition at line 10 of file rte_safety_violation.c.

rte_safety_violation_report()

void rte_safety_violation_report	(	rte_safety_violation_kind_t	kind,
		const char *	file,
		int32_t	line,
		const char *	message )

Reports one violation to the registered handler, if any.

Called internally by rte_safe_ptr_get()/_offset() and the rte_cast_checked_*()/rte_cast_bounds_check() functions at their own detection points - not normally called directly by application code.

Parameters

kind	Which kind of violation occurred.
file	Detection site file, may be NULL.
line	Detection site line.
message	Human-readable detail, may be NULL.

Safety:

No-op (REQ-COMMON-SAFETYVIOLATION-002) if no handler is registered - reporting a violation can never itself introduce a new failure mode.

Definition at line 20 of file rte_safety_violation.c.