QTools  7.4.0
Collection of Host-Based Tools
Loading...
Searching...
No Matches
qspy.h
Go to the documentation of this file.
1/*============================================================================
2* QTools Collection
3*
4* Q u a n t u m L e a P s
5* ------------------------
6* Modern Embedded Software
7*
8* Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
9*
10* SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
11*
12* This software is dual-licensed under the terms of the open source GNU
13* General Public License version 3 (or any later version), or alternatively,
14* under the terms of one of the closed source Quantum Leaps commercial
15* licenses.
16*
17* The terms of the open source GNU General Public License version 3
18* can be found at: <www.gnu.org/licenses/gpl-3.0>
19*
20* The terms of the closed source Quantum Leaps commercial licenses
21* can be found at: <www.state-machine.com/licensing>
22*
23* Redistributions in source code must retain this top-level comment block.
24* Plagiarizing this software to sidestep the license obligations is illegal.
25*
26* Contact information:
27* <www.state-machine.com>
28* <info@state-machine.com>
29============================================================================*/
30/*!
31* @date Last updated on: 2024-06-21
32* @version Last updated for version: 7.4.0
33*
34* @file
35* @brief Host API
36*/
37#ifndef QSPY_H_
38#define QSPY_H_
39
40#define QSPY_VER "7.4.0"
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/*! low-level facilities for configuring QSpy and parsing QS records ...*/
51
52/*! typedef for inclusion of qpc_qs.h */
53typedef uint16_t QSignal;
54
55/*! QSPY record being processed */
56typedef struct {
57 uint8_t const *start; /*!< start of the record */
58 uint8_t const *pos; /*!< current position in the stream */
59 uint32_t tot_len; /*!< total length of the record, including chksum */
60 int32_t len; /*!< current length of the stream */
61 uint8_t rec; /*!< the record-ID (see enum QSpyRecords in qs.h) */
63
64/* limits */
65enum {
66 QS_RECORD_SIZE_MAX = 512, /* max QS record size [bytes] */
67 QS_LINE_LEN_MAX = 1000, /* max length of a QSPY line [chars] */
68 QS_FNAME_LEN_MAX = 256, /* max length of filenames [chars] */
69 QS_SEQ_LIST_LEN_MAX = 300, /* max length of the Seq list [chars] */
70 QS_DNAME_LEN_MAX = 64, /* max dictionary name length [chars] */
71};
72
73/* pointer to the callback function for customized QS record parsing */
74typedef int (*QSPY_CustParseFun)(QSpyRecord * const me);
75typedef void (*QSPY_resetFun)(void);
76
77void QSpyRecord_init (QSpyRecord * const me,
78 uint8_t const *start, uint32_t tot_len);
80uint32_t QSpyRecord_getUint32(QSpyRecord * const me, uint8_t size);
81int32_t QSpyRecord_getInt32 (QSpyRecord * const me, uint8_t size);
82uint64_t QSpyRecord_getUint64(QSpyRecord * const me, uint8_t size);
83int64_t QSpyRecord_getInt64 (QSpyRecord * const me, uint8_t size);
84char const *QSpyRecord_getStr (QSpyRecord * const me);
85uint8_t const *QSpyRecord_getMem(QSpyRecord * const me,
86 uint8_t size,
87 uint32_t *pNum);
88
89/* QSPY configuration and high-level interface .............................*/
90/*! QSPY configuration parameters. @sa QSPY_config() */
91typedef struct {
92 uint16_t version;
93 uint8_t endianness;
94 uint8_t objPtrSize;
95 uint8_t funPtrSize;
96 uint8_t tstampSize;
97 uint8_t sigSize;
98 uint8_t evtSize;
99 uint8_t queueCtrSize;
100 uint8_t poolCtrSize;
101 uint8_t poolBlkSize;
102 uint8_t tevtCtrSize;
103 uint8_t tstamp[6];
104} QSpyConfig;
105
106typedef uint64_t KeyType;
107typedef uint32_t SigType;
108typedef uint64_t ObjType;
109
110void QSPY_config(QSpyConfig const *config,
111 QSPY_CustParseFun custParseFun);
113void QSPY_configMatFile(void *matFile);
114
115void QSPY_reset(void);
116void QSPY_parse(uint8_t const *buf, uint32_t nBytes);
117void QSPY_txReset(void);
118
119/* command options */
120enum {
124};
125bool QSPY_command(uint8_t cmdId, uint8_t opt);
126
127void QSPY_sendEvt(QSpyRecord const * const qrec);
128void QSPY_sendObj(QSpyRecord const * const qrec);
129void QSPY_sendCmd(QSpyRecord const * const qrec);
130void QSPY_sendTP (QSpyRecord const * const qrec);
131void QSPY_showNote(QSpyRecord const * const qrec);
132
133uint32_t QSPY_encode(uint8_t *dstBuf, uint32_t dstSize,
134 uint8_t const *srcBuf, uint32_t srcBytes);
135uint32_t QSPY_encodeResetCmd(uint8_t *dstBuf, uint32_t dstSize);
136uint32_t QSPY_encodeInfoCmd (uint8_t *dstBuf, uint32_t dstSize);
137uint32_t QSPY_encodeTickCmd (uint8_t *dstBuf, uint32_t dstSize, uint8_t rate);
138
139SigType QSPY_findSig(char const *name, ObjType obj);
140KeyType QSPY_findObj(char const *name);
141KeyType QSPY_findFun(char const *name);
142KeyType QSPY_findUsr(char const *name);
143KeyType QSPY_findEnum(char const *name, uint8_t group);
144
145#define SIG_NOT_FOUND ((SigType)-1)
146#define KEY_NOT_FOUND ((KeyType)-1)
147
148void QSPY_cleanup(void); /* cleanup after the run */
149
150char const* QSPY_tstampStr(void);
151
152void QSPY_onPrintLn(void); /* callback to print the last line of output */
153
154/* prints information message to the QSPY output (without sending it to FE) */
155void QSPY_printInfo(void);
156
157/* prints error message to the QSPY output (sending it to FE) */
159
160/* last human-readable line of output from QSPY ............................*/
161#define QS_LINE_OFFSET 8
163 /* output forwarded to the back-end... */
164 REG_OUT, /* regular output from the Target */
165 ERR_OUT, /* error output from QSPY */
166 /* ... */
167 BE_OUT, /* last message forwarded to the back-end */
168
169 /* output NOT forwarded to the back-end... */
170 INF_OUT, /* internal info from QSPY */
171 USR_OUT, /* generic user message from BE */
172 TST_OUT, /* test message from BE */
173};
174typedef struct {
176 int len; /* the length of the composed string */
177 int rec; /* the corresponding QS record ID */
178 int type; /* the type of the output */
179 int rx_status; /* the type of the RX status */
181
198
199/* returns the "group" of a given QS record-ID */
201
202/* last output generated */
204
205/* beginning of QSPY line to print */
206extern char const * const QSPY_line;
207
208#define SNPRINTF_LINE(format_, ...) do { \
209 int n_ = SNPRINTF_S(&QSPY_output.buf[QS_LINE_OFFSET], \
210 (QS_LINE_LEN_MAX - QS_LINE_OFFSET), \
211 format_, __VA_ARGS__); \
212 if ((0 < n_) && (n_ < QS_LINE_LEN_MAX - QS_LINE_OFFSET)) { \
213 QSPY_output.len = n_; \
214 } \
215 else { \
216 QSPY_output.len = QS_LINE_LEN_MAX - QS_LINE_OFFSET; \
217 } \
218} while (0)
219
220#define SNPRINTF_APPEND(format_, ...) do { \
221 int n_ = SNPRINTF_S(&QSPY_output.buf[QS_LINE_OFFSET + QSPY_output.len],\
222 (QS_LINE_LEN_MAX - QS_LINE_OFFSET - QSPY_output.len), \
223 format_, __VA_ARGS__); \
224 if ((0 < n_) \
225 && (n_ < QS_LINE_LEN_MAX - QS_LINE_OFFSET - QSPY_output.len)) { \
226 QSPY_output.len += n_; \
227 } \
228 else { \
229 QSPY_output.len = QS_LINE_LEN_MAX - QS_LINE_OFFSET; \
230 } \
231} while (0)
232
233#define CONFIG_UPDATE(member_, new_, diff_) \
234 if (QSPY_conf.member_ != (new_)) { \
235 QSPY_conf.member_ = (new_); \
236 (diff_) = 1U; \
237 } else (void)0
238
239/* Dictionaries ............................................................*/
240typedef struct {
243} DictEntry;
244
252
254 DictEntry* sto, uint32_t capacity);
255void Dictionary_config(Dictionary* const me, int keySize);
256char const* Dictionary_at(Dictionary* const me, unsigned idx);
257void Dictionary_put(Dictionary* const me, KeyType key, char const* name);
258char const* Dictionary_get(Dictionary* const me, KeyType key, char* buf);
260KeyType Dictionary_findKey(Dictionary* const me, char const* name);
262
263typedef struct {
268
276
278 SigDictEntry* sto, uint32_t capacity);
279void SigDictionary_config(SigDictionary* const me, int ptrSize);
281 SigType sig, ObjType obj, char const* name);
282char const* SigDictionary_get(SigDictionary* const me,
283 SigType sig, ObjType obj, char* buf);
285 SigType sig, ObjType obj);
287 char const* name, ObjType obj);
290
291/*==========================================================================*/
292/* facilities used by the QSPY host app only (but not for QSPY parser) */
293#ifdef QSPY_APP
294
295/*! commands to QSPY; @sa "packet IDs" in qutest.py or qview.py scripts */
296typedef enum {
297 QSPY_ATTACH = 128, /*!< attach to the QSPY Back-End */
298 QSPY_DETACH, /*!< detach from the QSPY Back-End */
299 QSPY_SAVE_DICT, /*!< save dictionaries to a file in QSPY */
300 QSPY_TEXT_OUT, /*!< toggle text output to a file in QSPY */
301 QSPY_BIN_OUT, /*!< toggle binary output to a file in QSPY */
302 QSPY_MATLAB_OUT, /*!< toggle Matlab output to a file in QSPY */
303 QSPY_SEQUENCE_OUT, /*!< toggle Sequence output to a file in QSPY */
304 QSPY_SEND_EVENT, /*!< send event (QSPY supplying signal) */
305 QSPY_SEND_AO_FILTER, /*!< send Local Filter (QSPY supplying addr) */
306 QSPY_SEND_CURR_OBJ, /*!< send current Object (QSPY supplying addr) */
307 QSPY_SEND_COMMAND, /*!< send command (QSPY supplying cmdId) */
308 QSPY_SEND_TEST_PROBE, /*!< send Test-Probe (QSPY supplying apiId) */
309 QSPY_CLEAR_SCREEN, /*!< clear the QSPY screen */
310 QSPY_SHOW_NOTE, /*!< show a note in QSPY output */
311 /* ... */
312} QSpyCommands;
313
314extern QSpyConfig QSPY_conf;
315extern Dictionary QSPY_funDict;
316extern Dictionary QSPY_objDict;
317extern Dictionary QSPY_usrDict;
318extern SigDictionary QSPY_sigDict;
319extern Dictionary QSPY_enumDict[8];
320
321void QSPY_setExternDict(char const* dictName);
322QSpyStatus QSPY_readDict(void);
323QSpyStatus QSPY_writeDict(void);
324
325bool QDIC_isActive(void);
326
327void Dictionary_write(Dictionary const* const me, FILE* stream);
328bool Dictionary_read(Dictionary* const me, FILE* stream);
329
330void SigDictionary_write(SigDictionary const* const me, FILE* stream);
331bool SigDictionary_read(SigDictionary* const me, FILE* stream);
332char const* QSPY_getMatDict(char const* s);
333
334void QSEQ_configFile(void *seqFile);
335bool QSEQ_isActive(void);
336void QSEQ_config(void* seqFile, char const* seqList);
337void QSEQ_updateDictionary(char const* name, KeyType key);
338int QSEQ_find(KeyType key);
339void QSEQ_genHeader(void);
340void QSEQ_genPost(uint32_t tstamp, int src, int dst, char const* sig,
341 bool isAttempt);
342void QSEQ_genPostLIFO(uint32_t tstamp, int src, char const* sig);
343void QSEQ_genTran(uint32_t tstamp, int obj, char const* state);
344void QSEQ_genPublish(uint32_t tstamp, int obj, char const* sig);
345void QSEQ_genAnnotation(uint32_t tstamp, int obj, char const* ann);
346void QSEQ_genTick(uint32_t rate, uint32_t nTick);
347void QSEQ_dictionaryReset(void);
348
349#endif /* QSPY_APP */
350
351#ifdef __cplusplus
352}
353#endif
354
355#endif /* QSPY_H_ */
QSpyStatus
Definition qspy.h:47
@ QSPY_SUCCESS
Definition qspy.h:49
@ QSPY_ERROR
Definition qspy.h:48
void Dictionary_config(Dictionary *const me, int keySize)
@ QS_SEQ_LIST_LEN_MAX
Definition qspy.h:69
@ QS_RECORD_SIZE_MAX
Definition qspy.h:66
@ QS_DNAME_LEN_MAX
Definition qspy.h:70
@ QS_FNAME_LEN_MAX
Definition qspy.h:68
@ QS_LINE_LEN_MAX
Definition qspy.h:67
void QSPY_sendTP(QSpyRecord const *const qrec)
SigType QSPY_findSig(char const *name, ObjType obj)
void SigDictionary_reset(SigDictionary *const me)
void Dictionary_ctor(Dictionary *const me, DictEntry *sto, uint32_t capacity)
char const * Dictionary_at(Dictionary *const me, unsigned idx)
int32_t QSpyRecord_getInt32(QSpyRecord *const me, uint8_t size)
QSpyStatus QSpyRecord_OK(QSpyRecord *const me)
void QSPY_resetAllDictionaries(void)
uint32_t QSpyRecord_getUint32(QSpyRecord *const me, uint8_t size)
uint64_t KeyType
Definition qspy.h:106
uint32_t QSPY_encodeResetCmd(uint8_t *dstBuf, uint32_t dstSize)
uint64_t QSpyRecord_getUint64(QSpyRecord *const me, uint8_t size)
uint32_t SigType
Definition qspy.h:107
int64_t QSpyRecord_getInt64(QSpyRecord *const me, uint8_t size)
int SigDictionary_find(SigDictionary *const me, SigType sig, ObjType obj)
int(* QSPY_CustParseFun)(QSpyRecord *const me)
Definition qspy.h:74
void SigDictionary_ctor(SigDictionary *const me, SigDictEntry *sto, uint32_t capacity)
QSPY_LastOutputType
Definition qspy.h:162
@ INF_OUT
Definition qspy.h:170
@ BE_OUT
Definition qspy.h:167
@ ERR_OUT
Definition qspy.h:165
@ USR_OUT
Definition qspy.h:171
@ REG_OUT
Definition qspy.h:164
@ TST_OUT
Definition qspy.h:172
char const * Dictionary_get(Dictionary *const me, KeyType key, char *buf)
void QSPY_reset(void)
KeyType Dictionary_findKey(Dictionary *const me, char const *name)
char const * SigDictionary_get(SigDictionary *const me, SigType sig, ObjType obj, char *buf)
void QSPY_sendCmd(QSpyRecord const *const qrec)
void QSPY_cleanup(void)
void SigDictionary_config(SigDictionary *const me, int ptrSize)
char const * QSPY_tstampStr(void)
void QSPY_printInfo(void)
QSPY_LastOutput QSPY_output
QSRreRecGroup
Definition qspy.h:182
@ GRP_MP
Definition qspy.h:190
@ GRP_TST
Definition qspy.h:186
@ GRP_INF
Definition qspy.h:184
@ GRP_TE
Definition qspy.h:191
@ GRP_EQ
Definition qspy.h:189
@ GRP_USR
Definition qspy.h:196
@ GRP_DIC
Definition qspy.h:185
@ GRP_MTX
Definition qspy.h:195
@ GRP_ERR
Definition qspy.h:183
@ GRP_QF
Definition qspy.h:192
@ GRP_SEM
Definition qspy.h:194
@ GRP_AO
Definition qspy.h:188
@ GRP_SM
Definition qspy.h:187
@ GRP_SC
Definition qspy.h:193
char const * QSpyRecord_getStr(QSpyRecord *const me)
void QSPY_sendEvt(QSpyRecord const *const qrec)
void QSPY_parse(uint8_t const *buf, uint32_t nBytes)
char const *const QSPY_line
SigType SigDictionary_findSig(SigDictionary *const me, char const *name, ObjType obj)
void Dictionary_put(Dictionary *const me, KeyType key, char const *name)
void QSPY_configTxReset(QSPY_resetFun txResetFun)
KeyType QSPY_findObj(char const *name)
QSRreRecGroup QSPY_getGroup(int recId)
void QSPY_onPrintLn(void)
uint32_t QSPY_encodeTickCmd(uint8_t *dstBuf, uint32_t dstSize, uint8_t rate)
KeyType QSPY_findEnum(char const *name, uint8_t group)
void QSPY_printError(void)
void QSPY_config(QSpyConfig const *config, QSPY_CustParseFun custParseFun)
void QSPY_showNote(QSpyRecord const *const qrec)
uint64_t ObjType
Definition qspy.h:108
uint32_t QSPY_encodeInfoCmd(uint8_t *dstBuf, uint32_t dstSize)
void QSPY_configMatFile(void *matFile)
uint32_t QSPY_encode(uint8_t *dstBuf, uint32_t dstSize, uint8_t const *srcBuf, uint32_t srcBytes)
int Dictionary_find(Dictionary *const me, KeyType key)
uint8_t const * QSpyRecord_getMem(QSpyRecord *const me, uint8_t size, uint32_t *pNum)
void(* QSPY_resetFun)(void)
Definition qspy.h:75
void QSpyRecord_init(QSpyRecord *const me, uint8_t const *start, uint32_t tot_len)
@ CMD_OPT_OFF
Definition qspy.h:121
@ CMD_OPT_TOGGLE
Definition qspy.h:123
@ CMD_OPT_ON
Definition qspy.h:122
void QSPY_sendObj(QSpyRecord const *const qrec)
#define QS_LINE_OFFSET
Definition qspy.h:161
KeyType QSPY_findFun(char const *name)
void Dictionary_reset(Dictionary *const me)
void QSPY_txReset(void)
bool QSPY_command(uint8_t cmdId, uint8_t opt)
KeyType QSPY_findUsr(char const *name)
uint16_t QSignal
Definition qspy.h:53
void SigDictionary_put(SigDictionary *const me, SigType sig, ObjType obj, char const *name)
Definition qspy.h:240
KeyType key
Definition qspy.h:241
int capacity
Definition qspy.h:248
DictEntry * sto
Definition qspy.h:247
DictEntry notFound
Definition qspy.h:246
int entries
Definition qspy.h:249
int keySize
Definition qspy.h:250
int rx_status
Definition qspy.h:179
uint8_t queueCtrSize
Definition qspy.h:99
uint8_t tevtCtrSize
Definition qspy.h:102
uint8_t evtSize
Definition qspy.h:98
uint8_t tstampSize
Definition qspy.h:96
uint8_t funPtrSize
Definition qspy.h:95
uint16_t version
Definition qspy.h:92
uint8_t poolBlkSize
Definition qspy.h:101
uint8_t objPtrSize
Definition qspy.h:94
uint8_t poolCtrSize
Definition qspy.h:100
uint8_t endianness
Definition qspy.h:93
uint8_t sigSize
Definition qspy.h:97
int32_t len
Definition qspy.h:60
uint8_t const * start
Definition qspy.h:57
uint8_t const * pos
Definition qspy.h:58
uint32_t tot_len
Definition qspy.h:59
uint8_t rec
Definition qspy.h:61
Definition qspy.h:263
SigType sig
Definition qspy.h:264
ObjType obj
Definition qspy.h:265
int capacity
Definition qspy.h:272
SigDictEntry notFound
Definition qspy.h:270
SigDictEntry * sto
Definition qspy.h:271
int entries
Definition qspy.h:273
int ptrSize
Definition qspy.h:274