QP/C  7.0.0
Real-Time Embedded Framework
qf_pkg.h File Reference

Internal (package scope) QF/C interface. More...

Go to the source code of this file.

Data Structures

struct  QFreeBlock
 

Macros

#define QF_CRIT_STAT_
 
#define QF_CRIT_E_()   QF_CRIT_ENTRY(dummy)
 
#define QF_CRIT_X_()   QF_CRIT_EXIT(dummy)
 
#define Q_ASSERT_CRIT_(id_, test_)
 
#define Q_REQUIRE_CRIT_(id_, test_)   Q_ASSERT_CRIT_((id_), (test_))
 
#define Q_ERROR_CRIT_(id_)
 
#define QTE_IS_LINKED   (1U << 7U)
 
#define QTE_WAS_DISARMED   (1U << 6U)
 
#define QTE_TICK_RATE   0x0FU
 
#define QF_EVT_CONST_CAST_(e_)   ((QEvt *)(e_))
 
#define QF_EVT_REF_CTR_INC_(e_)   (++QF_EVT_CONST_CAST_(e_)->refCtr_)
 
#define QF_EVT_REF_CTR_DEC_(e_)   (--QF_EVT_CONST_CAST_(e_)->refCtr_)
 
#define QF_PTR_AT_(base_, i_)   ((base_)[(i_)])
 
#define QF_PTR_RANGE_(x_, min_, max_)   (((min_) <= (x_)) && ((x_) <= (max_)))
 

Functions

void QActive_start_ (QActive *const me, uint_fast8_t prio, QEvt const **const qSto, uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize, void const *const par)
 

Variables

QF_EPOOL_TYPE_ QF_pool_ [QF_MAX_EPOOL]
 
uint_fast8_t QF_maxPool_
 
QSubscrListQF_subscrList_
 
enum_t QF_maxPubSignal_
 

Detailed Description

Date
Last updated on: 2021-12-23
Version
Last updated for: Version 7.0.0, 2022-04-30

Definition in file qf_pkg.h.


Data Structure Documentation

◆ QFreeBlock

struct QFreeBlock

structure representing a free block in the Native QF Memory Pool.

Definition at line 167 of file qf_pkg.h.

Data Fields
struct QFreeBlock *volatile next

Macro Definition Documentation

◆ QF_CRIT_STAT_

#define QF_CRIT_STAT_

This is an internal macro for defining the critical section status type.

The purpose of this macro is to enable writing the same code for the case when critical section status type is defined and when it is not. If the macro QF_CRIT_STAT_TYPE is defined, this internal macro provides the definition of the critical section status variable. Otherwise this macro is empty.

See also
QF_CRIT_STAT_TYPE

Definition at line 54 of file qf_pkg.h.

◆ QF_CRIT_E_

#define QF_CRIT_E_ ( )    QF_CRIT_ENTRY(dummy)

This is an internal macro for entering a critical section.

The purpose of this macro is to enable writing the same code for the case when critical section status type is defined and when it is not. If the macro QF_CRIT_STAT_TYPE is defined, this internal macro invokes QF_CRIT_ENTRY() passing the key variable as the parameter. Otherwise QF_CRIT_ENTRY() is invoked with a dummy parameter.

See also
QF_CRIT_ENTRY()

Definition at line 66 of file qf_pkg.h.

◆ QF_CRIT_X_

#define QF_CRIT_X_ ( )    QF_CRIT_EXIT(dummy)

This is an internal macro for exiting a critical section.

The purpose of this macro is to enable writing the same code for the case when critical section status type is defined and when it is not. If the macro QF_CRIT_STAT_TYPE is defined, this internal macro invokes QF_CRIT_EXIT passing the key variable as the parameter. Otherwise QF_CRIT_EXIT is invoked with a dummy parameter.

See also
QF_CRIT_EXIT

Definition at line 78 of file qf_pkg.h.

◆ Q_ASSERT_CRIT_

#define Q_ASSERT_CRIT_ (   id_,
  test_ 
)
Value:
do { \
if ((test_)) {} else { \
QF_CRIT_X_(); \
Q_onAssert(&Q_this_module_[0], (int_t)(id_)); \
} \
} while (false)
signed int int_t
Definition: qep.h:57

Definition at line 97 of file qf_pkg.h.

◆ Q_REQUIRE_CRIT_

#define Q_REQUIRE_CRIT_ (   id_,
  test_ 
)    Q_ASSERT_CRIT_((id_), (test_))

Definition at line 104 of file qf_pkg.h.

◆ Q_ERROR_CRIT_

#define Q_ERROR_CRIT_ (   id_)
Value:
do { \
QF_CRIT_X_(); \
Q_onAssert(&Q_this_module_[0], (int_t)(id_)); \
} while (false)

Definition at line 106 of file qf_pkg.h.

◆ QTE_IS_LINKED

#define QTE_IS_LINKED   (1U << 7U)

Definition at line 157 of file qf_pkg.h.

◆ QTE_WAS_DISARMED

#define QTE_WAS_DISARMED   (1U << 6U)

Definition at line 158 of file qf_pkg.h.

◆ QTE_TICK_RATE

#define QTE_TICK_RATE   0x0FU

Definition at line 159 of file qf_pkg.h.

◆ QF_EVT_CONST_CAST_

#define QF_EVT_CONST_CAST_ (   e_)    ((QEvt *)(e_))

helper macro to cast const away from an event pointer e_

Definition at line 174 of file qf_pkg.h.

◆ QF_EVT_REF_CTR_INC_

#define QF_EVT_REF_CTR_INC_ (   e_)    (++QF_EVT_CONST_CAST_(e_)->refCtr_)

increment the refCtr of an event e_ casting const away

Definition at line 177 of file qf_pkg.h.

◆ QF_EVT_REF_CTR_DEC_

#define QF_EVT_REF_CTR_DEC_ (   e_)    (--QF_EVT_CONST_CAST_(e_)->refCtr_)

decrement the refCtr of an event e_ casting const away

Definition at line 180 of file qf_pkg.h.

◆ QF_PTR_AT_

#define QF_PTR_AT_ (   base_,
  i_ 
)    ((base_)[(i_)])

access element at index i_ from the base pointer base_

Definition at line 183 of file qf_pkg.h.

◆ QF_PTR_RANGE_

#define QF_PTR_RANGE_ (   x_,
  min_,
  max_ 
)    (((min_) <= (x_)) && ((x_) <= (max_)))

This macro is specifically and exclusively used for checking the range of a block pointer returned to the pool. Such a check must rely on the pointer arithmetic not compliant with the MISRA-C 2012 Rule 18.3(R). Defining a specific macro for this purpose allows to selectively disable the warnings for this particular case.

Definition at line 193 of file qf_pkg.h.

Function Documentation

◆ QActive_start_()

void QActive_start_ ( QActive *const  me,
uint_fast8_t  prio,
QEvt const **const  qSto,
uint_fast16_t const  qLen,
void *const  stkSto,
uint_fast16_t const  stkSize,
void const *const  par 
)

Prototype of the internal active object start implementation

Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.

Parameters
[in,out]mepointer (see oop)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (must be NULL in QK)
[in]stkSizestack size [bytes]
[in]parpointer to an extra parameter (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
#include "qpc.h"
int main() {
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the Board Support Package */
. . .
/* instantiate and start the active objects... */
Blinky_ctor();
static QEvt const *l_blinkyQSto[10]; /* Event queue storage for Blinky */
QACTIVE_START(AO_Blinky, /* AO pointer to start */
1U, /* unique QP priority of the AO */
l_blinkyQSto, /* storage for the AO's queue */
Q_DIM(l_blinkyQSto), /* lenght of the queue [entries] */
(void *)0, /* stack storage (not used in QK) */
0U, /* stack size [bytes] (not used in QK) */
(void *)0); /* initialization parameter (or 0) */
. . .
return QF_run(); /* run the QF application */
}
#define Q_DEFINE_THIS_FILE
Definition: qassert.h:87
#define Q_DIM(array_)
Definition: qassert.h:307
#define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_)
Definition: qf.h:206
QP/C public interface including backwards-compatibility layer.
Definition: qep.h:119
int_t QF_run(void)
Definition: qk.c:124
void QF_init(void)
Definition: qk.c:64

Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.

Parameters
[in,out]mepointer (see oop)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (must be NULL in QV)
[in]stkSizestack size [bytes]
[in]parpointer to an extra parameter (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
#include "qpc.h"
int main() {
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the Board Support Package */
. . .
/* instantiate and start the active objects... */
Blinky_ctor();
static QEvt const *l_blinkyQSto[10]; /* Event queue storage for Blinky */
QACTIVE_START(AO_Blinky, /* AO pointer to start */
1U, /* unique QP priority of the AO */
l_blinkyQSto, /* storage for the AO's queue */
Q_DIM(l_blinkyQSto), /* lenght of the queue [entries] */
(void *)0, /* stack storage (not used in QK) */
0U, /* stack size [bytes] (not used in QK) */
(void *)0); /* initialization parameter (or 0) */
. . .
return QF_run(); /* run the QF application */
}

Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.

Parameters
[in,out]mepointer (see oop)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (used only when per-AO stack is needed)
[in]stkSizestack size [bytes]
[in]parpointer to an extra parameter (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
#include "qpc.h"
int main() {
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the Board Support Package */
. . .
/* instantiate and start the active objects... */
Blinky_ctor();
static QEvt const *l_blinkyQSto[10]; /* Event queue storage for Blinky */
QACTIVE_START(AO_Blinky, /* AO pointer to start */
1U, /* unique QP priority of the AO */
l_blinkyQSto, /* storage for the AO's queue */
Q_DIM(l_blinkyQSto), /* lenght of the queue [entries] */
(void *)0, /* stack storage (not used in QK) */
0U, /* stack size [bytes] (not used in QK) */
(void *)0); /* initialization parameter (or 0) */
. . .
return QF_run(); /* run the QF application */
}
Precondition
AO cannot be started from an ISR, the priority must be in range and the stack storage must not be provided, because the QK kernel does not need per-AO stacks.
The priority must be in range and the stack storage must not be provided, because the QV kernel does not need per-AO stacks.
AO cannot be started:
  • from an ISR;
  • the priority must be in range;
  • the stack storage must NOT be provided (because the QK kernel does not need per-AO stacks).

Definition at line 166 of file qk.c.

Variable Documentation

◆ QF_pool_

QF_EPOOL_TYPE_ QF_pool_[QF_MAX_EPOOL]
extern

allocate event pools

Definition at line 47 of file qf_dyn.c.

◆ QF_maxPool_

uint_fast8_t QF_maxPool_
extern

of initialized event pools

Definition at line 48 of file qf_dyn.c.

◆ QF_subscrList_

QSubscrList* QF_subscrList_
extern

the subscriber list array

◆ QF_maxPubSignal_

enum_t QF_maxPubSignal_
extern

the maximum published signal