QP/C++  7.0.1
Real-Time Embedded Framework
qs.hpp File Reference

QS/C++ platform-independent public interface. More...

Go to the source code of this file.

Classes

struct  QSrx
 QS software tracing parameters for input (QS-RX) More...
 
class  QS
 QS software tracing facilities for output (QS-TX) More...
 
struct  QSpyId
 QS ID type for applying local filtering. More...
 
class  QHsmDummy
 Dummy HSM class for testing (inherits QP::QHsm) More...
 
class  QActiveDummy
 Dummy Active Object class for testing (inherits QP::QActive) More...
 

Namespaces

namespace  QP
 namespace associated with the QP/C++ framework
 

Macros

#define QS_TIME_PRE_()   (QP::QS::u32_raw_(QP::QS::onGetTime()))
 Internal macro to output time stamp to a QS record. More...
 
#define QS_INIT(arg_)   (QP::QS::onStartup(arg_))
 Initialize the QS facility. More...
 
#define QS_EXIT()   (QP::QS::onCleanup())
 Cleanup the QS facility. More...
 
#define QS_GLB_FILTER(rec_)    (QP::QS::glbFilter_(static_cast<std::int_fast16_t>(rec_)))
 Global Filter ON for a given record type rec_ More...
 
#define QS_LOC_FILTER(qs_id_)    (QP::QS::locFilter_(static_cast<std::int_fast16_t>(qs_id_)))
 Local Filter for a given state machine object qs_id More...
 
#define QS_BEGIN_ID(rec_, qs_id_)
 Begin a user QS record with entering critical section. More...
 
#define QS_END()
 End a QS record with exiting critical section. More...
 
#define QS_BEGIN_NOCRIT(rec_, qs_id_)
 Begin a QS user record without entering critical section. More...
 
#define QS_END_NOCRIT()
 End a QS user record without exiting critical section. More...
 
#define QS_REC_DONE()   (static_cast<void>(0))
 macro to hook up user code when a QS record is produced More...
 
#define QS_GLB_CHECK_(rec_)
 helper macro for checking the global QS filter More...
 
#define QS_LOC_CHECK_(qs_id_)
 helper macro for checking the local QS filter More...
 
#define QS_CRIT_STAT_
 This is an internal macro for defining the critical section status type. More...
 
#define QS_CRIT_E_()   QF_CRIT_ENTRY(dummy)
 This is an internal macro for entering a critical section. More...
 
#define QS_CRIT_X_()   QF_CRIT_EXIT(dummy); QS_REC_DONE()
 This is an internal macro for exiting a critical section. More...
 
#define QS_I8(width_, data_)
 Output formatted std::int8_t to the QS record. More...
 
#define QS_U8(width_, data_)
 Output formatted std::uint8_t to the QS record. More...
 
#define QS_I16(width_, data_)
 Output formatted std::int16_t to the QS record. More...
 
#define QS_U16(width_, data_)
 Output formatted std::uint16_t to the QS record. More...
 
#define QS_I32(width_, data_)
 Output formatted std::int32_t to the QS record. More...
 
#define QS_U32(width_, data_)
 Output formatted std::uint32_t to the QS record. More...
 
#define QS_I64(width_, data_)
 Output formatted std::int64_t to the QS record. More...
 
#define QS_U64(width_, data_)
 Output formatted std::uint64_t to the QS record. More...
 
#define QS_F32(width_, data_)
 Output formatted 32-bit floating point number to the QS record. More...
 
#define QS_F64(width_, data_)
 Output formatted 64-bit floating point number to the QS record. More...
 
#define QS_STR(str_)   (QP::QS::str_fmt_(str_))
 Output formatted zero-terminated ASCII string to the QS record. More...
 
#define QS_MEM(mem_, size_)   (QP::QS::mem_fmt_((mem_), (size_)))
 Output formatted memory block of up to 255 bytes to the QS record. More...
 
#define QS_OBJ(obj_)
 Output formatted object pointer to the QS record. More...
 
#define QS_FUN(fun_)
 Output formatted function pointer to the QS record. More...
 
#define QS_SIG(sig_, obj_)
 Output formatted event signal (of type QP::QSignal) and the state machine object to the user QS record. More...
 
#define QS_SIG_DICTIONARY(sig_, obj_)    (QP::QS::sig_dict_pre_((sig_), (obj_), #sig_))
 Output signal dictionary record. More...
 
#define QS_OBJ_DICTIONARY(obj_)    (QP::QS::obj_dict_pre_((obj_), #obj_))
 Output object dictionary record. More...
 
#define QS_OBJ_ARR_DICTIONARY(obj_, idx_)    (QP::QS::obj_arr_dict_pre_((obj_), (idx_), #obj_))
 Output object-array dictionary record. More...
 
#define QS_FUN_DICTIONARY(fun_)
 Output function dictionary record. More...
 
#define QS_USR_DICTIONARY(rec_)
 Output user QS record dictionary record. More...
 
#define QS_ASSERTION(module_, loc_, delay_)    (QP::QS::assertion_pre_((module_), (loc_), (delay_)))
 Produce the assertion failure trace record. More...
 
#define QF_QS_CRIT_ENTRY()   (QP::QS::crit_entry_pre_())
 Output the critical section entry record. More...
 
#define QF_QS_CRIT_EXIT()   (QP::QS::crit_exit_pre_())
 Output the critical section exit record. More...
 
#define QF_QS_ISR_ENTRY(isrnest_, prio_)    (QP::QS::isr_entry_pre_((isrnest_), (prio_)))
 Output the interrupt entry record. More...
 
#define QF_QS_ISR_EXIT(isrnest_, prio_)    (QP::QS::isr_exit_pre_((isrnest_), (prio_)))
 Output the interrupt exit record. More...
 
#define QS_FLUSH()   (QP::QS::onFlush())
 Flush the QS trace data to the host. More...
 
#define QF_QS_ACTION(act_)   (act_)
 Execute an action that is only necessary for QS output. More...
 
#define QS_OUTPUT()   (QS_output())
 macro to handle the QS output from the application NOTE: if this macro is used, the application must define QS_output(). More...
 
#define QS_RX_INPUT()   (QS_rx_input())
 macro to handle the QS-RX input to the application NOTE: if this macro is used, the application must define QS_rx_input(). More...
 
#define QS_TEST_PROBE_DEF(fun_)
 QS macro to define the Test-Probe for a given fun_. More...
 
#define QS_TEST_PROBE(code_)    if (qs_tp_ != 0U) { code_ }
 QS macro to apply a Test-Probe. More...
 
#define QS_TEST_PROBE_ID(id_, code_)    if (qs_tp_ == static_cast<std::uint32_t>(id_)) { code_ }
 QS macro to apply a Test-Probe. More...
 
#define QS_TEST_PAUSE()   (QP::QS::test_pause_())
 QS macro to pause test execution and enter the test event loop. More...
 

Typedefs

using QSTimeCtr = std::uint32_t
 The type of the QS time stamp. This type determines the dynamic. More...
 
using QSCtr = std::uint_fast16_t
 QS ring buffer counter and offset type. More...
 

Enumerations

enum  QSpyRecords : std::int8_t {
  QS_EMPTY , QS_QEP_STATE_ENTRY , QS_QEP_STATE_EXIT , QS_QEP_STATE_INIT ,
  QS_QEP_INIT_TRAN , QS_QEP_INTERN_TRAN , QS_QEP_TRAN , QS_QEP_IGNORED ,
  QS_QEP_DISPATCH , QS_QEP_UNHANDLED , QS_QF_ACTIVE_DEFER , QS_QF_ACTIVE_RECALL ,
  QS_QF_ACTIVE_SUBSCRIBE , QS_QF_ACTIVE_UNSUBSCRIBE , QS_QF_ACTIVE_POST , QS_QF_ACTIVE_POST_LIFO ,
  QS_QF_ACTIVE_GET , QS_QF_ACTIVE_GET_LAST , QS_QF_ACTIVE_RECALL_ATTEMPT , QS_QF_EQUEUE_POST ,
  QS_QF_EQUEUE_POST_LIFO , QS_QF_EQUEUE_GET , QS_QF_EQUEUE_GET_LAST , QS_QF_NEW_ATTEMPT ,
  QS_QF_MPOOL_GET , QS_QF_MPOOL_PUT , QS_QF_PUBLISH , QS_QF_NEW_REF ,
  QS_QF_NEW , QS_QF_GC_ATTEMPT , QS_QF_GC , QS_QF_TICK ,
  QS_QF_TIMEEVT_ARM , QS_QF_TIMEEVT_AUTO_DISARM , QS_QF_TIMEEVT_DISARM_ATTEMPT , QS_QF_TIMEEVT_DISARM ,
  QS_QF_TIMEEVT_REARM , QS_QF_TIMEEVT_POST , QS_QF_DELETE_REF , QS_QF_CRIT_ENTRY ,
  QS_QF_CRIT_EXIT , QS_QF_ISR_ENTRY , QS_QF_ISR_EXIT , QS_QF_INT_DISABLE ,
  QS_QF_INT_ENABLE , QS_QF_ACTIVE_POST_ATTEMPT , QS_QF_EQUEUE_POST_ATTEMPT , QS_QF_MPOOL_GET_ATTEMPT ,
  QS_MUTEX_LOCK , QS_MUTEX_UNLOCK , QS_SCHED_LOCK , QS_SCHED_UNLOCK ,
  QS_SCHED_NEXT , QS_SCHED_IDLE , QS_SCHED_RESUME , QS_QEP_TRAN_HIST ,
  QS_QEP_TRAN_EP , QS_QEP_TRAN_XP , QS_TEST_PAUSED , QS_TEST_PROBE_GET ,
  QS_SIG_DICT , QS_OBJ_DICT , QS_FUN_DICT , QS_USR_DICT ,
  QS_TARGET_INFO , QS_TARGET_DONE , QS_RX_STATUS , QS_QUERY_DATA ,
  QS_PEEK_DATA , QS_ASSERT_FAIL , QS_QF_RUN
}
 QS pre-defined record types (TX channel) More...
 
enum  QSpyUserOffsets : std::int16_t {
  QS_USER = 100 , QS_USER0 = QS_USER , QS_USER1 = QS_USER0 + 5 , QS_USER2 = QS_USER1 + 5 ,
  QS_USER3 = QS_USER2 + 5 , QS_USER4 = QS_USER3 + 5
}
 QS user record group offsets for QS_GLB_FILTER() More...
 
enum  QSpyRecordGroups : std::int16_t {
  QS_ALL_RECORDS = static_cast<std::uint8_t>(0xF0U) , QS_SM_RECORDS , QS_AO_RECORDS , QS_EQ_RECORDS ,
  QS_MP_RECORDS , QS_TE_RECORDS , QS_QF_RECORDS , QS_SC_RECORDS ,
  QS_U0_RECORDS , QS_U1_RECORDS , QS_U2_RECORDS , QS_U3_RECORDS ,
  QS_U4_RECORDS , QS_UA_RECORDS
}
 QS record groups for QS_GLB_FILTER() More...
 
enum  QSpyIdOffsets : std::int16_t { QS_AO_ID = 0 , QS_EP_ID = 64 , QS_EQ_ID = 80 , QS_AP_ID = 96 }
 QS ID offsets for QS_LOC_FILTER() More...
 
enum  QSpyIdGroups : std::int16_t {
  QS_ALL_IDS = 0xF0 , QS_AO_IDS = 0x80 + QS_AO_ID , QS_EP_IDS = 0x80 + QS_EP_ID , QS_EQ_IDS = 0x80 + QS_EQ_ID ,
  QS_AP_IDS = 0x80 + QS_AP_ID
}
 QS ID groups for QS_LOC_FILTER() More...
 

Variables

constexpr std::uint16_t QS_EOD = 0xFFFFU
 Constant representing End-Of-Data condition returned from the QP::QS::getByte() function. More...
 
constexpr std::uint8_t QUTEST_ON_POST {124U}
 
std::uint8_t volatile QF_intNest
 

Detailed Description

Date
Last updated on: 2022-06-15
Version
Last updated for: Version 7.0.1, 2022-06-30 (planned)

Definition in file qs.hpp.


Class Documentation

◆ QP::QSrx

struct QP::QSrx

Definition at line 57 of file qs.hpp.

Class Members
void * currObj[8] current objects
uint8_t * buf pointer to the start of the ring buffer
QSCtr end offset of the end of the ring buffer
QSCtr volatile head offset to where next byte will be inserted
QSCtr volatile tail offset of where next byte will be extracted
QPSet readySet QUTEST ready-set of active objects.
bool inTestLoop QUTest event loop is running.

Macro Definition Documentation

◆ QS_TIME_PRE_

#define QS_TIME_PRE_ ( )    (QP::QS::u32_raw_(QP::QS::onGetTime()))

Definition at line 748 of file qs.hpp.

◆ QS_INIT

#define QS_INIT (   arg_)    (QP::QS::onStartup(arg_))
Description
This macro provides an indirection layer to invoke the QS initialization routine if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.
See also
QP::QS::onStartup(), example of setting up a QS filter in QS_GLB_FILTER()

Definition at line 851 of file qs.hpp.

◆ QS_EXIT

#define QS_EXIT ( )    (QP::QS::onCleanup())
Description
This macro provides an indirection layer to invoke the QS cleanup routine if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.
See also
QP::QS::onCleanup()

Definition at line 859 of file qs.hpp.

◆ QS_GLB_FILTER

#define QS_GLB_FILTER (   rec_)     (QP::QS::glbFilter_(static_cast<std::int_fast16_t>(rec_)))
Description
This macro provides an indirection layer to call QP::QS::filterOn() if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.
See also
Usage
The following example shows how to use QS filters:
int main(int arc, char *argv[]) {
. . .
if (!QS_INIT(argv)) { // Initialize QS target component
return -1; // Unable to initialize QSpy
}
// apply the global QS filters...
// NOTE: global filters start as being all OFF
QS_GLB_FILTER(QP::QS_QF_RECORDS); // turn QF-group ON
QS_GLB_FILTER(-QP::QS_QF_TICK); // turn #QS_QF_TICK OFF
// apply the local QS filters...
// NOTE: local filters start as being all ON
QS_LOC_FILTER(-QP::QS_EP_IDS); // turn EP (Event-Pool) group OFF
QS_LOC_FILTER(3); // turn AO with priority 3 ON
// start the active objects...
. . .
// NOTE: the following will work only after AO_Table has been started
QS_LOC_FILTER(-AO_Table->prio); // turn AO_Table OFF
. . .
}
@ QS_QF_TICK
QP::QF::tickX() was called.
Definition: qs.hpp:616
@ QS_EP_IDS
event-pool IDs
Definition: qs.hpp:714
@ QS_QF_RECORDS
QF QS records.
Definition: qs.hpp:692
#define QS_LOC_FILTER(qs_id_)
Local Filter for a given state machine object qs_id
Definition: qs.hpp:888
#define QS_GLB_FILTER(rec_)
Global Filter ON for a given record type rec_
Definition: qs.hpp:874
#define QS_INIT(arg_)
Initialize the QS facility.
Definition: qs.hpp:851

Definition at line 874 of file qs.hpp.

◆ QS_LOC_FILTER

#define QS_LOC_FILTER (   qs_id_)     (QP::QS::locFilter_(static_cast<std::int_fast16_t>(qs_id_)))
Description
This macro provides an indirection layer to call QS_locFilter_() if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.
See also

The following example shows how to use QS filters:

int main(int arc, char *argv[]) {
. . .
if (!QS_INIT(argv)) { // Initialize QS target component
return -1; // Unable to initialize QSpy
}
// apply the global QS filters...
// NOTE: global filters start as being all OFF
QS_GLB_FILTER(QP::QS_QF_RECORDS); // turn QF-group ON
QS_GLB_FILTER(-QP::QS_QF_TICK); // turn #QS_QF_TICK OFF
// apply the local QS filters...
// NOTE: local filters start as being all ON
QS_LOC_FILTER(-QP::QS_EP_IDS); // turn EP (Event-Pool) group OFF
QS_LOC_FILTER(3); // turn AO with priority 3 ON
// start the active objects...
. . .
// NOTE: the following will work only after AO_Table has been started
QS_LOC_FILTER(-AO_Table->prio); // turn AO_Table OFF
. . .
}

Definition at line 888 of file qs.hpp.

◆ QS_BEGIN_ID

#define QS_BEGIN_ID (   rec_,
  qs_id_ 
)
Value:
if (QS_GLB_CHECK_(rec_) && QS_LOC_CHECK_(qs_id_)) { \
QP::QS::beginRec_(static_cast<std::uint_fast8_t>(rec_)); \
QS_TIME_PRE_();
static void beginRec_(std::uint_fast8_t const rec) noexcept
Mark the begin of a QS record rec
Definition: qs.cpp:350
#define QS_CRIT_E_()
This is an internal macro for entering a critical section.
Definition: qs.hpp:989
#define QS_LOC_CHECK_(qs_id_)
helper macro for checking the local QS filter
Definition: qs.hpp:944
#define QS_GLB_CHECK_(rec_)
helper macro for checking the global QS filter
Definition: qs.hpp:937
Description
The following example shows how to build a user QS record using the macros QS_BEGIN_ID(), QS_END(), and the formatted output macros: QS_U8(), QS_STR(), etc.
Note
Must always be used in pair with QS_END()
#ifdef Q_SPY
enum {
PHILO_STAT = QP::QS_USER
};
. . .
#endif
void BSP_displayPhilStat(uint8_t n, char const *stat) {
. . .
// application-specific record
QS_BEGIN_ID(PHILO_STAT, AO_Philo[n]->m_prio)
QS_U8(1, n); // Philosopher number
QS_STR(stat); // Philosopher status
}
@ QS_USER
the first record available to QS users
Definition: qs.hpp:676
#define QS_U8(width_, data_)
Output formatted std::uint8_t to the QS record.
Definition: qs.hpp:1020
#define QS_END()
End a QS record with exiting critical section.
Definition: qs.hpp:915
#define QS_BEGIN_ID(rec_, qs_id_)
Begin a user QS record with entering critical section.
Definition: qs.hpp:905
#define QS_STR(str_)
Output formatted zero-terminated ASCII string to the QS record.
Definition: qs.hpp:1073

Definition at line 905 of file qs.hpp.

◆ QS_END

#define QS_END ( )
Value:
QS_CRIT_X_(); \
}
static void endRec_(void) noexcept
Mark the end of a QS record rec
Definition: qs.cpp:370
See also
example for QS_BEGIN_ID()
Note
Must always be used in pair with QS_BEGIN_ID()

Definition at line 915 of file qs.hpp.

◆ QS_BEGIN_NOCRIT

#define QS_BEGIN_NOCRIT (   rec_,
  qs_id_ 
)
Value:
if (QS_GLB_CHECK_(rec_) && QS_LOC_CHECK_(qs_id_)) { \
QS_TIME_PRE_();

Definition at line 921 of file qs.hpp.

◆ QS_END_NOCRIT

#define QS_END_NOCRIT ( )
Value:

Definition at line 927 of file qs.hpp.

◆ QS_REC_DONE

#define QS_REC_DONE ( )    (static_cast<void>(0))

Definition at line 933 of file qs.hpp.

◆ QS_GLB_CHECK_

#define QS_GLB_CHECK_ (   rec_)
Value:
((static_cast<std::uint_fast8_t>(QP::QS::priv_.glbFilter[ \
static_cast<std::uint_fast8_t>(rec_) >> 3U]) \
& (static_cast<std::uint_fast8_t>(1U) \
<< (static_cast<std::uint_fast8_t>(rec_) & 7U))) != 0U)
static QS priv_
Definition: qs.hpp:552
std::uint8_t glbFilter[16]
global on/off QS filter
Definition: qs.hpp:539

Definition at line 937 of file qs.hpp.

◆ QS_LOC_CHECK_

#define QS_LOC_CHECK_ (   qs_id_)
Value:
((static_cast<std::uint_fast8_t>(QP::QS::priv_.locFilter \
[static_cast<std::uint_fast8_t>(qs_id_) >> 3U]) \
& (static_cast<std::uint_fast8_t>(1U) \
<< (static_cast<std::uint_fast8_t>(qs_id_) & 7U))) != 0U)
std::uint8_t locFilter[16]
local on/off QS filter
Definition: qs.hpp:540

Definition at line 944 of file qs.hpp.

◆ QS_CRIT_STAT_

#define QS_CRIT_STAT_
Description
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 978 of file qs.hpp.

◆ QS_CRIT_E_

#define QS_CRIT_E_ ( )    QF_CRIT_ENTRY(dummy)
Description
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 989 of file qs.hpp.

◆ QS_CRIT_X_

#define QS_CRIT_X_ ( )    QF_CRIT_EXIT(dummy); QS_REC_DONE()
Description
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 1000 of file qs.hpp.

◆ QS_I8

#define QS_I8 (   width_,
  data_ 
)
Value:
(QP::QS::u8_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::I8_T)), (data_)))
static void u8_fmt_(std::uint8_t const format, std::uint8_t const d) noexcept
Output std::uint8_t data element with format information.
Definition: qs.cpp:511
@ I8_T
signed 8-bit integer format
Definition: qs.hpp:494

Definition at line 1014 of file qs.hpp.

◆ QS_U8

#define QS_U8 (   width_,
  data_ 
)
Value:
(QP::QS::u8_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::U8_T)), (data_)))
@ U8_T
unsigned 8-bit integer format
Definition: qs.hpp:495

Definition at line 1020 of file qs.hpp.

◆ QS_I16

#define QS_I16 (   width_,
  data_ 
)
Value:
(QP::QS::u16_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::I16_T)), (data_)))
@ I16_T
signed 16-bit integer format
Definition: qs.hpp:496
static void u16_fmt_(std::uint8_t format, std::uint16_t d) noexcept
output std::uint16_t data element with format information
Definition: qs.cpp:527

Definition at line 1026 of file qs.hpp.

◆ QS_U16

#define QS_U16 (   width_,
  data_ 
)
Value:
(QP::QS::u16_fmt_(static_cast<std::uint8_t>((((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::U16_T)), (data_)))
@ U16_T
unsigned 16-bit integer format
Definition: qs.hpp:497

Definition at line 1032 of file qs.hpp.

◆ QS_I32

#define QS_I32 (   width_,
  data_ 
)
Value:
static_cast<std::uint8_t>((static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::I32_T)), (data_)))
static void u32_fmt_(std::uint8_t format, std::uint32_t d) noexcept
Output std::uint32_t data element with format information.
Definition: qs.cpp:549
@ I32_T
signed 32-bit integer format
Definition: qs.hpp:498

Definition at line 1037 of file qs.hpp.

◆ QS_U32

#define QS_U32 (   width_,
  data_ 
)
Value:
(QP::QS::u32_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::U32_T)), (data_)))
@ U32_T
unsigned 32-bit integer format
Definition: qs.hpp:499

Definition at line 1043 of file qs.hpp.

◆ QS_I64

#define QS_I64 (   width_,
  data_ 
)
Value:
(QP::QS::u64_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::I64_T)), (data_)))
static void u64_fmt_(std::uint8_t format, std::uint64_t d) noexcept
Output uint64_t data element with format information.
Definition: qs_64bit.cpp:62
@ I64_T
signed 64-bit integer format
Definition: qs.hpp:507

Definition at line 1049 of file qs.hpp.

◆ QS_U64

#define QS_U64 (   width_,
  data_ 
)
Value:
(QP::QS::u64_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::U64_T)), (data_)))
@ U64_T
unsigned 64-bit integer format
Definition: qs.hpp:508

Definition at line 1055 of file qs.hpp.

◆ QS_F32

#define QS_F32 (   width_,
  data_ 
)
Value:
(QP::QS::f32_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::F32_T)), (data_)))
static void f32_fmt_(std::uint8_t format, float32_t const d) noexcept
Output 32-bit floating point data element with format information.
Definition: qs_fp.cpp:41
@ F32_T
32-bit floating point format
Definition: qs.hpp:500

Definition at line 1061 of file qs.hpp.

◆ QS_F64

#define QS_F64 (   width_,
  data_ 
)
Value:
(QP::QS::f64_fmt_(static_cast<std::uint8_t>( \
(static_cast<std::uint8_t>((width_) << 4)) \
| static_cast<std::uint8_t>(QP::QS::F64_T)), (data_)))
static void f64_fmt_(std::uint8_t format, float64_t const d) noexcept
Output 64-bit floating point data element with format information.
Definition: qs_fp.cpp:70
@ F64_T
64-bit floating point format
Definition: qs.hpp:501

Definition at line 1067 of file qs.hpp.

◆ QS_STR

#define QS_STR (   str_)    (QP::QS::str_fmt_(str_))

Definition at line 1073 of file qs.hpp.

◆ QS_MEM

#define QS_MEM (   mem_,
  size_ 
)    (QP::QS::mem_fmt_((mem_), (size_)))

Definition at line 1076 of file qs.hpp.

◆ QS_OBJ

#define QS_OBJ (   obj_)
Value:
reinterpret_cast<std::uint32_t>(obj_)))
@ OBJ_T
object pointer format
Definition: qs.hpp:505

Definition at line 1093 of file qs.hpp.

◆ QS_FUN

#define QS_FUN (   fun_)
Value:
reinterpret_cast<std::uint32_t>(fun_)))
@ FUN_T
function pointer format
Definition: qs.hpp:506

Definition at line 1112 of file qs.hpp.

◆ QS_SIG

#define QS_SIG (   sig_,
  obj_ 
)
Value:
QP::QS::u16_fmt_(QP::QS::SIG_T, static_cast<std::uint16_t>(sig_)); \
static void obj_raw_(void const *const obj) noexcept
Output obj pointer data element without format information.
Definition: qs.cpp:705
@ SIG_T
event signal format
Definition: qs.hpp:504

Definition at line 1132 of file qs.hpp.

◆ QS_SIG_DICTIONARY

#define QS_SIG_DICTIONARY (   sig_,
  obj_ 
)     (QP::QS::sig_dict_pre_((sig_), (obj_), #sig_))
Description
A signal dictionary record associates the numerical value of the signal and the binary address of the state machine that consumes that signal with the human-readable name of the signal.

Providing a signal dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable names.

A signal dictionary entry is associated with both the signal value sig_ and the state machine obj_, because signals are required to be unique only within a given state machine and therefore the same numerical values can represent different signals in different state machines.

For the "global" signals that have the same meaning in all state machines (such as globally published signals), you can specify a signal dictionary entry with the obj_ parameter set to NULL.

The following example shows the definition of signal dictionary entries in the initial transition of the Table active object. Please note that signals HUNGRY_SIG and DONE_SIG are associated with the Table state machine only ("me" obj_ pointer). The EAT_SIG signal, on the other hand, is global (0 obj_ pointer):

Table Table::inst;
Q_STATE_DEF(Table, initial) {
QS_OBJ_DICTIONARY(&Table::inst);
QS_FUN_DICTIONARY(&Table::initial);
QS_FUN_DICTIONARY(&Table::active);
QS_FUN_DICTIONARY(&Table::serving);
QS_FUN_DICTIONARY(&Table::paused);
QS_SIG_DICTIONARY(DONE_SIG, nullptr); // global signals
QS_SIG_DICTIONARY(EAT_SIG, nullptr);
QS_SIG_DICTIONARY(PAUSE_SIG, nullptr);
QS_SIG_DICTIONARY(TERMINATE_SIG, nullptr);
QS_SIG_DICTIONARY(HUNGRY_SIG, this); // signal just for Table
. . .
}
static QState top(void *const me, QEvt const *const e) noexcept
The top-state handler.
Definition: qep_hsm.cpp:185
#define Q_STATE_DEF(subclass_, state_)
Macro to generate a definition of a state-handler for a given state in a subclass of QP::QHsm.
Definition: qep.hpp:811
#define QS_OBJ_DICTIONARY(obj_)
Output object dictionary record.
Definition: qs.hpp:1194
#define QS_FUN_DICTIONARY(fun_)
Output function dictionary record.
Definition: qs.hpp:1226
#define QS_SIG_DICTIONARY(sig_, obj_)
Output signal dictionary record.
Definition: qs.hpp:1178
Note
The QSpy log utility must capture the signal dictionary record in order to use the human-readable information. You need to connect to the target before the dictionary entries have been transmitted.

The following QSpy log example shows the signal dictionary records generated from the Table initial transition and subsequent records that show human-readable names of the signals:

qspy -fqs.bin -S2 -Q2 -P4 -p4 -T4
QSpy 4.0.00
Thu Apr 06 09:56:10 2005
-f qs.bin
-S 2
-Q 2
-P 4
-p 4
-T 4
. . . . . .
Obj Dic: 00419048->table
EQ.INIT: Obj=00419050 Len= 5
0000000000 AO.ADD : Active=table Prio=51
Fun Dic: 00401CEE->Table_serving
Sig Dic: 00000004,Obj=00419048 ->HUNGRY_SIG
Sig Dic: 00000005,Obj=00419048 ->DONE_SIG
Sig Dic: 00000006,Obj=00000000 ->EAT_SIG
0000000000 AO.SUB : Active=table Sig=HUNGRY_SIG
0000000000 AO.SUB : Active=table Sig=DONE_SIG
0000000000 AO.SUB : Active=table Sig=00000007,Obj=00419048
Q_INIT : Obj=table Source=00403CE0 Target=Table_serving
0000000000 ==>Init: Obj=table New=Table_serving
. . . . . .
// the Philosophers become hungry...
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
Queue(nUsed= 1, nMax= 1)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
Queue(nUsed= 2, nMax= 2)
Q_ENTRY: Obj=philo[2] State=Philosopher_hungry
0000000007 AO.GET : Active= table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
Queue(nUsed= 2)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
Queue(nUsed= 2, nMax= 3)
Q_ENTRY: Obj=philo[4] State=Philosopher_hungry
Q_ENTRY: Obj=philo[1] State=Philosopher_hungry
Q_ENTRY: Obj=philo[3] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[2] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[4] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[3] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[1] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
Q_ENTRY: Obj=philo[0] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[0] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
// user record output
0000000007 User070: 2 hungry
// Table grants permissions to eat
0000000007 NEW : Evt(Sig=EAT_SIG, size= 6)
0000000007 MP.GET : Obj=00418E18 nFree= 5 nMin= 5
0000000007 AO.FIFO: Obj=philo[4] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[3] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[2] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[1] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[0] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 PUBLISH: Evt(Sig=EAT_SIG, Pool=1, Ref= 5) nSubsr= 5
0000000007 AO.GETL: Active= philo[4] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[2] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[3] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[1] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[0] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
. . . . . .
#define PUBLISH(e_, sender_)
Invoke the event publishing facility QP::QF::publish_().
Definition: qf.hpp:1435

The following QSpy log example shows the same sequence of records, but with dictionary records removed. The human-readable signal names are not available.

qspy -fqs0.bin -S2 -Q2 -P4 -p4 -T4
QSpy 4.0.00
Thu Apr 06 10:10:22 2005
-f qs0.bin
-S 2
-Q 2
-P 4
-p 4
-T 4
. . . . . .
Obj Dic: 00419048->table
EQ.INIT: Obj=00419050 Len= 5
0000000000 AO.ADD : Active=table Prio=51
// the signal dictionary entries removed from the binary QS log
*** Dropped 4 records
0000000000 AO.SUB : Active=table Sig=00000004,Obj=00419048
0000000000 AO.SUB : Active=table Sig=00000005,Obj=00419048
0000000000 AO.SUB : Active=table Sig=00000007,Obj=00419048
Q_INIT : Obj=table Source=00403CE0 Target=00403CE0
0000000000 ==>Init: Obj=table New=00401CEE
. . . . . .
// the Philosophers become hungry...
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
Queue(nUsed= 1, nMax= 1)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
Queue(nUsed= 2, nMax= 2)
Q_ENTRY: Obj=philo[2] State=Philosopher_hungry
0000000007 AO.GET : Active= table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
Queue(nUsed= 2)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
Queue(nUsed= 2, nMax= 3)
Q_ENTRY: Obj=philo[4] State=Philosopher_hungry
Q_ENTRY: Obj=philo[1] State=Philosopher_hungry
Q_ENTRY: Obj=philo[3] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[2] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[4] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[3] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[1] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
Q_ENTRY: Obj=philo[0] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[0] Sig=TIMEOUT_SIG Source=Philosopher_thinking
New=Philosopher_hungry
// user record output
0000000007 User070: 2 hungry
// Table grants permissions to eat
0000000007 NEW : Evt(Sig=00000006,Obj=00000000, size= 6)
0000000007 MP.GET : Obj=00418E18 nFree= 5 nMin= 5
0000000007 AO.FIFO: Obj=philo[4] Evt(Sig=00000006,Obj=00419000, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[3] Evt(Sig=00000006,Obj=00418FBC, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[2] Evt(Sig=00000006,Obj=00418F78, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[1] Evt(Sig=00000006,Obj=00418F34, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 AO.FIFO: Obj=philo[0] Evt(Sig=00000006,Obj=00418EF0, Pool=1, Ref= 0)
Queue(nUsed= 0, nMax= 0)
0000000007 PUBLISH: Evt(Sig=00000006,Obj=00000000, Pool=1, Ref= 5) nSubsr= 5
0000000007 AO.GETL: Active= philo[4] Evt(Sig=00000006,Obj=00419000, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[2] Evt(Sig=00000006,Obj=00418F78, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[3] Evt(Sig=00000006,Obj=00418FBC, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[1] Evt(Sig=00000006,Obj=00418F34, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[0] Evt(Sig=00000006,Obj=00418EF0, Pool=1, Ref= 5)
. . . . . .

Definition at line 1178 of file qs.hpp.

◆ QS_OBJ_DICTIONARY

#define QS_OBJ_DICTIONARY (   obj_)     (QP::QS::obj_dict_pre_((obj_), #obj_))
Description
An object dictionary record associates the binary address of an object in the target's memory with the human-readable name of the object.

Providing an object dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable object names.

The following example shows the definition of object dictionary entry for the Table active object:

Table Table::inst;
Q_STATE_DEF(Table, initial) {
QS_OBJ_DICTIONARY(&Table::inst);
QS_FUN_DICTIONARY(&Table::initial);
QS_FUN_DICTIONARY(&Table::active);
QS_FUN_DICTIONARY(&Table::serving);
QS_FUN_DICTIONARY(&Table::paused);
QS_SIG_DICTIONARY(DONE_SIG, nullptr); // global signals
QS_SIG_DICTIONARY(EAT_SIG, nullptr);
QS_SIG_DICTIONARY(PAUSE_SIG, nullptr);
QS_SIG_DICTIONARY(TERMINATE_SIG, nullptr);
QS_SIG_DICTIONARY(HUNGRY_SIG, this); // signal just for Table
. . .
}

Definition at line 1194 of file qs.hpp.

◆ QS_OBJ_ARR_DICTIONARY

#define QS_OBJ_ARR_DICTIONARY (   obj_,
  idx_ 
)     (QP::QS::obj_arr_dict_pre_((obj_), (idx_), #obj_))
Description
An object array dictionary record associates the binary address of the object element in the target's memory with the human-readable name of the object.

Providing a dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable object names.

The following example shows the definition of object array dictionary for Philo::inst[n] and Philo::inst[n].m_timeEvt:

Definition at line 1211 of file qs.hpp.

◆ QS_FUN_DICTIONARY

#define QS_FUN_DICTIONARY (   fun_)
Value:
QP::QS::force_cast<void (*)(void)>(fun_), #fun_))
static T_OUT force_cast(T_IN in)
template for forcing cast of member functions for function dictionaries and test probes.
Definition: qs.hpp:530
static void fun_dict_pre_(void(*const fun)(void), char const *const name) noexcept
Output function dictionary record.
Definition: qs.cpp:895
Description
A function dictionary record associates the binary address of a function in the target's memory with the human-readable name of the function.

Providing a function dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable function names.

The example from QS_SIG_DICTIONARY shows the definition of a function dictionary.

Definition at line 1226 of file qs.hpp.

◆ QS_USR_DICTIONARY

#define QS_USR_DICTIONARY (   rec_)
Value:
do { \
static char const usr_name_[] = #rec_; \
QP::QS::usr_dict_pre_((rec_), &usr_name_[0]); \
} while (false)
static void usr_dict_pre_(enum_t const rec, char const *const name) noexcept
Output user dictionary record.
Definition: qs.cpp:569
Description
A user QS record dictionary record associates the numerical value of a user record with the human-readable identifier.

Definition at line 1235 of file qs.hpp.

◆ QS_ASSERTION

#define QS_ASSERTION (   module_,
  loc_,
  delay_ 
)     (QP::QS::assertion_pre_((module_), (loc_), (delay_)))

Definition at line 1241 of file qs.hpp.

◆ QF_QS_CRIT_ENTRY

#define QF_QS_CRIT_ENTRY ( )    (QP::QS::crit_entry_pre_())

Definition at line 1245 of file qs.hpp.

◆ QF_QS_CRIT_EXIT

#define QF_QS_CRIT_EXIT ( )    (QP::QS::crit_exit_pre_())

Definition at line 1248 of file qs.hpp.

◆ QF_QS_ISR_ENTRY

#define QF_QS_ISR_ENTRY (   isrnest_,
  prio_ 
)     (QP::QS::isr_entry_pre_((isrnest_), (prio_)))

Definition at line 1251 of file qs.hpp.

◆ QF_QS_ISR_EXIT

#define QF_QS_ISR_EXIT (   isrnest_,
  prio_ 
)     (QP::QS::isr_exit_pre_((isrnest_), (prio_)))

Definition at line 1255 of file qs.hpp.

◆ QS_FLUSH

#define QS_FLUSH ( )    (QP::QS::onFlush())
Description
This macro invokes the QP::QS::flush() platform-dependent callback function to flush the QS trace buffer to the host. The function typically busy-waits until all the data in the buffer is sent to the host. This is acceptable only in the initial transient.

Definition at line 1265 of file qs.hpp.

◆ QF_QS_ACTION

#define QF_QS_ACTION (   act_)    (act_)

Definition at line 1268 of file qs.hpp.

◆ QS_OUTPUT

#define QS_OUTPUT ( )    (QS_output())

Definition at line 1272 of file qs.hpp.

◆ QS_RX_INPUT

#define QS_RX_INPUT ( )    (QS_rx_input())

Definition at line 1276 of file qs.hpp.

◆ QS_TEST_PROBE_DEF

#define QS_TEST_PROBE_DEF (   fun_)
Value:
std::uint32_t const qs_tp_ = \
static std::uint32_t getTestProbe_(void(*const api)(void)) noexcept
internal function to get the Test-Probe for a given API
Definition: qs_rx.cpp:723

Definition at line 1283 of file qs.hpp.

◆ QS_TEST_PROBE

#define QS_TEST_PROBE (   code_)     if (qs_tp_ != 0U) { code_ }

Definition at line 1288 of file qs.hpp.

◆ QS_TEST_PROBE_ID

#define QS_TEST_PROBE_ID (   id_,
  code_ 
)     if (qs_tp_ == static_cast<std::uint32_t>(id_)) { code_ }

Definition at line 1292 of file qs.hpp.

◆ QS_TEST_PAUSE

#define QS_TEST_PAUSE ( )    (QP::QS::test_pause_())

Definition at line 1296 of file qs.hpp.