QXK/C (preemptive dual-mode kernel) platform-independent public interface. More...

#include "qequeue.h"
#include "qmpool.h"
#include "qf.h"

Classes
class	QXK
	The QXK kernel class. More...

class	QXThread
	eXtended (blocking) thread of the QXK preemptive kernel More...

class	QXSemaphore
	Counting Semaphore of the QXK preemptive kernel. More...

class	QXMutex
	Blocking Mutex the QXK preemptive kernel. More...

Macros
#define	QF_EQUEUE_TYPE QEQueue

#define	QF_OS_OBJECT_TYPE void*

#define	QF_THREAD_TYPE void*

#define	QXK_TLS(type_) ((type_)QXK_current()->thread)

#define	QXTHREAD_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)

#define	QXTHREAD_NO_TIMEOUT ((uint_fast16_t)0)

#define	QXTHREAD_POST_X(me_, e_, margin_, sender_) QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))

#define	QXK_ISR_CONTEXT_() (QF_intNest_ != 0U)

#define	QF_SCHED_STAT_ QSchedStatus lockStat_;

#define	QF_SCHED_LOCK_(ceil_)

#define	QF_SCHED_UNLOCK_()

#define	QACTIVE_EQUEUE_WAIT_(me_) (Q_ASSERT_ID(110, (me_)->eQueue.frontEvt != (QEvt *)0))

#define	QACTIVE_EQUEUE_SIGNAL_(me_)

#define	QXK_PTR_CAST_(type_, ptr_) ((type_)(ptr_))

#define	QXTHREAD_CAST_(ptr_) ((QXThread *)(ptr_))

#define	QF_EPOOL_TYPE_ QMPool

#define	QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) (QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))

#define	QF_EPOOL_EVENT_SIZE_(p_) ((uint_fast16_t)(p_).blockSize)

#define	QF_EPOOL_GET_(p_, e_, m_, qs_id_) ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))

#define	QF_EPOOL_PUT_(p_, e_, qs_id_) (QMPool_put(&(p_), (e_), (qs_id_)))

Typedefs
typedef QActiveVtable	QXThreadVtable
	Virtual Table for the QXThread class (inherited from QActiveVtable)

Variables
QXThread const *	QXThread_dummy

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE QEQueue

Definition at line 50 of file qxk.h.

◆ QF_OS_OBJECT_TYPE

#define QF_OS_OBJECT_TYPE void*

Definition at line 55 of file qxk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE void*

Definition at line 58 of file qxk.h.

◆ QXK_TLS

#define QXK_TLS ( type_ ) ((type_)QXK_current()->thread)

Access Thread-Local Storage (TLS) and cast it on the given type_

Definition at line 61 of file qxk.h.

◆ QXTHREAD_START

#define QXTHREAD_START	(	me_,
		prioSpec_,
		qSto_,
		qLen_,
		stkSto_,
		stkSize_,
		par_
	)

Value:

do { \
    Q_ASSERT((me_)->super.super.vptr); \
    ((*((QActiveVtable const *)((me_)->super.super.vptr))->start)( \
        &(me_)->super, (prioSpec_), (QEvt const **)(qSto_), (qLen_), \
        (stkSto_), (stkSize_), (par_))); \
} while (false)

Virtual call to start an extened thread

Starts execution of the thread and registers the AO with the framework.

Parameters

[in,out]	me_	current instance pointer (see oop)
[in]	prioSpec_	priority specification at which to start the extended thread (see QPrioSpec)
[in]	qSto_	pointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]	qLen_	length of the event queue (in events)
[in]	stkSto_	pointer to the stack storage (used only when per-AO stack is needed)
[in]	stkSize_	stack size (in bytes)
[in]	par_	pointer to the additional port-specific parameter(s) (might be NULL).

Usage: #include "qpc.h"

Q_DEFINE_THIS_FILE

int main() {

. . .

QF_init(); /* initialize the framework */

BSP_init(); /* initialize the Board Support Package */

/* initialize publish-subscribe~~~ */

QF_psInit(subscrSto, Q_DIM(subscrSto));

/* initialize event pools~~~ */

QF_poolInit(smlPoolSto, sizeof(smlPoolSto), sizeof(smlPoolSto[0]));

/* start the active objects (basic threads)~~~ */

Table_ctor(); /* instantiate the Table AO */

QACTIVE_START(AO_Table, /* AO to start */

n + 1U, /* QF-priority */

tableQueueSto, /* event queue storage */

Q_DIM(tableQueueSto), /* queue length [events] */

tableStackSto, /* stack storage */

sizeof(tableStackSto), /* stack size [bytes] */

(void *)0); /* initialization param */

. . .

/* start the extended-threads~~~ */

Test_ctor(); /* instantiate the Test extended thread */

QXTHREAD_START(XT_Test, /* Thread to start */

10U, /* QF-priority */

testQueueSto, /* message queue storage */

Q_DIM(testQueueSto), /* message length [events] */

testStackSto, /* stack storage */

sizeof(testStackSto), /* stack size [bytes] */

(void *)0); /* initialization param */

return QF_run(); /* run the QF application */

}

Q_DIM
#define Q_DIM(array_)
Definition: qassert.h:424

QACTIVE_START
#define QACTIVE_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition: qf.h:1907

QF_psInit
static void QF_psInit(QSubscrList *const subscrSto, enum_t const maxSignal)
Definition: qf.h:1482

qpc.h
QP/C public interface including backwards-compatibility layer.

QF_run
int_t QF_run(void)
Definition: qutest.c:190

QF_init
void QF_init(void)
Definition: qutest.c:171

QXTHREAD_START
#define QXTHREAD_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition: qxk.h:934

Definition at line 934 of file qxk.h.

◆ QXTHREAD_NO_TIMEOUT

#define QXTHREAD_NO_TIMEOUT ((uint_fast16_t)0)

No-timeout when blocking on semaphores, mutextes, and queues

Definition at line 944 of file qxk.h.

◆ QXTHREAD_POST_X

#define QXTHREAD_POST_X	(	me_,
		e_,
		margin_,
		sender_
	)	QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))

Asynchronous posting events to the event queue of an eXtended thread

This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.

Parameters

[in,out]	me_	current instance pointer (see oop)
[in]	e_	pointer to the event to post
[in]	margin_	the minimum free slots in the queue, which must still be available after posting the event. The special value QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]	sender_	pointer to the sender object (used in QS tracing)

Returns: 'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free slots available in the queue.

Note: The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QXTHREAD_POST_X() macro does not pass the sender_ parameter, so the overhead of passing this extra argument is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QXTHREAD_POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

Usage: extern QActive * const AO_Table;

. . .

/* typically inside a state machine action */

TableEvt *pe;

Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */

if (pe != (TableEvt *)0) {

pe->philNum = me->num;

QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* <--- */

}

. . .

Q_NEW_X
#define Q_NEW_X(e_, evtT_, margin_, sig_,...)
Definition: qf.h:1834

QACTIVE_POST_X
#define QACTIVE_POST_X(me_, e_, margin_, sender_)
Definition: qf.h:1988

QActive
Active object class (based on the QHsm implementation strategy)
Definition: qf.h:372

Definition at line 979 of file qxk.h.

◆ QXK_ISR_CONTEXT_

#define QXK_ISR_CONTEXT_ ( ) (QF_intNest_ != 0U)

Internal macro that reports the execution context (ISR vs. thread)

Returns: true if the code executes in the ISR context and false otherwise

Definition at line 996 of file qxk.h.

◆ QF_SCHED_STAT_

#define QF_SCHED_STAT_ QSchedStatus lockStat_;

QXK scheduler lock status

Definition at line 1001 of file qxk.h.

◆ QF_SCHED_LOCK_

#define QF_SCHED_LOCK_ ( ceil_ )

Value:

    do { \
    if (QXK_ISR_CONTEXT_()) { \
        lockStat_ = 0xFFU; \
    } else { \
        lockStat_ = QXK_schedLock((ceil_)); \
    } \
} while (false)

QXK selective scheduler locking

Definition at line 1005 of file qxk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )

Value:

    do { \
    if (lockStat_ != 0xFFU) { \
        QXK_schedUnlock(lockStat_); \
    } \
} while (false)

QXK selective scheduler unlocking

Definition at line 1015 of file qxk.h.

◆ QACTIVE_EQUEUE_WAIT_

#define QACTIVE_EQUEUE_WAIT_ ( me_ ) (Q_ASSERT_ID(110, (me_)->eQueue.frontEvt != (QEvt *)0))

QXK native event queue waiting

Definition at line 1023 of file qxk.h.

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ ( me_ )

Value:

    do { \
    QPSet_insert(&QF_readySet_, (uint_fast8_t)(me_)->prio); \
    if (!QXK_ISR_CONTEXT_()) { \
        if (QXK_sched_() != 0U) { \
            QXK_activate_(); \
        } \
    } \
} while (false)

QXK native event queue signaling

Definition at line 1028 of file qxk.h.

◆ QXK_PTR_CAST_

#define QXK_PTR_CAST_	(	type_,
		ptr_
	)	((type_)(ptr_))

internal macro to encapsulate casting of pointers for MISRA deviations

This macro is specifically and exclusively used for casting pointers that are never de-referenced, but only used for internal bookkeeping and checking (via assertions) the correct operation of the QXK kernel. Such pointer casting is not compliant with MISRA-2012-Rule 11.3(req) as well as other messages (e.g., PC-Lint-Plus warning 826). Defining this specific macro for this purpose allows to selectively disable the warnings for this particular case.

Definition at line 1049 of file qxk.h.

◆ QXTHREAD_CAST_

#define QXTHREAD_CAST_ ( ptr_ ) ((QXThread *)(ptr_))

internal macro to encapsulate casting of pointers for MISRA deviations

This macro is specifically and exclusively used for downcasting pointers to QActive to pointers to QXThread in situations when it is known that such downcasting is correct.However, such pointer casting is not compliant with MISRA-2012-Rule 11.3(req) as well as other messages (e.g., PC-Lint-Plus warning 826). Defining this specific macro for this purpose allows to selectively disable the warnings for this particular case.

Definition at line 1062 of file qxk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_ QMPool

Definition at line 1090 of file qxk.h.

◆ QF_EPOOL_INIT_

#define QF_EPOOL_INIT_	(	p_,
		poolSto_,
		poolSize_,
		evtSize_
	)	(QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))

Definition at line 1093 of file qxk.h.

◆ QF_EPOOL_EVENT_SIZE_

#define QF_EPOOL_EVENT_SIZE_ ( p_ ) ((uint_fast16_t)(p_).blockSize)

Definition at line 1097 of file qxk.h.

◆ QF_EPOOL_GET_

#define QF_EPOOL_GET_	(	p_,
		e_,
		m_,
		qs_id_
	)	((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))

Definition at line 1100 of file qxk.h.

◆ QF_EPOOL_PUT_

#define QF_EPOOL_PUT_	(	p_,
		e_,
		qs_id_
	)	(QMPool_put(&(p_), (e_), (qs_id_)))

Definition at line 1104 of file qxk.h.

Typedef Documentation

◆ QXThreadVtable

typedef QActiveVtable QXThreadVtable

Note: QXThread inherits QActive without adding any new virtual functions and therefore, QXThreadVtable is typedef'ed as QActiveVtable.

Definition at line 595 of file qxk.h.

Variable Documentation

◆ QXThread_dummy

QXThread const* QXThread_dummy

extern

dummy static to force generation of "struct QXThread"

Classes

Macros

Typedefs

Variables

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

◆ QF_OS_OBJECT_TYPE

◆ QF_THREAD_TYPE

◆ QXK_TLS

◆ QXTHREAD_START

◆ QXTHREAD_NO_TIMEOUT

◆ QXTHREAD_POST_X

◆ QXK_ISR_CONTEXT_

◆ QF_SCHED_STAT_

◆ QF_SCHED_LOCK_

◆ QF_SCHED_UNLOCK_

◆ QACTIVE_EQUEUE_WAIT_

◆ QACTIVE_EQUEUE_SIGNAL_

◆ QXK_PTR_CAST_

◆ QXTHREAD_CAST_

◆ QF_EPOOL_TYPE_

◆ QF_EPOOL_INIT_

◆ QF_EPOOL_EVENT_SIZE_

◆ QF_EPOOL_GET_

◆ QF_EPOOL_PUT_

Typedef Documentation

◆ QXThreadVtable

Variable Documentation

◆ QXThread_dummy