triceRingBuffer.c

//! \file triceRingBuffer.c
//! \author Thomas.Hoehenleitner [at] seerose.net
//! //////////////////////////////////////////////////////////////////////////
#include "cobs.h"
#include "tcobs.h"
#include "trice.h"

#if TRICE_BUFFER == TRICE_RING_BUFFER && TRICE_OFF == 0

#if TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE
static void triceSingleDeferredOut(int* wordCount);
#else
static void triceMultiDeferredOut(int* triceCount, int* wordCount);
#endif

#if TRICE_RING_BUFFER_OVERFLOW_WATCH == 1

#define TRICE_RING_BUFFER_LOWER_MARGIN 8 //!< 32-bit units just for debugging > 0
#define TRICE_RING_BUFFER_UPPER_MARGIN 8 //!< 32-bit units just for debugging > 0
#define TRICE_RING_BUFFER_MARGIN_FILL_VALUE 0xfee4deb

#else

#define TRICE_RING_BUFFER_LOWER_MARGIN 0 //!< 32-bit units just for debugging > 0
#define TRICE_RING_BUFFER_UPPER_MARGIN 0 //!< 32-bit units just for debugging > 0
#define TRICE_RING_BUFFER_FILL_VALUE 0

#endif

//! triceRingBuffer is a kind of heap for trice messages. It needs to be initialized with 0.
//! Initial:
//! |<-LM->|<----------------  triceRingBuffer  ------------------------------------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<---------------- TRICE_RING_BUFFER_SIZE -------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<--        writable        -->|<-- TRICE_RING_BUFFER_MIN_SPACE32 -->|<-UM->|
//!                                |                              |                                     ^--------- TriceRingBufferLimit
//!                                |                              ^----------------------------------------------- TriceRingBufferProtectLimit
//!                                ^------------------------------------------------------------------------------ TriceBufferWritePosition
//!                                ^------------------------------------------------------------------------------ TriceRingBufferReadPosition
//!                                ^------------------------------------------------------------------------------ TriceRingBufferStart
//!
//! After some writes:
//! |<-LM->|<----------------  triceRingBuffer  ------------------------------------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<---------------- TRICE_RING_BUFFER_SIZE -------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<-T->|<-T->|<--  writable  -->|<-- TRICE_RING_BUFFER_MIN_SPACE32 -->|<-UM->|
//!                                |           |                  |                                     ^--------- TriceRingBufferLimit
//!                                |           |                  ^----------------------------------------------- TriceRingBufferProtectLimit
//!                                |           ^------------------------------------------------------------------ TriceBufferWritePosition
//!                                ^------------------------------------------------------------------------------ TriceRingBufferReadPosition
//!                                ^------------------------------------------------------------------------------ TriceRingBufferStart
//!
//! After some reads:
//! |<-LM->|<----------------  triceRingBuffer  ------------------------------------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<---------------- TRICE_RING_BUFFER_SIZE -------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<writable->|<--  writable  -->|<-- TRICE_RING_BUFFER_MIN_SPACE32 -->|<-UM->|
//!                                |           |                  |                                     ^--------- TriceRingBufferLimit
//!                                |           |                  ^----------------------------------------------- TriceRingBufferProtectLimit
//!                                |           ^------------------------------------------------------------------ TriceBufferWritePosition
//!                                |           ^-------------------------------------------------------------------TriceRingBufferReadPosition
//!                                ^------------------------------------------------------------------------------ TriceRingBufferStart
//!
//! After some time:
//! |<-LM->|<----------------  triceRingBuffer  ------------------------------------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<---------------- TRICE_RING_BUFFER_SIZE -------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|                              |<-- TRICE_RING_BUFFER_MIN_SPACE32 -->|<-UM->|
//!                                |                              |                                     ^--------- TriceRingBufferLimit
//!                                |                              ^----------------------------------------------- TriceRingBufferProtectLimit
//!                                |<-- writable -->|<-T->|<-T->|<-T->|<-------- not writable --------->|<-UM->|
//!                                |                |                 ^------------------------------------------- TriceBufferWritePosition, no more TRICE_RING_BUFFER_MIN_SPACE32!
//!                                |                ^------------------------------------------------------------- TriceRingBufferReadPosition
//!                                ^------------------------------------------------------------------------------ TriceRingBufferStart
//! With next Trice, TriceBufferWritePosition has to wrap firstly:
//! |<-LM->|<----------------  triceRingBuffer  ------------------------------------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|<---------------- TRICE_RING_BUFFER_SIZE -------------------------->|<-UM->|
//! |<-LM->|<--TRICE_DATA_OFFSET-->|                              |<-- TRICE_RING_BUFFER_MIN_SPACE32 -->|<-UM->|
//!                                |                              |                                     ^--------- TriceRingBufferLimit
//!                                |                              ^----------------------------------------------- TriceRingBufferProtectLimit
//!                                |<-- writable -->|<-T->|<-T->|<-T->|<-------- not writable --------->|<-UM->|   When depth32(==writable) < TRICE_RING_BUFFER_MIN_SPACE32, no write is possible.
//!                                |                ^------------------------------------------------------------- TriceRingBufferReadPosition
//!                                ^------------------------------------------------------------------------------ TriceBufferWritePosition (wrapped)
//!                                ^------------------------------------------------------------------------------ TriceRingBufferStart
uint32_t triceRingBuffer[TRICE_RING_BUFFER_LOWER_MARGIN + (TRICE_DATA_OFFSET >> 2) + (TRICE_RING_BUFFER_SIZE >> 2) + TRICE_RING_BUFFER_UPPER_MARGIN] = {0};

//! TRICE_RING_BUFFER_MIN_SPACE32 is the needed space before a new Trice is allowed to be written.
//! The TRICE_DATA_OFFSET guaranties, that in front of TriceRingBufferReadPosition is always a scratch pad.
#define TRICE_RING_BUFFER_MIN_SPACE32 ((TRICE_SINGLE_MAX_SIZE + TRICE_DATA_OFFSET) >> 2)

//! TRICE_RING_BUFFER_START is a helper definition to avoid warning "expression must have a constant value".
#define TRICE_RING_BUFFER_START (triceRingBuffer + TRICE_RING_BUFFER_LOWER_MARGIN + (TRICE_DATA_OFFSET >> 2))

//! TriceRingBufferStart is an immutable pointer to the begin of the triceRingBuffer area.
uint32_t* const TriceRingBufferStart = TRICE_RING_BUFFER_START;

//! triceBufferWriteLimit is the first address behind triceRingBuffer area and immutable.
//! With encryption it can happen that 4 bytes following TriceRingBufferLimit are used as scratch pad.
//! We use the value of TRICE_DEFERRED_XTEA_ENCRYPT (0 or 1) here to respect that
//! See also comment inside triceSingleDeferredOut.
uint32_t* const TriceRingBufferLimit = TRICE_RING_BUFFER_START + (TRICE_RING_BUFFER_SIZE >> 2);

//! TricesCountRingBuffer holds the readable trices count inside triceRingBuffer.
unsigned TricesCountRingBuffer = 0;

//! TriceBufferWritePosition is used by the TRICE_PUT macros.
uint32_t* TriceBufferWritePosition = TRICE_RING_BUFFER_START;

//! TriceRingBufferProtectLimit is the first address not allowed to be written to in any circumstances.
//! If TriceBufferWritePosition >= TriceRingBufferProtectLimit, TriceBufferWritePosition needs to wrap.
uint32_t* const TriceRingBufferProtectLimit = TRICE_RING_BUFFER_START + (TRICE_RING_BUFFER_SIZE >> 2) - TRICE_RING_BUFFER_MIN_SPACE32;

//! TriceRingBufferReadPosition points to a valid trice message when singleTricesRingCount > 0.
//! This is first the TRICE_DATA_OFFSET byte space followed by the trice data.
//! Initially this value is set to TriceRingBufferStart minus TRICE_DATA_OFFSET byte space
//! to get a correct value for the very first call of triceNextRingBufferRead
// uint32_t* TriceRingBufferReadPosition = TriceRingBufferStart - (TRICE_DATA_OFFSET>>2); //lint !e428 Warning 428: negative subscript (-4) in operator 'ptr-int'
uint32_t* TriceRingBufferReadPosition = TRICE_RING_BUFFER_START;

#if TRICE_DIAGNOSTICS == 1

//! TricesCountRingBufferMax holds the max count of trices occurred inside the ring buffer.
//! This value is only informal, because the length of the trice messages is not known.
// unsigned TricesCountRingBufferMax = 0;

//! TriceRingBufferDepthMax holds the max occurred ring buffer depth.
int TriceRingBufferDepthMax = 0;

#endif // #if TRICE_DIAGNOSTICS == 1

#if TRICE_PROTECT == 1

//! TriceEnoughSpace checks, if enough bytes available for the next trice.
//! \retval 0, when not enough space
//! \retval 1, when enough space
int TriceEnoughSpace(void) {
	// depth32 is the used buffer space in 32-bit words. After reset TriceBufferWritePosition and TriceRingBufferReadPosition are equal and depth32 is 0.
	// After some trice data writing, TriceBufferWritePosition is > TriceRingBufferReadPosition and depth32 has a positive value.
	// When trice data read out takes place, the TriceRingBufferReadPosition is incremented. That makes the depth32 value smaller again and gives write space.
	// Before a new trice write operation, TriceBufferWritePosition is reset to TriceRingBufferStart if less than TRICE_SINGLE_MAX_SIZE bytes left to the TriceRingBufferLimit.
	// So, even there is a only 4 bytes Trice, it cannot be written, when no full TRICE_SINGLE_MAX_SIZE space is left, because we do not know its size in advance.
	// The TriceRingBufferReadPosition jumps in the same way as the TriceBufferWritePosition. It wraps according the same rules.

	int depth32 = TriceBufferWritePosition - TriceRingBufferReadPosition;
	if (depth32 == 0 && TricesCountRingBuffer > 0) {
		goto noSpace;
	}
	if (depth32 < 0) { // After a TriceBufferWritePosition reset the difference is negative and needs correction to get the correct value.
		depth32 += (TRICE_RING_BUFFER_SIZE >> 2);
	}
	// This fn is called before an intended trice data write ande therefore additional at least TRICE_SINGLE_MAX_SIZE>>2 32-bit words need to fit in the buffer.
	// There must be left TRICE_DATA_OFFSET space behind the last Trice to be usable as scratch pad in front of TriceRingBufferReadPosition.
	if (depth32 <= (TRICE_RING_BUFFER_SIZE >> 2) - TRICE_RING_BUFFER_MIN_SPACE32) {
		return 1;
	} else {
	noSpace:
#if TRICE_DIAGNOSTICS == 1
		TriceDeferredOverflowCount++;
#endif
		return 0;
	}
}

#endif // #if TRICE_PROTECT == 1

// triceIncrementRingBufferReadPosition sets TriceRingBufferReadPosition forward by wordCount.
//! \param lastWordCount is the u32 count of the last read trice including padding bytes.
TRICE_INLINE void triceIncrementRingBufferReadPosition(int wordCount) {
	TriceRingBufferReadPosition += wordCount;
	if (TriceRingBufferReadPosition > TriceRingBufferProtectLimit) {
		TriceRingBufferReadPosition = TriceRingBufferStart;
	}
}

// triceRingBufferDiagnostics computes and tracks TriceRingBufferDepthMax
TRICE_INLINE void triceRingBufferDiagnostics(void) {
#if TRICE_DIAGNOSTICS == 1
	int depth = (TriceBufferWritePosition - TriceRingBufferReadPosition) << 2; // lint !e845 Info 845: The left argument to operator '<<' is certain to be 0
	if (depth < 0) {
		depth += TRICE_DEFERRED_BUFFER_SIZE;
	}
	TriceRingBufferDepthMax = (depth > TriceRingBufferDepthMax) ? depth : TriceRingBufferDepthMax;
#endif // #if TRICE_DIAGNOSTICS == 1
}

#if TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE

//! triceTransferSingleFraming transfers a single Trice from the Ring Buffer.
//! Implicit assumed is, that the pre-condition "TricesCountRingBuffer > 0" is fulfilled.
void triceTransferSingleFraming(void) {
	triceRingBufferDiagnostics(); // We need to measure before the RingBufferReadPosition increment.

	static int lastWordCount = 0; // lastWordCount is needed to increment TriceRingBufferReadPosition accordingly after transfer is done.
	triceIncrementRingBufferReadPosition(lastWordCount);
	lastWordCount = 0;

	if (TricesCountRingBuffer == 0) { // no data
		return;
	}
	TRICE_ENTER_CRITICAL_SECTION
	TricesCountRingBuffer--; // We decrement, even the Trice is not out yet.
	TRICE_LEAVE_CRITICAL_SECTION

	// The trice data are starting at byte offset TRICE_DATA_OFFSET from TriceRingBufferReadPosition.
	triceSingleDeferredOut(&lastWordCount);
}

#endif // #if TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE

#if TRICE_DEFERRED_TRANSFER_MODE == TRICE_MULTI_PACK_MODE

//! triceTransferMultiFraming transfers several, but not necessarily all, Trices from the Ring Buffer.
void triceTransferMultiFraming(void) {
	triceRingBufferDiagnostics(); // We need to measure before the RingBufferReadPosition increment.

	// The Ring Buffer can contain a fair amount of trices and we do not want them copy in a separate buffer for less RAM usage.
	// Therefore we pack all Trices until the Ring Buffer end (where it wraps) together.
	// We know here, that at least one Trice is inside the Ring Buffer.
	static int triceCount = 0; // triceCount it the count of Trices from the last call.
	TRICE_ENTER_CRITICAL_SECTION
	// It is known here, that the previous transmission is finished and we can advance.
	TricesCountRingBuffer -= triceCount;
	TRICE_LEAVE_CRITICAL_SECTION
	triceCount = 0;

	static int multiWordCount = 0;                        // wordCount is the Ring Buffer space which is now free after the last transfer is finished.
	triceIncrementRingBufferReadPosition(multiWordCount); // We can safely increment here, because we know, that the last transmission is done.
	multiWordCount = 0;

	triceMultiDeferredOut(&triceCount, &multiWordCount);
	return;
}

#endif // #if TRICE_DEFERRED_TRANSFER_MODE == TRICE_MULTI_PACK_MODE

//! TriceTransfer needs to be called cyclically to read out the Ring Buffer.
void TriceTransfer(void) {
#if TRICE_CGO == 0             // In automated tests we assume last transmission is finished, so we do not test depth to be able to test multiple Trices in deferred mode.
	if (TriceOutDepth() > 0) { // Last transmission not finished. todo: Write TriceOutDepth() as dummy for TRICE_CGO.
		return;
	}
#endif
#if TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE
	triceTransferSingleFraming();
#else
	triceTransferMultiFraming();
#endif
}

//! TriceIDAndBuffer evaluates a trice message and returns the ID for routing.
//! \param pData is where the trice message starts.
//! \param pWordCount is filled with the word count the trice data occupy from pData.
//! \param ppTriceNetStart is filled with the trice net data start. That is maybe a 2 bytes offset from pData.
//! \param pTriceNetLength is filled with the net trice length (without padding bytes), 0 on error.
//! \retval is the triceID, a positive value on success or error information.
static int TriceIDAndBuffer(const uint32_t* const pData, int* pWordCount, uint8_t** ppTriceNetStart, size_t* pTriceNetLength) {
	uint16_t TID = TRICE_TTOHS(*(uint16_t*)pData); // type and id
	int triceID = 0x3FFF & TID;
	int triceType = TID >> 14; // 2 bits
	unsigned offset;
	size_t len;
	uint8_t* pStart = (uint8_t*)pData;
	switch (triceType) {
	case TRICE_TYPE_S0: // S0 = no stamp
		offset = 0;
		len = 4 + triceDataLen(pStart + 2); // tyId
		break;
	case TRICE_TYPE_S2:                     // S2 = 16-bit stamp
		len = 6 + triceDataLen(pStart + 6); // tyId ts16
		offset = 2;
#if TRICE_DEFERRED_XTEA_ENCRYPT
		// move trice to start at a uint32_t alignment border
		memmove(pStart, pStart + 2, len); // https://stackoverflow.com/questions/1201319/what-is-the-difference-between-memmove-and-memcpy
#else                                     // #if TRICE_DEFERRED_XTEA_ENCRYPT
		// Like for UART transfer no uint32_t alignment is needed.
		pStart += 2; // see Id(n) macro definition
#endif                                    // #else // #if TRICE_DEFERRED_XTEA_ENCRYPT
		break;
	case TRICE_TYPE_S4: // S4 = 32-bit stamp
		offset = 0;
		len = 8 + triceDataLen(pStart + 6); // tyId ts32
		break;
	default: // impossible case (triceType has only 2 bits)
	         // fall thru
	case TRICE_TYPE_X0:
		TriceErrorCount++;
		*ppTriceNetStart = pStart;
		*pTriceNetLength = 0;
		return -__LINE__; // extended trices not supported (yet)
	}
	// S16 case example:            triceSize  len   t-0-3   t-o
	// 80id 80id 1616 00cc                8     6      3      6
	// 80id 80id 1616 01cc dd            12     7      7     10
	// 80id 80id 1616 02cc dd dd         12     8      7     10
	// 80id 80id 1616 03cc dd dd dd      12     9      7     10
	// 80id 80id 1616 04cc dd dd dd dd   12    10      7     10
	*pWordCount = (len + offset + 3) >> 2;
	*ppTriceNetStart = pStart;
	*pTriceNetLength = len;
	return triceID;
}

#if TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE

//! triceSingleDeferredOut expects a single trice at TriceRingBufferReadPosition and returns the wordCount of this trice which includes 1-3 padding bytes.
//! The space from TriceRingBufferReadPosition-TRICE_DATA_OFFSET to TriceRingBufferReadPosition is assumed to be usable as scratch pad.
//! This function is specific to the ring buffer, because the wordCount value needs to be reconstructed.
//! \retval The returned value tells how many words where used by the transmitted trice and is usable for the memory management. See RingBuffer for example.
//! The returned value is typically (TRICE_DATA_OFFSET/4) plus 1 (4 bytes) to 3 (9-12 bytes) but could go up to ((TRICE_DATA_OFFSET/4)+(TRICE_BUFFER_SIZE/4)).
//! Return values <= 0 signal an error.
//! TriceRingBufferReadPosition points to the begin of a single trice.
//! The data at TriceRingBufferReadPosition are getting destroyed, because buffer is used as scratch pad.
static void triceSingleDeferredOut(int* wordCount) {
	uint8_t* enc = ((uint8_t*)TriceRingBufferReadPosition) - TRICE_DATA_OFFSET; // TRICE_DATA_OFFSET bytes are usable in front of TriceRingBufferReadPosition.
	uint8_t* pTriceNetStart;                                                    // Trice starts here. That is maybe a 2 bytes offset from TriceRingBufferReadPosition.
	size_t triceNetLength;                                                      // Trice length without padding bytes.
	int triceID = TriceIDAndBuffer(TriceRingBufferReadPosition, wordCount, &pTriceNetStart, &triceNetLength);
	// We can let TRICE_DATA_OFFSET only in front of the ring buffer and pack the Trices without offset space.
	// And if we allow as max depth only ring buffer size minus TRICE_DATA_OFFSET, we can use space in front of each Trice.

#if (TRICE_DEFERRED_XTEA_ENCRYPT == 1) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_NONE)
#if TRICE_CONFIG_WARNINGS == 1
#warning configuration: The Trice tool does not support encryption without COBS (or TCOBS) framing.
#endif
	size_t encLen = TriceEncode(TRICE_DEFERRED_XTEA_ENCRYPT, TRICE_DEFERRED_OUT_FRAMING, enc, pTriceNetStart, triceNetLength);
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 1)
	// comment: The following 2 steps could be done in an incremental way within one singe loop.
	// Behind the trice brutto length (with padding bytes), 4 bytes needed as scratch pad when XTEA is active.
	// After TriceIDAndBuffer pTriceNetStart could have a 2 bytes offset.
	uint8_t* tmp = ((uint8_t*)TriceRingBufferReadPosition) - 4;
	memmove(tmp, pTriceNetStart, triceNetLength);           // Make 4 bytes space for scratch pad beind Trice message.
	size_t len8 = (triceNetLength + 7) & ~7;                // Only multiple of 8 are possible to encrypt, so we adjust len.
	memset(tmp + triceNetLength, 0, len8 - triceNetLength); // clear padding space
	XTEAEncrypt((uint32_t*)tmp, len8 >> 2);
#if TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_TCOBS
	size_t encLen = (size_t)TCOBSEncode(enc, tmp, len8);
#elif TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_COBS
	size_t encLen = COBSEncode(enc, tmp, len8);
#else
#error configuration
#endif
	enc[encLen++] = 0; // Add zero as package delimiter.
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 0) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_TCOBS)
	size_t len = (size_t)TCOBSEncode(enc, pTriceNetStart, triceNetLength);
	enc[len++] = 0; // Add zero as package delimiter.
	size_t encLen = len;
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 0) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_COBS)
	size_t len = (size_t)COBSEncode(enc, pTriceNetStart, triceNetLength);
	enc[len++] = 0; // Add zero as package delimiter.
	size_t encLen = len;
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 0) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_NONE)
	enc = pTriceNetStart;
	size_t encLen = triceNetLength;
#else
#error configuration: TRICE_DEFERRED_TRANSFER_MODE == TRICE_MULTI_PACK_MODE for ring buffer not implemented yet
#endif
#if TRICE_DIAGNOSTICS == 1
	// enc                 addr  pTriceNetStart           nextData
	// ^-TRICE_DATA_OFFSET-^-0|2-^-triceNetLength+(0...3)-^
	// ^-encLen->firstNotModifiedAddress
	uint8_t* nextData = (uint8_t*)(((uintptr_t)(pTriceNetStart + triceNetLength + 3)) & ~3);
	uint8_t* firstNotModifiedAddress = enc + encLen;
	int distance = nextData - firstNotModifiedAddress;
	int triceDataOffsetDepth = TRICE_DATA_OFFSET - distance; // distance could get > TRICE_DATA_OFFSET, so TriceDataOffsetDepthMax stays unchanged then.
	TriceDataOffsetDepthMax = triceDataOffsetDepth < TriceDataOffsetDepthMax ? TriceDataOffsetDepthMax : triceDataOffsetDepth;
#endif // #if TRICE_DIAGNOSTICS == 1
	TriceNonBlockingDeferredWrite8(triceID, enc, encLen);
}

#endif // #if TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE

#if TRICE_DEFERRED_TRANSFER_MODE == TRICE_MULTI_PACK_MODE

// triceMultiDeferredOut packs Trices until the Ring Buffer end and returns their count and total length in words.
// These 2 values are used later, after the transmission is finished, for advancing.
// The value TricesCountRingBuffer is evaluated internally but not modified.
static void triceMultiDeferredOut(int* triceCount, int* multiWordCount) {
	*triceCount = 0;
	*multiWordCount = 0;
	if (TricesCountRingBuffer == 0) {
		return; // Nothing to do.
	}
	// At least one Trice message is ready for transfer.
	if (TriceRingBufferReadPosition > TriceRingBufferLimit - TRICE_RING_BUFFER_MIN_SPACE32) {
		for (;;)
			; // unexpected
	}

	// We can start at TriceRingBufferReadPosition and go to the TriceRingBufferLimit OR go to the TriceBufferWritePosition using TricesCountRingBuffer.
	uint8_t* enc = ((uint8_t*)TriceRingBufferReadPosition) - TRICE_DATA_OFFSET; // TRICE_DATA_OFFSET bytes are usable in front of TriceRingBufferReadPosition.
	uint8_t* tmp = enc + TRICE_DATA_OFFSET / 2;                                 // todo
	uint8_t* nextEnc = tmp;
	int multiLen = 0;
	uint32_t* nextTriceRingBufferReadPosition = TriceRingBufferReadPosition;
	do {
		int wordCount = 0;
		uint8_t* pTriceNetStart; // Trice starts here.
		size_t triceNetLength;   // Trice length without padding bytes.
		TriceIDAndBuffer(nextTriceRingBufferReadPosition, &wordCount, &pTriceNetStart, &triceNetLength);
		memmove(nextEnc, pTriceNetStart, triceNetLength);
		nextEnc += triceNetLength;
		multiLen += triceNetLength;
		*multiWordCount += wordCount;
		(*triceCount)++;
		nextTriceRingBufferReadPosition += wordCount;

	} while (*triceCount < TricesCountRingBuffer && nextTriceRingBufferReadPosition <= TriceRingBufferLimit - TRICE_RING_BUFFER_MIN_SPACE32);

#if (TRICE_DEFERRED_XTEA_ENCRYPT == 1) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_NONE)
#if TRICE_CONFIG_WARNINGS == 1
#warning configuration: The Trice tool does not support encryption without COBS (or TCOBS) framing.
#endif
	size_t encLen = TriceEncode(TRICE_DEFERRED_XTEA_ENCRYPT, TRICE_DEFERRED_OUT_FRAMING, enc, enc, multiLen);
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 1)
	size_t len8 = (multiLen + 7) & ~7;          // Only multiple of 8 are possible to encrypt, so we adjust len.
	memset(tmp + multiLen, 0, len8 - multiLen); // clear padding space
	XTEAEncrypt((uint32_t*)tmp, len8 >> 2);
#if TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_TCOBS
	size_t encLen = (size_t)TCOBSEncode(enc, tmp, len8);
	enc[encLen++] = 0;
#elif TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_COBS
	size_t encLen = (size_t)COBSEncode(enc, tmp, len8);
	enc[encLen++] = 0;
#else
#error configuration
#endif
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 0) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_TCOBS)
	size_t len = (size_t)TCOBSEncode(enc, tmp, multiLen);
	enc[len++] = 0; // Add zero as package delimiter.
	size_t encLen = len;
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 0) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_COBS)
	size_t len = (size_t)COBSEncode(enc, tmp, multiLen);
	enc[len++] = 0; // Add zero as package delimiter.
	size_t encLen = len;
#elif (TRICE_DEFERRED_XTEA_ENCRYPT == 0) && (TRICE_DEFERRED_OUT_FRAMING == TRICE_FRAMING_NONE)
	size_t encLen = multiLen;
#else
#error configuration: TRICE_DEFERRED_TRANSFER_MODE == TRICE_MULTI_PACK_MODE for ring buffer not implemented yet
#endif
#if TRICE_DIAGNOSTICS == 1
// todo ...
#endif // #if TRICE_DIAGNOSTICS == 1
	TriceNonBlockingDeferredWrite8(0, enc, encLen);
}

#endif // #if TRICE_DEFERRED_TRANSFER_MODE == TRICE_MULTI_PACK_MODE

#if TRICE_RING_BUFFER_OVERFLOW_WATCH == 1

void TriceInitRingBufferMargins(void) {
	for (int i = 0; i < TRICE_RING_BUFFER_LOWER_MARGIN; i++) {
		triceRingBuffer[i] = TRICE_RING_BUFFER_MARGIN_FILL_VALUE;
	}
	for (int i = 0; i < TRICE_RING_BUFFER_UPPER_MARGIN; i++) {
		*(TriceRingBufferLimit + i) = TRICE_RING_BUFFER_MARGIN_FILL_VALUE;
	}
}

void WatchRingBufferMargins(void) {
	for (int i = 0; i < TRICE_RING_BUFFER_LOWER_MARGIN; i++) {
		if (triceRingBuffer[i] != TRICE_RING_BUFFER_MARGIN_FILL_VALUE) {
			for (;;)
				;
		}
	}

	for (int i = 0; i < TRICE_RING_BUFFER_UPPER_MARGIN; i++) {
		if (*(TriceRingBufferLimit + i) != TRICE_RING_BUFFER_MARGIN_FILL_VALUE) {
			for (;;)
				;
		}
	}
}

#endif // #if TRICE_RING_BUFFER_OVERFLOW_WATCH == 1

#endif // #if TRICE_BUFFER == TRICE_RING_BUFFER && TRICE_OFF == 0