QP/C  7.3.3
Real-Time Embedded Framework
Loading...
Searching...
No Matches
qxk.h File Reference

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

Go to the source code of this file.

Classes

class  QXK
 QXK dual-mode kernel (QXK namespace emulated as a "class" in C) More...
 
class  QXK_Attr
 Private attributes of the QXK kernel. 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 of the QXK preemptive kernel. More...
 

Macros

#define QXTHREAD_NO_TIMEOUT   ((QTimeEvtCtr)0)
 
#define QXTHREAD_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
 
#define QXTHREAD_POST_X(me_, e_, margin_, sender_)    QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))
 
#define QF_SCHED_STAT_   QSchedStatus lockStat_;
 
#define QF_SCHED_LOCK_(ceil_)
 
#define QF_SCHED_UNLOCK_()
 
#define QACTIVE_EQUEUE_WAIT_(me_)    Q_ASSERT_INCRIT(310, (me_)->eQueue.frontEvt != (QEvt *)0)
 
#define QACTIVE_EQUEUE_SIGNAL_(me_)
 
#define QXTHREAD_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_, qsId_)    ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qsId_)))
 
#define QF_EPOOL_PUT_(p_, e_, qsId_)    (QMPool_put(&(p_), (e_), (qsId_)))
 

Typedefs

typedef uint_fast16_t QSchedStatus
 

Enumerations

enum  QXK_TimeoutSigs { QXK_DELAY_SIG = 1 , QXK_TIMEOUT_SIG }
 

Detailed Description

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

Traceability

Definition in file qxk.h.

Macro Definition Documentation

◆ QXTHREAD_NO_TIMEOUT

#define QXTHREAD_NO_TIMEOUT   ((QTimeEvtCtr)0)

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

Definition at line 66 of file qxk.h.

◆ QXTHREAD_START

#define QXTHREAD_START (   me_,
  prioSpec_,
  qSto_,
  qLen_,
  stkSto_,
  stkSize_,
  par_ 
)
Value:
QACTIVE_START((me_), (prioSpec_), (qSto_), (qLen_), \
(stkSto_), (stkSize_), (par_))
#define QACTIVE_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition qp.h:1197

Start an extended thread

Description
Starts execution of the thread and registers the AO with the framework.
Parameters
[in,out]me_current instance pointer (see oop)
[in]prioSpec_QF priority of the extended thread
[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).
Traceability
Usage
#include "qpc.h"
int main() {
QF_init(); // initialize the framework
BSP_init(); // initialize the Board Support Package
// initialize publish-subscribe...
QActive_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
}
#define Q_DIM(array_)
Definition qp.h:535
QP/C interface including the backwards-compatibility layer.
int_t QF_run(void)
Definition qutest.c:191
void QF_init(void)
Definition qutest.c:172
#define QXTHREAD_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition qxk.h:273

Definition at line 273 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

Description
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.
Traceability
Usage
extern QXThread * const XT_Test;
. . .
// 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;
QXTHREAD_POST_X(XT_Test, &pe->super, 3U, me); // <===
}
. . .
#define Q_NEW_X(evtT_, margin_, sig_,...)
Definition qp.h:1181
#define QXTHREAD_POST_X(me_, e_, margin_, sender_)
Definition qxk.h:277
eXtended (blocking) thread of the QXK preemptive kernel
Definition qxk.h:145

Definition at line 277 of file qxk.h.

◆ QF_SCHED_STAT_

#define QF_SCHED_STAT_   QSchedStatus lockStat_;

Definition at line 288 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)
#define QXK_ISR_CONTEXT_()
Check if the code executes in the ISR context.
Definition qp_port.h:131

Definition at line 291 of file qxk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (lockStat_ != 0xFFU) { \
QXK_schedUnlock(lockStat_); \
} \
} while (false)

Definition at line 300 of file qxk.h.

◆ QACTIVE_EQUEUE_WAIT_

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

Definition at line 307 of file qxk.h.

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ (   me_)
Value:
do { \
QPSet_insert(&QXK_priv_.readySet, (uint_fast8_t)(me_)->prio); \
QPSet_update_(&QXK_priv_.readySet, &QXK_priv_.readySet_dis); \
if (!QXK_ISR_CONTEXT_()) { \
if (QXK_sched_() != 0U) { \
QXK_activate_(); \
} \
} \
} while (false)

Definition at line 312 of file qxk.h.

◆ QXTHREAD_EQUEUE_SIGNAL_

#define QXTHREAD_EQUEUE_SIGNAL_ (   me_)
Value:
do { \
if (me->super.temp.obj == QXK_PTR_CAST_(QMState*, &me->eQueue)) { \
(void)QXThread_teDisarm_(QXTHREAD_CAST_(me)); \
QPSet_insert(&QXK_priv_.readySet, (uint_fast8_t)me->prio); \
QPSet_update_(&QXK_priv_.readySet, &QXK_priv_.readySet_dis); \
if (!QXK_ISR_CONTEXT_()) { \
(void)QXK_sched_(); \
} \
} \
} while (false)
#define QXTHREAD_CAST_(ptr_)
Definition qxk.h:366
#define QXK_PTR_CAST_(type_, ptr_)
Definition qxk.h:363
State object for the QMsm class (QM State Machine).
Definition qp.h:239

Definition at line 337 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

Description
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-C:2023-Rule 11.3(R) 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.
Traceability

Definition at line 363 of file qxk.h.

◆ QXTHREAD_CAST_

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

Internal macro to encapsulate casting of pointers for MISRA deviations

Description
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-C:2023 Rule 11.3(R) 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.
Traceability

Definition at line 366 of file qxk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_   QMPool

Definition at line 372 of file qxk.h.

◆ QF_EPOOL_INIT_

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

Definition at line 375 of file qxk.h.

◆ QF_EPOOL_EVENT_SIZE_

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

Definition at line 379 of file qxk.h.

◆ QF_EPOOL_GET_

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

Definition at line 382 of file qxk.h.

◆ QF_EPOOL_PUT_

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

Definition at line 386 of file qxk.h.

Typedef Documentation

◆ QSchedStatus

typedef uint_fast16_t QSchedStatus

Definition at line 60 of file qxk.h.

Enumeration Type Documentation

◆ QXK_TimeoutSigs

Enumerator
QXK_DELAY_SIG 
QXK_TIMEOUT_SIG 

Definition at line 390 of file qxk.h.