ab_gp_cycle_ticks.h File Reference

A/B cycle tick count shared by the cycle timer callback and the cycle thread (ISS-051). More...

#include <stdint.h>
#include "rte/oal/mutex/rte_mutex.h"
#include "rte/utils/status/rte_status.h"
#include "rte/utils/types/rte_types.h"

Include dependency graph for ab_gp_cycle_ticks.h:

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

Go to the source code of this file.

Data Structures
struct	ab_gp_cycle_ticks_t
	Tick count and the mutex that guards it. Not volatile: every access to count holds the mutex. More...

Macros
#define	AB_GP_CYCLE_TICKS_LOCK_TIMEOUT_MS   10U
	Longest wait for the tick count's mutex, in ms (OSA rule R2). Far above the critical section's hold time, far below the cycle period (500 ms).

Functions
rte_status_t	ab_gp_cycle_ticks_setup (ab_gp_cycle_ticks_t *ticks)
	Creates the mutex and clears the count. Setup phase only (rte_mutex_create() is a setup-only resource, ADR-026); call before the timer that posts is created. Does not check for an earlier setup of ticks.
rte_status_t	ab_gp_cycle_ticks_post (ab_gp_cycle_ticks_t *ticks)
	Adds one tick (timer callback side). The count saturates at UINT32_MAX.
rte_status_t	ab_gp_cycle_ticks_take (ab_gp_cycle_ticks_t *ticks, uint32_t *out_pending)
	Returns every pending tick and clears the count, as one critical section (cycle thread side).
rte_status_t	ab_gp_cycle_ticks_teardown (ab_gp_cycle_ticks_t *ticks)
	Destroys the mutex. Call only when no other task can post or take any more (the posting timer is destroyed). The instance is not set up afterwards, whatever the result.

Detailed Description

A/B cycle tick count shared by the cycle timer callback and the cycle thread (ISS-051).

The periodic cycle timer posts one tick per expiry; the cyclic executive takes every pending tick at the top of a cycle. The count used to be a volatile uint32_t incremented by the timer callback and read, then cleared, by the cycle thread with no synchronisation: a tick posted between the read and the clear was lost, and a late increment store could bring already consumed ticks back. Either way the channel's cycle number drifted from its sibling's.

Here every access to the count holds an RTE mutex (ADR-033; REQ-OAL-MUTEX-001 forbids a platform primitive in the application, and the C99 build has no <stdatomic.h>), and ab_gp_cycle_ticks_take() reads and clears in one critical section.

Safety argument:

• Every wait is bounded (OSA rule R2): the lock is rte_mutex_lock_timed() with AB_GP_CYCLE_TICKS_LOCK_TIMEOUT_MS.
• The critical section is a few instructions (one compare and one store, or one load and one store) and calls nothing, and the mutex uses priority inheritance (REQ-OAL-MUTEX-004), so the cycle thread is never held up by more than that section. The priority-inheritance part holds on Linux, where the timed lock is pthread_mutex_timedlock(); a non-Linux development host (macOS) polls with a trylock every 1 ms, and a waiter that is not blocked on the mutex gives the holder no boost.
• REQ-OAL-TIMER-003 asks for a "bounded-time, non-blocking context" in a timer callback. The callback meets the first half only: it can block for up to AB_GP_CYCLE_TICKS_LOCK_TIMEOUT_MS (10 ms) waiting for the mutex. It is bounded, it is not non-blocking.
• A lock or unlock status other than RTE_STATUS_OK is returned to the caller, never ignored here.

Assumption: the OSAdapter runs timer callbacks in task context (true for Platform_OS_POSIX: a timer thread). A port whose timer callbacks run in interrupt context must not take a mutex there and needs another primitive for the post side.

The caller owns the instance. It must be all-zero before ab_gp_cycle_ticks_setup() (static storage, or cleared with rte_mem_set()), so that a post, take or teardown before setup is refused instead of using an indeterminate handle.

Definition in file ab_gp_cycle_ticks.h.

Macro Definition Documentation

AB_GP_CYCLE_TICKS_LOCK_TIMEOUT_MS

#define AB_GP_CYCLE_TICKS_LOCK_TIMEOUT_MS   10U

Longest wait for the tick count's mutex, in ms (OSA rule R2). Far above the critical section's hold time, far below the cycle period (500 ms).

Definition at line 44 of file ab_gp_cycle_ticks.h.

Function Documentation

ab_gp_cycle_ticks_setup()

rte_status_t ab_gp_cycle_ticks_setup

(

ab_gp_cycle_ticks_t *

ticks

)

Creates the mutex and clears the count. Setup phase only (rte_mutex_create() is a setup-only resource, ADR-026); call before the timer that posts is created. Does not check for an earlier setup of ticks.

Parameters

ticks

instance to set up, all-zero or torn down

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM when ticks is NULL; otherwise the status of rte_mutex_create() (the instance then stays not set up)

Definition at line 9 of file ab_gp_cycle_ticks.c.

ab_gp_cycle_ticks_post()

rte_status_t ab_gp_cycle_ticks_post

(

ab_gp_cycle_ticks_t *

ticks

)

Adds one tick (timer callback side). The count saturates at UINT32_MAX.

Parameters

ticks

instance to post to

Returns

RTE_STATUS_OK when the tick was counted; RTE_STATUS_INVALID_PARAM when ticks is NULL; RTE_STATUS_INVALID_STATE before setup or after teardown; otherwise the status of the failed rte_mutex_lock_timed() (RTE_STATUS_TIMEOUT after AB_GP_CYCLE_TICKS_LOCK_TIMEOUT_MS; the tick is then not counted) or of the failed rte_mutex_unlock() (the tick is then counted)

Definition at line 30 of file ab_gp_cycle_ticks.c.

ab_gp_cycle_ticks_take()

rte_status_t ab_gp_cycle_ticks_take	(	ab_gp_cycle_ticks_t *	ticks,
		uint32_t *	out_pending )

Returns every pending tick and clears the count, as one critical section (cycle thread side).

Parameters

ticks	instance to take from
out_pending	receives the number of ticks posted since the previous take; 0 when none. Written only when the lock was acquired.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM when ticks or out_pending is NULL; RTE_STATUS_INVALID_STATE before setup or after teardown; otherwise the status of the failed rte_mutex_lock_timed() (the count is then unchanged) or of the failed rte_mutex_unlock() (the count is then already taken and cleared)

Definition at line 57 of file ab_gp_cycle_ticks.c.

ab_gp_cycle_ticks_teardown()

rte_status_t ab_gp_cycle_ticks_teardown

(

ab_gp_cycle_ticks_t *

ticks

)

Destroys the mutex. Call only when no other task can post or take any more (the posting timer is destroyed). The instance is not set up afterwards, whatever the result.

Parameters

ticks

instance to tear down

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM when ticks is NULL; RTE_STATUS_INVALID_STATE when it is not set up; otherwise the status of rte_mutex_destroy()

Definition at line 83 of file ab_gp_cycle_ticks.c.