Understanding the Trice code

[rokath]

@Sazerac4 asked:

I read the source code and I have some questions :

• In the differences of the macros trice8, trice16, trice32 and trice64. Their activation depends on the maximum size of the arguments that we want: TRICE_DEFAULT_PARAMETER_BIT_WIDTH. But when writing to the buffer, data must always be format to fit a 32 bit size?

• What is the purprose to always put data in a 32bits format ? (target or memeory alignement ? )

• I understand the syntax of macros and the feature attached to them but not the full uppercase one :

#define trice8(tid, fmt, ...)   // Log (no timestamp)
#define Trice8(tid, fmt, ...)  // Log (16 bits timestamp)
#define TRice8(tid, fmt, ...)  // Log (32 bits timestamp)
//
#define TRICE8(tid, fmt, ...)  // What is the purpose of this kind of macros ?

• When i read this macros (trice8.h:93). I think tid is unused. it is right guess ?

//! TRICE8_0 writes trice data as fast as possible in a buffer.
//! \param tid is a 16 bit Trice id in upper 2 bytes of a 32 bit value
#define TRICE8_0(tid, pFmt) \
	TRICE_ENTER tid;        \
	TRICE_CNTC(0);          \
	TRICE_LEAVE

[rokath]

In the differences of the macros trice8, trice16, trice32 and trice64. Their activation depends on the maximum size of the arguments that we want: TRICE_DEFAULT_PARAMETER_BIT_WIDTH. But when writing to the buffer, data must always be format to fit a 32 bit size?

The macros trice8, trice16, trice32 and trice64 are always usable and the number 8, 16, 32, 64 specifies the parameter width. They are partially disabled, when the value TRICE_SINGLE_MAX_SIZE is defined to be smaller than 104. That's mainly to get compiler errors rather than runtime errors. The value TRICE_DEFAULT_PARAMETER_BIT_WIDTH is the parameter bit with for the macro trice (without number). It can make sense to set this value to 16 on smaller machines.

What is the purprose to always put data in a 32bits format ? (target or memeory alignement ? )

Mainly speed. If you do all byte wise, things slow down. Of course alignment is important when using 32-bit instructions. The Trice macro base size is 4 bytes. If, for example a single 8-bit value is parameter, its includes 3 padding 0-bytes. These are not transferred - they only occupy RAM. A 64-bit alignment would be overkill, so 32-bit seems to be a good choice, as many MCUs nowadays are 32-bit ones.

I understand the syntax of macros and the feature attached to them but not the full uppercase one

"the full uppercase one" is the real Trice macro only using inline code. Because the main design aim was speed, this was the original design. Then I realized, that several hundred of TRICE macros increase the needed code amount too much and that it is better to have just a function call instead of having inline macros. If speed matters use TRICE(id(0), TRICE(Id(0), TRICE(ID(0) else use trice(iD(0), Trice(iD(0), TRice(iD(0) or mix usage as you like. The lower case macros internally use TRICE but each is only a function call.

The TRICE macro definition uses the C preprocess to concatenate the code behind the sub-macros
TRICE_ENTER
tid=id(n), Id(n), ID(n)
TRICE_CNTC(0)
TRICE_LEAVE

When i read this macros (trice8.h:93). I think tid is unused. it is right guess ?

tid in this context is executable code id, Id or ID defined in trice.h:

//! ID writes 14-bit id with 11 as 2 most significant bits, followed by a 32-bit stamp.
//! 11iiiiiiI TT | TT (NC) | ...
//! C000 = 1100 0000 0000 0000
#define ID(n)                                 \
	do {                                      \
		uint32_t ts = TriceStamp32;           \
		TRICE_PUT16_1616((0xC000 | (n)), ts); \
	} while (0)

//! Id writes 14-bit id with 10 as 2 most significant bits two times, followed by a 16-bit stamp.
//! 10iiiiiiI 10iiiiiiI | TT (NC) | ...
//! 8000 = 1000 0000 0000 0000
#define Id(n)                                        \
	do {                                             \
		uint16_t ts = TriceStamp16;                  \
		TRICE_PUT((0x80008000 | ((n) << 16) | (n))); \
		TRICE_PUT16(ts);                             \
	} while (0)

//! id writes 14-bit id with 01 as 2 most significant bits, followed by no stamp.
//! 01iiiiiiI (NC) | ...
//! 4000 = 0100 0000 0000 0000
#define id(n) TRICE_PUT16(0x4000 | (n));

//! iD is just a code parsing helper.
#define iD(n) (n)