branch experimentalTriceProtect merged

.gitignore

@@ -13,19 +13,23 @@
 #.id
 #_tryout/*
 
-internal/decoder/debug.test
-.netrc
-dist/**
-*.uvoptx
-*.__i
-*._ia
+#internal/decoder/debug.test
+#.netrc
+#dist/**
+#*.uvoptx
+#*.__i
+#*._ia
 
-test/MDK-ARM_STM32F030R8/temp/
-test/testdata/temp/
-test/vsCode_Nucleo-G0B1_instrumented/temp/
-test/Nucleo-STM32L432LC_generated/build/
-test/PSoC-Creator-4.2-Workspace/PSoC-Creator-4.2-Workspace.cywrk.ms
-test/PSoC-Creator-4.2-Workspace/Software_Transmit_UART.cydsn/Software_Transmit_UART.cyfit
-test/PSoC-Creator-4.2-Workspace/Software_Transmit_UART.cydsn/Software_Transmit_UART.rpt
+#test/MDK-ARM_STM32F030R8/temp/
+#test/testdata/temp/
+#test/vsCode_Nucleo-G0B1_instrumented/temp/
+#test/Nucleo-STM32L432LC_generated/build/
+#test/PSoC-Creator-4.2-Workspace/PSoC-Creator-4.2-Workspace.cywrk.ms
+#test/PSoC-Creator-4.2-Workspace/Software_Transmit_UART.cydsn/Software_Transmit_UART.cyfit
+#test/PSoC-Creator-4.2-Workspace/Software_Transmit_UART.cydsn/Software_Transmit_UART.rpt
 
 dist/
+**/build/
+**/temp/
+
+*.exe

CHANGELOG.md

@@ -45,7 +45,7 @@ date        | version | comment
 2023-AUG-06 |  0.62.1 | In some cases, when Trice16() returned a 32-bit value the cycle counter got disturbed. This is solved now.
 2023-SEP-10 |  0.62.2 | Fixes issue [#427](https://github.com/rokath/trice/issues/427). TCOBS decoder more robust against data garbage.
 2023-SEP-22 |  0.62.3 | Incorporated pull requests [#433](https://github.com/rokath/trice/issues/433) && [#435](https://github.com/rokath/trice/issues/435). Minor clarification in trice user guide.
-2024-Mar-17 |  0.63.0 | Issue [#436](https://github.com/rokath/trice/issues/436) done (faster now). Issue [#438](https://github.com/rokath/trice/issues/438) done (minor). Issue [#439](https://github.com/rokath/trice/issues/439) done (no more trice macros inside header files). Now unified `__restrict` keyword. `RESTRICT` keyword removed and `#include <stdint.h>` into all **triceConfig.h** files. Obsolete 'RESTRICT' code removed. Code cleanup, tests now ok with `-race`. **Added: `triceAssertTrue` and `triceAssertFalse`**. CLI switch `-d16` better documented. **`UserNonBlockingDirectWriteAuxiliaryFn` and `UserNonBlockingDeferredWriteAuxiliaryFn` invented for a cleaner auxiliary interface adaption**. Doc updated in `TriceUserGuide.md`, `TriceVsPrintfSimilaritiesAndDifferences.md`, `TriceTargetCode.md`, `TriceColor.md` and preface extended. Folder `examples` fixed. Merge pull request [#442](https://github.com/rokath/trice/pull/442) from rokath/dependabot/go_modules/golang.org/x/crypto-0.17.0. Merge pull request [#437](https://github.com/rokath/trice/pull/437) from hugobpontes/fix_ID_Id_compiler_warnings (add  `do ... while (0)` to Id and ID macros.
+2024-Mar-17 |  0.63.0 | Issue [#436](https://github.com/rokath/trice/issues/436) done (faster now). Issue [#438](https://github.com/rokath/trice/issues/438) done (minor). Issue [#439](https://github.com/rokath/trice/issues/439) done (no more trice macros inside header files). Now unified `__restrict` keyword. `RESTRICT` keyword removed and `#include <stdint.h>` into all **triceConfig.h** files. Obsolete 'RESTRICT' code removed. Code cleanup, tests now ok with `-race`. **Added: `triceAssertTrue` and `triceAssertFalse`**. CLI switch `-d16` better documented. **`UserNonBlockingDirectWrite8AuxiliaryFn` and `UserNonBlockingDeferredWrite8AuxiliaryFn` invented for a cleaner auxiliary interface adaption**. Doc updated in `TriceUserGuide.md`, `TriceVsPrintfSimilaritiesAndDifferences.md`, `TriceTargetCode.md`, `TriceColor.md` and preface extended. Folder `examples` fixed. Merge pull request [#442](https://github.com/rokath/trice/pull/442) from rokath/dependabot/go_modules/golang.org/x/crypto-0.17.0. Merge pull request [#437](https://github.com/rokath/trice/pull/437) from hugobpontes/fix_ID_Id_compiler_warnings (add  `do ... while (0)` to Id and ID macros.
 
 ## v0.60.1 Twice Log Screen Shot
 

README.md

@@ -206,7 +206,7 @@ trice32( Id(12345), "Verbose: bla bla")
 These can be understood as tags too. But only one tag per *trice* right now.
 Look into [lineTransformerANSI.go](./internal/emitter/lineTransformerANSI.go) for options or extensions.
 
-Also you can at compile time disable *trice* code generation on file level with `#define TRICE_OFF` before including `trice.h`.
+Also you can at compile time disable *trice* code generation on file level with `#define TRICE_OFF 1` before including `trice.h`.
 
 Because [one *trice* consists typically only of 4 to 8 bytes](./docs/TriceEncodings.md#flex-encoding) there is usually no need to dynamically switch trices on and off inside the embedded device. This can be done on the display side inside the **trice** tool with the command line switches `-ban` or `-pick`. For example `-pick err,wrn` disables all output despite error and warning messages.
 Switching trices on and off inside the target increases the overhead and demands some kind of command interface.

docs/TraceWithTrice.md

@@ -159,10 +159,10 @@ If a target side log level control is needed, a **trice** tool extension could e
 
 ###  5.8. <a name='CompiletimeenabledisableTRICEmacrosonfilelevel'></a>Compile time enable/disable `TRICE` macros on file level 
 
-After debugging code in a file, there is [no need to remove or comment out `TRICE` macros](./TriceConfiguration.md#target-side-trice-on-off). Write a `#define TRICE_OFF` just before the `#include "trice.h"` line and all `TRICE` macros in this file are ignored completely by the compiler, but not by the **trice** tool. In case of re-constructing the [**T**rice **ID** **L**ist](../til.json) these no code generating macros are regarded.
+After debugging code in a file, there is [no need to remove or comment out `TRICE` macros](./TriceConfiguration.md#target-side-trice-on-off). Write a `#define TRICE_OFF 1` just before the `#include "trice.h"` line and all `TRICE` macros in this file are ignored completely by the compiler, but not by the **trice** tool. In case of re-constructing the [**T**rice **ID** **L**ist](../til.json) these no code generating macros are regarded.
 
 ```C
-//#define TRICE_OFF // enable this line to disable trice code generation in this file object
+#define TRICE_OFF 0 // Set this value to 1 to disable trice code generation in this file object.
 #include "trice.h"
 ```
 

docs/TriceSpace.md

@@ -37,7 +37,7 @@ The following numbers are measured with a legacy encoding, showing that the inst
 
 * The core instrumentation needs less 150 bytes FLASH and about 100 bytes RAM when buffer size is 64 bytes.
 * The about 50 trices in TriceCheckSet() allocate roughly 2100 (fast mode) or 1500 (small mode) bytes.
-* trices are removable without code changes by defining `TRICE_OFF` on file or project level.
+* trices are removable without code changes with `#define TRICE_OFF 1` before `incude "trice.h"` on file level or generally on project level.
 
 ##  3. <a name='Memoryneedsexampleprojects'></a>Memory needs (example projects)
 

docs/TriceSpeed.md

@@ -34,7 +34,7 @@ The usual case is `#define TRICE_HTOTL(x) (x)`. The `uint32_t* TriceBufferWriteP
 
 * With appropriate mapping a direct write to physical output(s) is possible:
   * RTT0 without extra copy.
-    * With `TRICE_SEGGER_RTT_32BIT_DIRECT_WRITE` about 100 MCU clocks do the whole work, what is within 1.5 us @ 64 MHz.
+    * With `TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE` about 100 MCU clocks do the whole work, what is within 1.5 us @ 64 MHz.
   * AUX without extra copy.
   * Not (yet) supported UART transfer loop with polling. With 1MBit baud rate, 4-12 bytes would last 40-120 µs.
 

docs/TriceTargetCode.md

@@ -64,3 +64,46 @@ The `TRICE_RING_BUFFER` allocates incremental ring buffer space and each trice l
       - triceIDAndLen
       - triceDirectEncode
       - triceNonBlockingDirectWrite
+
+## Some Thoughs
+
+There have been 3 similar implementations for trice encode
+
+```C
+static size_t triceDirectEncode(   uint8_t* enc, const uint8_t * buf, size_t len );
+       size_t TriceDeferredEncode( uint8_t* enc, const uint8_t * buf, size_t len );
+
+unsigned TriceEncryptAndCobsFraming32( uint32_t * const triceStart, unsigned wordCount ){
+```
+
+Now:
+
+```C
+size_t TriceEncode( unsigned encrypt, unsigned framing, uint8_t* dst, const uint8_t * buf, size_t len ){ 
+unsigned TriceEncryptAndCobsFraming32( uint32_t * const triceStart, unsigned wordCount ){
+```
+
+Currently there are 3 similar implementations for trice buffer reads
+
+```C
+static size_t triceIDAndLen(    uint32_t* pBuf,               uint8_t** ppStart, int*      triceID );
+static int    TriceNext(        uint8_t** buf,                size_t* pSize,     uint8_t** pStart,    size_t* pLen );
+static int    TriceIDAndBuffer( uint32_t const * const pData, int* pWordCount,   uint8_t** ppStart,   size_t* pLength );
+```
+
+- The TriceID is only needed for routing and can co in a global variable just for speed.
+- The source buffer should be `uint32_t const * const`.
+- The destination should be given with `uint32_t * const` and the return value is the trice netto size. For efficiency the result should be ready encoded.
+
+```C
+//! \param pTriceID is filled with ID for routing
+//! \param pCount is used for double or ring buffer to advance inside the buffer
+//! \param dest provides space for the encoded trice
+//! \param src is the location of the trice message we want encode
+//! \retval is the netto size of the encoded trice data
+size_t TriceEncode(int* pTriceID, unsigned int pCount, uint32_t * const dest, uint32_t const * const src );
+```
+
+- This function interface is used for all cases.
+- First we use the existing code for implementation and then we clean the code.
+

docs/TriceUserGuide.md

@@ -1171,9 +1171,9 @@ As discussed in [issue #294](https://github.com/rokath/trice/issues/294) it can
 
 ###  11.1. <a name='TargetsideTriceOn-Off'></a>Target side *Trice* On-Off
 
-- If your code works well after checking, you can add `#define TRICE_OFF` just before the `#include "trice.h"` line and no *trice* code is generated anymore for that file, so no need to delete or comment out `TRICE` macros: : ![./ref/TRICE_OFF.PNG](./ref/TRICE_OFF.PNG)
-- Hint from @escherstair: With `-D TRICE_OFF` as compiler option, the trice code diappears completely from the binary.
-- No runtime On-Off switch is implemented for  several reasons:
+- If your code works well after checking, you can add `#define TRICE_OFF 1` just before the `#include "trice.h"` line and no *trice* code is generated anymore for that file, so no need to delete or comment out `TRICE` macros: : ![./ref/TRICE_OFF.PNG](./ref/TRICE_OFF.PNG)
+- Hint from @escherstair: With `-D TRICE_OFF=1` as compiler option, the trice code diappears completely from the binary.
+- No runtime On-Off switch is implemented for several reasons:
   - Would need a control channel to the target.
   - Would add little performance and code overhead.
   - Would sligtly change target timing (testing).
@@ -1381,7 +1381,7 @@ _##  12. <a name='TriceUserInterface-QuickStart'></a> Trice User Interface - Qui
 - *Trice* messages are framed binary data, if framing is not disabled.
 - Framing is important for data disruption cases and is done with [TCOBS](./TCOBSSpecification.md) (has included data reduction) but the user can force to use [COBS](https://github.com/rokath/COBS), what makes it easier to write an own decoder in some cases or disable framing at all. 
   - Change the setting `TRICE_FRAMING` inside `triceConfig.h` and use the **trice** tool `-packageFraming` switch accordingly.
-- For robustness each *Trice* gets its own (T)COBS package per default. That is changeable for transfer data reduction. Use `#define TRICE_TRANSFER_MODE TRICE_PACK_MULTI_MODE.` inside `triceConfig.h`. This allows to reduce the data size a bit by avoiding many 0-delimiter bytes but results in some more data loss in case of data disruptions.
+- For robustness each *Trice* gets its own (T)COBS package per default. That is changeable for transfer data reduction. Use `#define TRICE_DEFERRED_TRANSFER_MODE TRICE_PACK_MULTI_MODE.` inside `triceConfig.h`. This allows to reduce the data size a bit by avoiding many 0-delimiter bytes but results in some more data loss in case of data disruptions.
 
 <p align="right">(<a href="#top">back to top</a>)</p>
 
@@ -1397,8 +1397,8 @@ _##  12. <a name='TriceUserInterface-QuickStart'></a> Trice User Interface - Qui
 
 - To interpret a decoded package, it´s endianness needs to be known.
 - For efficiency binary trice data are stored and transmitted in MCU endianness and the **trice** tool expects binary data in little endian format as most MCUs are little endian.
-- On big endian MCUs the compiler switch `TRICE_MCU_IS_BIG_ENDIAN` needs to be defined and the **trice** tool has a CLI switch "triceEndianness" which needs to be set to "bigEndian" then.
-- If trice transmit data are needed to be not in MCU order for some reason, the macro `TRICE_TRANSFER_ORDER_IS_NOT_MCU_ENDIAN` is needed. This increases the critical trice storage time and target code amount.
+- On big endian MCUs the compiler switch `TRICE_MCU_IS_BIG_ENDIAN` needs to be defined as 1 and the **trice** tool has a CLI switch "triceEndianness" which needs to be set to "bigEndian" then.
+- If trice transmit data are needed to be not in MCU order for some reason, the macro `TRICE_TRANSFER_ORDER_IS_NOT_MCU_ENDIAN` is needed to be defined as 1. This increases the critical trice storage time and target code amount.
 
 <p align="right">(<a href="#top">back to top</a>)</p>
 
@@ -1424,7 +1424,7 @@ _##  12. <a name='TriceUserInterface-QuickStart'></a> Trice User Interface - Qui
   | `TRICE( Id(n), "...", ...)` | 16-bit     | calls internally `uint16_t TriceStamp16( void )` for trice message stamping |
   | `TRICE( ID(n), "...", ...)` | 32-bit     | calls internally `uint32_t TriceStamp32( void )` for trice message stamping |
 
-It is up to the user to provide the functions `TriceStamp16()` and/or `TriceStamp32()`. Normally they return a µs or ms tick count but any values are allowed.
+It is up to the user to provide the functions `TriceStamp16` and/or `TriceStamp32`. Normally they return a µs or ms tick count but any values are allowed.
 
 <p align="right">(<a href="#top">back to top</a>)</p>
 
@@ -1476,7 +1476,7 @@ It is up to the user to provide the functions `TriceStamp16()` and/or `TriceStam
   | `10iiiiiiI 10iiiiiiI TT NC ...`    |           2            | First 16bit are doubled. Info over `-d16` trice switch. | `u16 u16 u16 u16 [uW] ... [uW]` |
   | _________ `11iiiiiiI TT TT NC ...` |           3            | >= 4-byte message, *Trice* format with 32-bit stamp     | ___ `u16 u32 u16 [uW] ... [uW]` |
 
-- The stamp selector `2` encoding has 2 possibilities. When using `TRICE_SEGGER_RTT_32BIT_DIRECT_WRITE` or encryption, for alignment reasons the first 16bit ID field is doubled. The trice tool discards these 2 doubled bytes when the CLI switch `-d16` is given or encryption is active.
+- The stamp selector `2` encoding has 2 possibilities. When using `TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE` or encryption, for alignment reasons the first 16bit ID field is doubled. The trice tool discards these 2 doubled bytes when the CLI switch `-d16` is given or encryption is active.
 - Default endianness is little endian as most MCUs use little endianness. Otherwise the `-triceEndianness=bigEndian` CLI switch is needed.
 - The receiving tool evaluates firstly the 2 stamp bits and follows some rules:
     - 0: reserved -> ignore the whole package (discard) or treat it as user data.

examples/MDK-ARM_STM32F030R8_instrumented/Core/Inc/SEGGER_RTT_Conf.h

@@ -92,7 +92,7 @@ Revision: $Rev: 24316 $
 #endif
 
 #ifndef   BUFFER_SIZE_UP
-  #define BUFFER_SIZE_UP                            (256)  // Size of the buffer for terminal output of target, up to host (Default: 1k)
+  #define BUFFER_SIZE_UP                            (1024)  // Size of the buffer for terminal output of target, up to host (Default: 1k)
 #endif
 
 #ifndef   BUFFER_SIZE_DOWN