# Trice User Manual
```diff
---> To Long To Readβ
+--> To Long To Read - use it as reference onlyβ
+ Speed of Light `printf` Comfort Within Interrupts And Everywhere +
```
-
-
---
+
Table of Contents
+(click to expand)
-
-
Table of Contents
-
-
-
+into a source file of your project. The `8` stands here for 8 bit values (`16`, `32` and `64` also possible). Values of mixed size up to 32-bit size are allowed in one `trice` macro, so you can use Trice consequently to match most cases for the prize of little data overhead.
---
-## 9. Trice tool in logging action
-
+## 11. Trice tool in logging action
+
With `trice log -port COM12` you can visualize the trices on the PC, if for example `COM12` is receiving the data from the embedded device at the 115200 default baudrate.
@@ -1265,75 +1195,11 @@ The following capture output comes from an (old) example project inside [../exam
See [../_test/testdata/triceCheck.c](../_test/testdata/triceCheck.c) for reference. The *Trices* can come mixed from inside interrupts (light blue `ISR:...`) or from normal code. For usage with a RTOS, *Trices* are protected against breaks (`TRICE_ENTER_CRITICAL_SECTION`, `TRICE_LEAVE_CRITICAL_SECTION`). Regard the differences in the read SysTick values inside the GIF above These differences are the MCU clocks needed for one trice (~0,25Β΅s@48MHz).
-Use the `-color off` switch for piping output in a file. More convenient is the `-lf auto` switch.
-
-
+Use the `-color off` switch for piping output in a file. More convenient is the `-lf auto` switch.
-## 10. Encryption
+## 12. Encryption
* You can deliver your device with encrypted trices. This way only the service [wo]men is able to read the *Trices*.
* Implemented is [XTEA](https://en.wikipedia.org/wiki/XTEA) but this is exchangeable.
@@ -1344,10 +1210,10 @@ Quick workaround:
-## 11. Trice Command Line Interface & Examples
+## 13. Trice Command Line Interface & Examples
The trice tool is very easy to use even it has a plenty of options. Most of them normally not needed.
-The trice tool can be started in several modes (sub-commands), each with several mandatory or optional switches. Switches can have parameters or not.
+The trice tool can be started in several modes (sub-commands), each with several mandatory or optional switches. Switches can have a single parameter string or not.
```b
trice sub-command -switch1 -switch2 parameter -switch3 ...
@@ -1360,7 +1226,7 @@ Info for a special sub-command is shown with `trice help -log` for example.
* The command history is usable for example inside the bash, simply enter CTRL-R and start typing `trice...` and you can select from the history.
* The most convenient way is to use trice inside scripts like in [this](../examples/L432_inst/build.sh) example.
-### 11.1. Common information
+### 13.1. Common information
* `trice h -all` shows all options of the current version.
* `trice ver` prints version information.
@@ -1369,16 +1235,14 @@ Info for a special sub-command is shown with `trice help -log` for example.
* Use log witch `-s[howInputBytes]` to check if any bytes are received at all. 
* With `-debug` you can see the [T]COBS packages and decoded Trice packages. 
-
-### 11.2. Further examples
+### 13.2. Further examples
-#### 11.2.1. Automated pre-build insert command example
+#### 13.2.1. Automated pre-build insert command example
* Scan directories `../src`, `../lib/src` and `./` to insert the IDs there and extend list file `../../../til.json`
@@ -1388,7 +1252,7 @@ trice i -v -i ../../../til.json -src ../src -src ../lib/src -src ./
This is a typical line you can add to your project as an automatic pre-compile step.
-#### 11.2.2. Some Log examples
+#### 13.2.2. Some Log examples
* Log trice messages on COM3 8N1 115200 baud
@@ -1402,7 +1266,7 @@ trice log -i ./myProject/til.json -p=COM3
trice l -s COM3 -baud=9600
```
-#### 11.2.3. Logging over a display server
+#### 13.2.3. Logging over a display server
* Start displayserver on ip 127.0.0.1 (localhost) and port 61497
@@ -1422,7 +1286,7 @@ trice l -ds -p COM3
trice sd -r 192.168.1.23:45678
```
-#### 11.2.4. Logfile output
+#### 13.2.4. Logfile output
```bash
trice l -p COM3 -logfile auto
@@ -1438,7 +1302,7 @@ This creates a new logfile `trice.log` on first start and appends to it on each
Logfiles are text files one can see with 3rd party tools. Example: `cat trice.log`. They contain also the PC reception timestamps if where enabled.
-#### 11.2.5. Binary Logfile
+#### 13.2.5. Binary Logfile
```bash
trice l -p COM3 -binaryLogfile auto
@@ -1458,7 +1322,7 @@ Binary logfiles are handy in the field for long data recordings.
When using RTT, the data are exchanged over a file interface. These binary logfiles are stored in the project [./temp] folder and accessable for later view: `trice l -p FILEBUFFER -args ./temp/logfileName.bin`. Of course the host timestamps are the playing time then.
-#### 11.2.6. TCP output
+#### 13.2.6. TCP output
```bash
trice l -p COM3 -tcp 127.0.0.1:23
@@ -1469,7 +1333,7 @@ This additionally sends Trice output to a 3rd party TCP listener, for example li
 
-#### 11.2.7. TCP input
+#### 13.2.7. TCP input
```bash
trice l -p TCP4 -args "192.168.2.3:45678"
@@ -1477,41 +1341,27 @@ trice l -p TCP4 -args "192.168.2.3:45678"
This expects a TCP4 server at IP address `192.168.2.3` with port number `45678` to read binary Trice data from.
-
-
-#### 11.2.8. Stimulate target with a user command over UART
+#### 13.2.8. Stimulate target with a user command over UART
Sometimes it is handy to stimulate the target during development. For that a 2nd screen is helpful what is possible using the display server option:
-#### 11.2.9. Explpore and modify tags and their colors
+#### 13.2.9. Explpore and modify tags and their colors
See chapter [Trice Tags and Color](#trice-tags-and-color).
-#### 11.2.10. Location Information
+#### 13.2.10. Location Information
When running `trice insert`, a file `li.json` is created, what you can control with the `-li|locationInformation` switch. During logging, when `li.json` is found, automatically the filename and line number is displayed in front of each log line, controllable with the `-liFmt` switch. This information is correct only with the right version of the `li.json` file. That is usually the case on the PC during development. Out in the field only the `til.json` reference is of importance. It serves as an accumulator of all firmware versions and usually the latest version of this file is the best fit. The `li.json` file should stay with the software developer only and needs no version control in the usual case because it is rebuild with each compilation, when `trice i` is a prebuild step. When `trice clean` is used, the file `li.json` should go into the version management too to secure that identical trices get the same ID back.
+## 14. Limitations
-## 12. Limitations
+### 14.1. Permanent Limitations
-### 12.1. Permanent Limitations
-
-#### 12.1.1. Limitation TRICE in TRICE not possible
+#### 14.1.1. Limitation TRICE in TRICE not possible
* No-Good Example:
@@ -1531,9 +1381,9 @@ int f0( void ){ TRICE( "msg:f0\n"); return 0; }
void f1( void ){ int x = f0(); TRICE( "Yes: %d", x ); }
```
-### 12.2. Current Limitations
+### 14.2. Current Limitations
-#### 12.2.1. String Concatenation Within TRICE Macros Not Possible
+#### 14.2.1. String Concatenation Within TRICE Macros Not Possible
String concatenation within TRICE macros does not work. The reason lays inside the way the trice tool parser works:
@@ -1543,44 +1393,13 @@ void f0( void ){ TRICE( "msg:" ## "Hello\n" ); } // ERROR!
To implement this would need to build a trice preprocessor or to run the C preprocessor first and to modify the preprocessor output with the trice tool. That would make things unneccessary complicate and fragile for now.
-
-#### 12.2.2. Limited Trice Parser Capabilities
+#### 14.2.2. Limited Trice Parser Capabilities
The Trice tool internal parser has only limited capabilities. In works well in most cases, but could led to problems in some cases. The compiler run will for sure end up with some error messages in the following examples, so the developer can fix the code.
-
-
An example, provided by [@KammutierSpule](https://github.com/kammutierspule), is this:
- - started from a empty li.json/til.json
+* started from a empty li.json/til.json
```C
void trice0_test() {
@@ -1590,7 +1409,7 @@ void trice0_test() {
}
```
- * run `trice insert`
+* run `trice insert`
```C
void trice0_test() {
@@ -1602,366 +1421,178 @@ void trice0_test() {
As said, the compiler will complain about that in any case.
-
+* use several printf-calls
+* Use triceB and its relatives
+
+
Float Numbers
- +* surround each with `aFloat()` - - - +All the string literals (i.e. compile-time known strings) should be put inside the format string. +Only the dynamic strings should be used as variables in triceS macro for best performance. -## 13. Additional hints +## 15. Additional hints -### 13.1. Pre-built executables are available +### 15.1. Pre-built executables are available See [https://github.com/rokath/trice/releases](https://github.com/rokath/trice/releases). -### 13.2. Configuration file triceConfig.h +### 15.2. Configuration file triceConfig.h * When setting up your first project you need a `triceConfig.h` file. -* You should **not** use the `./_test/cgo.../triceConfig.h` directly, because these are customized for internal tests with CGO. But you can use their settings as helper for a starting point. -* Please choose one of these files as starting point: - * [../examples/F030_inst/Core/Inc/triceConfig.h](../examples/F030_inst/Core/Inc/triceConfig.h) - * [../examples/G0B1_inst/Core/Inc/triceConfig.h](../examples/G0B1_inst/Core/Inc/triceConfig.h) - * [../examples/L432_inst/Core/Inc/triceConfig.h](../examples/L432_inst/Core/Inc/triceConfig.h) -* Comparing them and understandig the differences helps quick starting. -* The file [triceDefaultConfig.h](../src/triceDefaultConfig.h) contains all possible config keys with descriptions. - -### 13.3. Setting up the very first connection - -If you see nothing in the beginning, what is normal ;-), add the `-s` (`-showInputBytes`) switch to see if any data arrive. There is also a switch `-debug` showing you the received packages, if you are interested in. - -### 13.4. Avoid buffer overruns - -It is your responsibility to produce less data than transmittable. If this is not guarantied, a data loss is not avoidable or you have to slow down the user application. The buffers have an optional overflow protection (`TRICE_PROTECT`), which is enabled by default. Recommendation: Make the buffer big and emit the maxDepth cyclically, every 10 or 1000 seconds. Then you know the needed size. It is influenced by the max Trice data burst and the buffer switch interval. See [./examples/exampleData/triceLogDiagData.c](../examples/exampleData/triceLogDiagData.c) for help. - -If the target application produces more Trice data than transmittable, a buffer overrun can let the target crash, because for performance reasons no overflow check is implemented in versions before v0.65.0. Such a check is added now per default using `TRICE_PROTECT`, but the Trice code can only throw data away in such case. Of course you can disable this protection to get more speed. - -Configuring the ring buffer option with `TRICE_PROTECT == 0` makes buffer overruns not completely impossible, because due to partial Trice log overwrites, false data are not excluded anymore and overwriting the buffer boundaries is possible, because of wrong length information. Also losses will occur when producing more data than transmittable. This is detectable with the cycle counter. The internal 8-bit cycle counter is usually enabled. If Trice data are lost, the receiver side will detect that because the cycle counter is not as expected. There is a chance of 1/256 that the detection does not work for a single case. You can check the detection by unplugging the trice UART cable for a time. Also resetting the target during transmission should display a cycle error. - -Gennerally it is recommended to enable `TRICE_PROTECT` during development and to disable it for performance, if you are 100% sure, that not more data are producable than transmittable. - -Important to know: If the `TRICE_PROTECT` code inhibits the writing into a buffer, there will be later no cycle error because a non existing Trice cannot cause a cycle error. Therefore the `TriceDirectOverflowCount` and `TriceDeferredOverflowCount` values exist, which could be monitored. - -### 13.5. Buffer Macros - -(Examples in [../_test/testdata/triceCheck.c](../_test/testdata/triceCheck.c)) - -| Macro Name | Description | -|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `triceS` \|`TriceS` \|`TRiceS` \|`TRICE_S` | Output of runtime generated 0-terminated strings. | -| `triceN` \|`TriceN` \|`TRiceN` \|`TRICE_N` | Is for byte buffer output as string until the specified size. It allows limiting the string size to a specific value and does not rely on a terminating 0. If for example len = 7 is given and "Hello\0World\n" is in the buffer, the byte sequence "Hello\0W" is transmitted but the trice tool probably shows only "Hello". | -| `trice8B` \|`Trice8B` \|`TRice8B` \|`TRICE8_B` | Is for byte buffer output according to the given format specifier for a single byte. | -| `trice16B`\|`Trice16B`\|`TRice16B`\|`TRICE16_B` | Is for 16-bit buffer output according to the given format specifier for a 16-bit value. | -| `trice32B`\|`Trice32B`\|`TRice32B`\|`TRICE32_B` | Is for 32-bit buffer output according to the given format specifier for a 32-bit value. | -| `triceB` \|`TriceB` \|`TRiceB` \|`TRICE_B` | Is buffer output according to the given format specifier for a default unit according to configuration (8 | 16 | 32-bit value). | - -### 13.6. Logfile viewing - -Logfiles, Trice tool generated with sub-command switch `-color off`, are normal ASCII files. If they are with color codes, these are ANSI escape sequences. - -* Simply `cat trice.log`. One view option is also `less -R trice.log`. The Linux command `less` is also available inside the windows git bash. -* Under Windows one could also download and use [ansifilter](https://sourceforge.net/projects/ansifilter/) for logfile viewing. A monospaced font is recommended. -* See also [Color issues under Windows](#color-issues-under-windows) - -### 13.7. Using the Trice tool with 3rd party tools - -Parallel output as logfile, TCP or binary logfile is possible. See examples above. - -### 13.8. Several targets at the same time - -You can connect each target over its transmit channel with an own Trice instance and integrate all transmissions line by line in an additional Trice instance acting as display server. See [https://github.com/rokath/trice#display-server-option](https://github.com/rokath/trice#display-server-option). - - - -The C-code is executed during some tests. Prerequisite is an installed GCC. - -### 13.9. TRICE_STACK_BUFFER could cause stack overflow with -o0 optimization - -As discussed in [issue #294](https://github.com/rokath/trice/issues/294) it can happen, that several TRICE macros within one function call increase the stack usage more than expected, when compiler optimization is totally switched off. - -### 13.10. Cycle Counter - -* The trice tool expects the first cycle counter to start with 0xC0 (=192). If the target is already running and you connect the trice tool then, the first message is marked with "CYCLE: ? not equal expected value 192 - adjusting. Now 1 CycleEvents". -* If the target is resetted asynchronous, the trice tool receives a cycle counter 192. Most probably the last cycle counter was not 191, so this triggers also a messageΒ with "CYCLE: 192 not equal expected value ?- adjusting. Now n CycleEvents". -* In the Trice tool is some heuristics to suppress such obvious false positives. - - - - -## 14. Switching Trice ON and OFF - - - -### 14.1. Target side compile-time Trice On-Off - -* 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: - -```C -#define TRICE_OFF 1 -#include "trice.h" -void fn(void) { - trice( iD(123), "Hi"); // Will generate code only, when TRICE_OFF == 0. - trice( "Lo"); // Will generate code only, when TRICE_OFF == 0. -} -``` - -With `#define TRICE_OFF 1` 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](../_test/testdata/til.json) these no code generating macros are regarded and go into (or stay inside) the ID reference list. - -* 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). - * User can add its own switches anywhere. - * The short Trice macro code is negligible. - * The trice output is encryptable, if needed. -* Because of the low Trice bandwidth needs and to keep the target code as clear as possible the runtime On-Off decision should be done by the Trice tool. - - - -### 14.2. Host side Trice On-Off - -* The PC Trice tool offers command line switches to `-pick` or `-ban` for Trice tags and will be extended with display switches. -* A Trice tool `-logLevel` switch is usable too. - - +### 15.8. Several targets at the same time - +The C-code is executed during some tests. Prerequisite is an installed GCC. -_### segger.com +### 15.9. TRICE_STACK_BUFFER could cause stack overflow with -o0 optimization -* Tooling around Segger RTT, Download latest version from SEGGER web site. +As discussed in [issue #294](https://github.com/rokath/trice/issues/294) it can happen, that several TRICE macros within one function call increase the stack usage more than expected, when compiler optimization is totally switched off. -_#### SEGGER downloaded Software +### 15.10. Cycle Counter -* Check in the Internet for newer versions. +* The trice tool expects the first cycle counter to start with 0xC0 (=192). If the target is already running and you connect the trice tool then, the first message is marked with "CYCLE: ? not equal expected value 192 - adjusting. Now 1 CycleEvents". +* If the target is resetted asynchronous, the trice tool receives a cycle counter 192. Most probably the last cycle counter was not 191, so this triggers also a messageΒ with "CYCLE: 192 not equal expected value ?- adjusting. Now n CycleEvents". +* In the Trice tool is some heuristics to suppress such obvious false positives. -_#### JLink -* Download and install [J-LinkSoftwareAndDocumentationPack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) or simply use `JLinkRTTLogger.exe` and accompanying `JLinkARM.dll` copied from default install location `C:\Program Files (x86)\SEGGER\JLink`. Both files are inside `JLinkRTTLogger.zip` You need to put to a location in \$PATH or extend \$PATH. + -_#### SEGGER_RTT +## 16. Switching Trice ON and OFF -* Target code is expected inside SEGGER_RTT. This is the extracted SEGGER_RTT_V....zip. -* Optionally check for a newer version. + -_#### STLinkReflash_190812.zip +### 16.1. Target side compile-time Trice On-Off -* Tool for exchanging ST-LINK and J-LINK software on STM32 evaluation boards. - * Works not for v3 Hardware but well for v2 Hardware. - * In case of not accepting the ST-Link firmware use [../st.com/en.stsw-link007_V2-37-26.zip](../st.com/en.stsw-link007_V2-37-26.zip) for updating the ST-Link firmware first. It could be you need to exchange the ST-Link firmware variant into the variant with mass storage. +* 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: - +```C +#define TRICE_OFF 1 +#include "trice.h" +void fn(void) { + trice( iD(123), "Hi"); // Will generate code only, when TRICE_OFF == 0. + trice( "Lo"); // Will generate code only, when TRICE_OFF == 0. +} +``` -_## st.com +With `#define TRICE_OFF 1` 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](../_test/testdata/til.json) these no code generating macros are regarded and go into (or stay inside) the ID reference list. -* STMicroelectronics +* 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). + * User can add its own switches anywhere. + * The short Trice macro code is negligible. + * The trice output is encryptable, if needed. +* Because of the low Trice bandwidth needs and to keep the target code as clear as possible the runtime On-Off decision should be done by the Trice tool. -_## Trice Version 1.0 Specification (Draft) +### 16.2. Host side Trice On-Off -_## Trice User Interface - Quick Start - ---> +* The PC Trice tool offers command line switches to `-pick` or `-ban` for Trice tags and will be extended with display switches. +* A Trice tool `-logLevel` switch is usable too. -## 15. Framing +## 17. Framing * Trice messages are framed binary data, if framing is not disabled. -* Framing is important for data disruption cases and is done with [TCOBS](https://github.com/rokath/tcobs) (has included data compression) 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. +* Framing is important for data disruption cases and is done with [TCOBS](https://github.com/rokath/tcobs) (has included data compression) 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 can get its own (T)COBS package (`TRICE_DEFERRED_TRANSFER_MODE == TRICE_SINGLE_PACK_MODE`). That is configurable for transfer data reduction. Use `#define TRICE_DEFERRED_TRANSFER_MODE TRICE_MULTI_PACK_MODE` inside `triceConfig.h` (is now default). 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. -## 16. Optional XTEA Encryption +## 18. Optional XTEA Encryption * If XTEA is used, the encrypted packages have a multiple-of-8 byte length containing 1-7 padding bytes. * The optional decryption is the next step after unpacking a data frame. @@ -1969,7 +1600,7 @@ _## Trice User Interface - Quick Star -## 17. Endianness +## 19. Endianness * To interpret a decoded package, itΒ΄s endianness needs to be known. * For efficiency, binary trice data are normally stored and transmitted in MCU endianness and the Trice tool expects binary data in little endian format as most MCUs are little endian. @@ -1979,7 +1610,7 @@ _## Trice User Interface - Quick Star -## 18. Trice (Time)Stamps +## 20. Trice (Time)Stamps * Each Trice message can carry stamp bits, which are free usable like for time, addressing or filtering. * By selecting the letter case (**tr**ice, **Tr**ice, **TR**ice) you decide for each single Trice macro about the stamp size. @@ -2005,9 +1636,9 @@ It is up to the user to provide the functions `TriceStamp16` and/or `TriceStamp3 -## 19. Binary Encoding +## 21. Binary Encoding -### 19.1. Symbols +### 21.1. Symbols | Symbol | Meaning | |:-------:|------------------------------------------------------------------------------| @@ -2029,7 +1660,7 @@ It is up to the user to provide the functions `TriceStamp16` and/or `TriceStamp3 | `x` | unspecified bit | | `X` | =`xxxxxxxx` unspecified byte | -### 19.2. Package Format +### 21.2. Package Format * Because of the **TCOBS** or **COBS** package framing, the package sizes are detectable by the trice tool without additionlal length information. * All decoded frames of 0-, 1-, 2- and 3-byte size are considered as user data and ignored by the Trice tool. @@ -2064,18 +1695,27 @@ It is up to the user to provide the functions `TriceStamp16` and/or `TriceStamp3 * use ID to get parameters width `W`=8,16,32,64 from file *til.json* and and parameters count and convert appropriate. * Within one trice message the parameter bit width `W` does not change. +##### Framing with COBS or TCOBS encoding + +* For maximum storage speed each Trice message starts at a 32-bit boundary and has 1-3 padding bytes. +* In direct mode only a single message needs handling. +* In deferred mode after double buffer swap any count of trice messages is in the buffer. +* There are different policies possible: + 1. **TRICE_FAST_MULTI_MODE**: Compact buffer by removing all padding bytes, encode it as a single package, append one 0-delimiter and transmit. This allows to reduce the transmitted data amount by paying the price of possibly more data lost in case of an error. Also the data interpretation can perform less checks. + 2. **TRICE_SAFE_SINGLE_MODE**: Encode each buffer separate, append a 0-delimiter for each and pack them all together before transmitting. This increases the transmit data slightly but minimizes the amount of lost data in case of a data disruption. + -## 20. Trice Decoding +## 22. Trice Decoding The 14-bit IDs are used to display the log strings. These IDs are pointing in two reference files. -### 20.1. Trice ID list til.json +### 22.1. Trice ID list til.json * This file integrates all firmware variants and versions and is the key to display the message strings. With the latest version of this file all previous deployed firmware images are usable without the need to know the actual firmware version. * The files `til.json.h`, `til.json.c` and the like are generated to help writing an own trice decoder tool in your preferred language. Use `trice i -v` for it. That can be interesting in environments, where Go compiled binaries not executable, like [PCs running QNX OS](https://github.com/rokath/trice/discussions/263#discussioncomment-4180692). -### 20.2. Trice location information file li.json +### 22.2. Trice location information file li.json * If the generated `li.json` is available, the Trice tool automatically displays file name and line number. But that is accurate only with the exact matching firmware version. That usually is the case right after compiling and of most interest at the developers table. * The Trice tool will silently not display location information, if the `li.json` file is not found. For in-field logging, the option `-showID string` could be used. This allows later an easy location of the relevant source code. @@ -2083,9 +1723,9 @@ The 14-bit IDs are used to display the log strings. These IDs are pointing in tw -## 21. Trice ID Numbers +## 23. Trice ID Numbers -### 21.1. ID number selection +### 23.1. ID number selection * The default encoding TREX supports 14-bit IDs, so over 16000 IDs possible. Other encodings can work with other ID sizes. * `trice("Hi!\n");` β‘ `trice i` β‘ `trice( iD(12345), "Hi!\n");` β‘ `trice c` β‘ `trice("Hi!\n");` @@ -2099,19 +1739,14 @@ The 14-bit IDs are used to display the log strings. These IDs are pointing in tw * Example: `trice insert -IDMin 6000 -IDMax 6999` will choose new randomly IDs only between 6000 and 6999. * It is possible to give each Trice tag an **ID** range making it possible to implement Trice tag specific runtime on/off on the target side if that is needed. This could be interesting for routing purposes also. Please run `trice help -insert` and read about the `-IDRange` switch for more details. - - -### 21.2. ID number usage and stability +### 23.2. ID number usage and stability * If you write `trice( "msg:%d", 1);` again on a 2nd location, the copy gets a different **ID**, because each Trice gets its own **ID**. * If you change `trice( "msg:%d", 1);` to `trice8( "msg:%d", 1);`, to reduce the needed parameter space, a new **ID** is assigned. That is because the parameter bit width is implicit a part of the now changed Trice. If you change that back, the previous **ID** is assigned again. @@ -2124,33 +1759,29 @@ _### New Method to get a random ID * If the same string appears again in the same file this ID is active again. * If a trice occurs more than one time, each occurrence gets a different ID. If then 2 of them disappear, their ID numbers stay in `til.json`. If then one of them comes back, it gets its ID back. -### 21.3. Trice ID 0 +### 23.3. Trice ID 0 * The trice ID 0 is a placeholder for "no ID", which is replaced automatically during the next `trice insert` according to the used trice switches `-IDMethod`, `-IDMin` and `IDMax`. * It is sufficient to write the TRICE macros just without the `id(0),` `Id(0),` `ID(0),`. It will be inserted automatically according the `-stamp` switch. - - -## 22. Trice ID management +## 24. Trice ID management -### 22.1. *Trices* inside source code +### 24.1. Trice inside source code -#### 22.1.1. *Trices* in source code comments +#### 24.1.1. Trice in source code comments * Trice macros commented out, are **visible** for the `trice insert` command and therefore regarded. * Example: `// trice("Hi!\n");` is still regarded by the `trice i`. * During `trice insert` commented out Trice macros, are treated in the same way as active Trice macros. Even after deletion their content stays inside til.json. This is intensionally to get best stability across several firmware versions or variants. * The trice tool does treat trice statements inside comments or excluded by compiler switches also. -#### 22.1.2. Different IDs for same Trices +#### 24.1.2. Different IDs for same Trices -* When the same Trice is used several times with identical IDs, after copying, and `trice insert` is called, only one ID survives in the source code. +* When the same Trice is used several times with identical IDs, after copying, and `trice insert` is called, only one ID survives in the source code. -#### 22.1.3. Same IDs for different Trices +#### 24.1.3. Same IDs for different Trices * If duplicate ID's with different format strings found inside the source tree (case several developers or source code merging) one ID is replaced by a new ID. The probability for such case is low, because of the default random ID generation. * Also you can simply copy a Trice statement and modify it without dealing with the ID. @@ -2158,36 +1789,13 @@ _### New Method to get a random ID * That is done silently for you during the next `trice insert`. * When you use the Trice cache, the IDs are invisible and all happens in the background automatically. -#### 22.1.4. ID Routing - -With the Trice insert CLI switch `-IDRange` each Trice [tag](#tags,-color-and-log-levels) can get a specific ID range assigned and inside the project specific **triceConfig.h** the user can control, which ID range is routed to specific output channels. Search for `_MIN_ID` inside **triceDefaultConfig.h** and extend your search than for example `TRICE_UARTA_MIN_ID` to explore how to use. - - +With the Trice insert CLI switch `-IDRange` each Trice [tag](#tags,-color-and-log-levels) can get a specific ID range assigned and inside the project specific *triceConfig.h* the user can control, which ID range is routed to specific output channels. Search for `_MIN_ID` inside **triceDefaultConfig.h** and extend your search than for example `TRICE_UARTA_MIN_ID` to explore how to use. -## 23. ID reference list til.json +## 25. ID reference list til.json * The `trice insert` command demands a **til.json** file - it will not work without it. That is a safety feature to avoid unwanted file generations. If you are sure to create a new **til.json** file, create an empty one: `touch til.json`. * The name **til.json** is a default one. With the command line parameter `-i` you can use any filename. @@ -2196,7 +1804,7 @@ sub-command 'r|refresh': For updating ID list from source files but does not cha * One can delete the ID reference list when IDs inside the code. It will be reconstructed automatically from the source tree with the next `trice clean` command, but history is lost then. * Keeping obsolete IDs makes it more comfortable during development to deal with different firmware variants at the same time. -### 23.1. til.json Version control +### 25.1. til.json Version control * The ID list should go into the version control repository of your project. * To keep it clean from the daily development garbage one could delete the **til.json**, then check-out again and re-build just before check-in. A small script could do that. @@ -2206,7 +1814,7 @@ sub-command 'r|refresh': For updating ID list from source files but does not cha > For the no-ids option deleting **til.json** should not not be done when the sources are without IDs. That would result in a loss of the complete ID history and a assignment of a complete new set of IDs. -### 23.2. Long Time Availability +### 25.2. Long Time Availability * You could place a download link for the Trice tool and the used **til.json** list. * Link a compressed/encrypted **til.json** file as resource into the target binary and optionally get it back long years later in a safe way. @@ -2214,9 +1822,9 @@ sub-command 'r|refresh': For updating ID list from source files but does not cha -## 24. The Trice Insert Algorithm +## 26. The Trice Insert Algorithm -### 24.1. Starting Conditions +### 26.1. Starting Conditions * Before `trice i` is executed on a source tree, the starting conditions are partially undefined: * A trice ID list file `til.json` file must exist, but it is allowed to be empty. @@ -2244,7 +1852,7 @@ sub-command 'r|refresh': For updating ID list from source files but does not cha * One and only one position is used and relevant, all others are ignored. If no `li.json` exists on the expected location trice insert creates one there. * The src tree can contain IDs not present inside `til.json`. This state is seldom, for example after adding sources containing IDs. -### 24.2. Aims +### 26.2. Aims * The `trice insert` main aim is to have a consistent state between `til.json`, `li.json` and the source tree with no **ID** used twice. * Also the changes should be minimal. @@ -2254,9 +1862,9 @@ sub-command 'r|refresh': For updating ID list from source files but does not cha * To keep the [Trice ID management](#trice-id-management) simple, the `insert` operation acts "per file". That means, that in case a file is renamed or code containing trice statements is copied to an other file, new IDs are generated for the affectes trices. * File name changes occur are not that often, so tha should be acceptable. -### 24.3. Method +### 26.3. Method -#### 24.3.1. Trice Insert Initialization +#### 26.3.1. Trice Insert Initialization ```Go // insertIDsData holds the insert run specific data. @@ -2284,7 +1892,7 @@ type insertIDsData struct { * During STM creation use these rules: * If the next found f src ID == n != 0: * If ID n already inside STM set ID = 0 (that is brutal but ok) - * Otherwise extend STM with ID n and remove n from IDroom + * Otherwise extend STM with ID n and remove n from ID space * It is possible, f is used n times with different IDs, so that is no problem. * It is possible, f is used n times with the same ID, so the first occurrence is the winner. * If the next found f src ID == 0 (normal case after trice z): @@ -2307,35 +1915,12 @@ type insertIDsData struct { Until here the algorithm seem to be ok. - - * STM is not needed but maybe helpful during debugging. * STM than is usable to regenerate li.json and to extend til.json - -* If after `trice i` a `trice z` and a `trice i` again is executed, all IDs are expected to be at the same place again. If in between `trice i`, an optional `trice z`and a `trice i` src was edited, most IDs are expected to be at the same place again. - +* If after `trice i` a `trice c` and a `trice i` again is executed, all IDs are expected to be at the same place again. If in between `trice i`, an optional `trice c`and a `trice i` src was edited, most IDs are expected to be at the same place again. -### 24.4. User Code Patching (trice insert) +### 26.4. User Code Patching (trice insert) * A Trice **ID** is inserted by `trice insert` as shown in the table: @@ -2360,7 +1945,7 @@ _### Tests * `trice i` in your project root expects a til.json file there and checks sources and **til.json** for changes to insert. * `trice i -v -i ../../../til.json -src ../src -src ../lib/src -src ./` is a typical case as automated pre-build step in your project settings telling Trice to scan the project dir and two external directories. Even `trice i` is fast, it is generally quicker to search only relevant places. -### 24.5. User Code Patching Examples +### 26.5. User Code Patching Examples * A Trice **ID** is modified as shown in these cases: * Previously inserted (patched) user code copied to a different location: @@ -2378,7 +1963,7 @@ _### Tests trice(iD( 1233), "Hi!\n"); // re-patched trice(iD( 1234), "Hi!\n"); // re-patched ``` - + * If the code is copied inside the same file, the first occurrence after the copy stays unchanged and the following are modified. * If the code is copied to other files only, the copies get new IDs. * Previously inserted (patched) user code copied and modified: @@ -2408,14 +1993,14 @@ _### Tests TRice( iD(12345), "Hi!" ); // manually changed stamp size and then "trice i" performed. ``` -### 24.6. User Code Un-Patching +### 26.6. User Code Un-Patching -### 24.7. ID Usage Options +### 26.7. ID Usage Options * Per default the `trice insert` command chooses randomly a so far unused ID for new format strings and extends `til.json`. * After `trice c` all src IDs are removed or 0. In this state the src should go into the version management system. - -### 24.8. General ID Management Information + +### 26.8. General ID Management Information * The trice ID-instead-of-String idea lives from pre-compile patching of the user code. * The user has full control how to deal with that. @@ -2423,204 +2008,24 @@ _### Tests * Each format string gets its unique trice ID. If the same format string is used on different source code locations it gets different trice IDs this way allowing a reliable location information. -### 24.9. Option Cleaning in a Post-build process +### 26.9. Option Cleaning in a Post-build process * The code is visually free of IDs all the time. -### 24.10. Option Let the inserted Trice ID be a Part of the User Code +### 26.10. Option Let the inserted Trice ID be a Part of the User Code * This is the legacy method. It allows unchanged src translation into code without using the trice tool. * It is very robust and maybe needed in nasty debugging situations. * It allows to reconstruct lost til.json information. * Recommendet for small projects. -### 24.11. Option Cleaning on Repository Check-In +### 26.11. Option Cleaning on Repository Check-In * The code is visually free of IDs only inside the repository. - - - - - - -## 25. Trice Speed +## 27. Trice Speed A Trice macro execution can be as cheap like **3 Assembler instructions or 6 processor clocks**: @@ -2635,7 +2040,7 @@ The MCU is clocked with 48 MHz and a Trice duration is about 2 Β΅s, where alone  -### 25.1. Target Implementation Options +### 27.1. Target Implementation Options All trice macros use internally this sub-macro: @@ -2645,7 +2050,7 @@ All trice macros use internally this sub-macro: The usual case is `#define TRICE_HTOTL(x) (x)`. The `uint32_t* TriceBufferWritePosition` points to a buffer, which is codified and used with the Trice framing sub-macros `TRICE_ENTER` and `TRICE_LEAVE` in dependence of the use case. -#### 25.1.1. Trice Use Cases TRICE_STATIC_BUFFER and TRICE_STACK_BUFFER - direct mode only +#### 27.1.1. Trice Use Cases TRICE_STATIC_BUFFER and TRICE_STACK_BUFFER - direct mode only 1. Each singe Trice is build inside a common buffer and finally copied inside the sub-macro `TRICE_LEAVE`. 2. Disabled relevant interrupts between `TRICE_ENTER` and `TRICE_LEAVE` are mantadory for `TRICE_STATIC_BUFFER`. @@ -2658,7 +2063,7 @@ The usual case is `#define TRICE_HTOTL(x) (x)`. The `uint32_t* TriceBufferWriteP * AUX without extra copy. * Not (yet) supported UART transfer loop with polling. With 1MBit baud rate, 4-12 bytes would last 40-120 Β΅s. -#### 25.1.2. Trice Use Case TRICE_DOUBLE_BUFFER - deferred mode, fastest Trice execution, more RAM needed +#### 27.1.2. Trice Use Case TRICE_DOUBLE_BUFFER - deferred mode, fastest Trice execution, more RAM needed 1. Several *trices* are build in a half buffer. 1. No stack used. @@ -2666,7 +2071,7 @@ The usual case is `#define TRICE_HTOTL(x) (x)`. The `uint32_t* TriceBufferWriteP 1. Usable for multiple blocking and non-blocking physical Trice channels. 1. No copy call inside `TRICE_LEAVE` but optionally an additional direct mode is supported. -#### 25.1.3. Trice Use Case βTRICE_RING_BUFFER - deferred mode, balanced Trice execution time and needed RAM +#### 27.1.3. Trice Use Case βTRICE_RING_BUFFER - deferred mode, balanced Trice execution time and needed RAM 1. Each single *trices* is build in a ring buffer segment. 1. No stack used. @@ -2677,97 +2082,11 @@ The usual case is `#define TRICE_HTOTL(x) (x)`. The `uint32_t* TriceBufferWriteP +## 28. Trice memory needs -## 26. Trice Cache for Compilation Speed - -The `trice insert` and `trice clean` commands are parsing and modifying the source code files. Even this is a reasonable fast procedure, this could get time consuming on large projects, especially when using these commands as permanent pre-compile and post-compile steps. It is assumed, that usually between 2 compile steps not all project files are changed. The project files majority will stay unchanged despite the ID insertion and removal. This repeated parsing and modifying of unchanged source code is avoidable with the Trice cache technique. Also it could get anoying to recompile files all the time only because they got Trice IDs removed and inserted. With the Trice cache we get also a solution not to re-compile un-edited files as well. - - - -### 26.1. Trice Cache Logic - -When `id.TriceCacheEnabled` is true (applied `-cache` CLI switch) and the folder `~/.trice/cache` exists, we have -* optionally a _cleaned cache file_ `~/.trice/cache/cleaned/fullpath/file` with mtime of _IDs cleaned_ -* optionally an _inserted cache file_ `~/.trice/cache/inserted/fullpath/file` with mtime of _IDs inserted_ -* `fullpath/file` with mtime of _IDs cleaned_ **OR** _IDs inserted_ **OR** _last edit_. When mtime of `path/file` is: - * _IDs cleaned_: - * On command `trice c`, nothing to do - * On command `trice i`, copy, if existing, _inserted cache file_ into `fullpath/file`. Otherwise process `trice i` and copy result into _inserted cache file_. - * _IDs inserted_: - * On command `trice c`, copy, if existing, _cleaned cache file_ into `fullpath/file`. Otherwise process `trice c` and copy result into _cleaned cache file_. - * On command `trice i`, nothing to do - * _last edit_: - * On command `trice c`, invalidate cache, process `trice c` and update _cleaned cache file_, file gets a new mtime, the mtime of _IDs cleaned_. On a following command `trice i`, file mtime is _IDs cleaned_, BUT the cache is invalid, so process `trice i` and update cache/inserted. - * On command `trice i`, invalidate cache, process `trice i` and update _inserted cache file_, file gets a new mtime, the mtime of _IDs inserted_. On a following command `trice c`, file mtime is _IDs inserted_, BUT the cache is invalid, so process `trice c` and update cache/cleaned. - -### 26.2. Trice Cache Remarks - -* `fullpath/file` means `/home/me/proj3/file` for example. When copied to the cache, the real "fullpath" is there `/home/me/.trice/cache/cleaned/home/me/proj3/file`. - -> Should the `.trice/cache` be better located inside the project folder? What, if the user has several projects and several users on the same machine working on projects together? What about libraries containing trice code? - -* The `~/.trice/cache` folder should the Trice tool **not** create automatically in the users home folder `$HOME`. The existence of this folder is user controlled. The folder must exist. If several users work on the same project and some use the cache and some not - it is is possible this way, even build scripts are shared. -* The `~/.trice/cache` folder should **not** go under revision control. -* A CLI switch `-cache` does enable/disable the Trice cache. Default is off. -* The user should consider what happens, if other pre-compile or post-compile steps are modifying files as well, before enabling the Trice cache. - -### 26.3. Trice Cache Tests - -Nr | Action | cCache | iCache | ID state | Edid state | Test function -------|----------|---------|---------|------------|------------|------------------------------------------------------------------------------ -0,1 | 0:clean | 0:inval | 0:inval | 0:cleaned | X:any | Test_0_1_0000X_clean_on_invalid_cCache_invalid_iCache_cleaned_file -2,3 | 0:clean | 0:inval | 0:inval | 1:inserted | X:any | Test_2_3_00011_clean_on_inalid_cCache_invalid_iCache_inserted_edited_file -4,5 | 0:clean | 0:inval | 1:valid | 0:cleaned | X:any | Test_4_5_0010X_clean_on_invalid_cCache_valid_iCache_cleaned_file -6 | 0:clean | 0:inval | 1:valid | 1:inserted | 0:not | Test_6_00110_clean_on_invalid_cCache_valid_iCache_inserted_not_edited_file -7 | 0:clean | 0:inval | 1:valid | 1:inserted | 1:yes | Test_7_00111_clean_on_invalid_cCache_valid_iCache_inserted_edited_file -8 | 0:clean | 1:valid | 0:inval | 0:cleaned | 0:not | Test_8_01000_clean_on_valid_cCache_invalid_iCache_cleaned_not_edited_file -9 | 0:clean | 1:valid | 0:inval | 0:cleaned | 1:yes | Test_9_01001_clean_on_valid_cCache_invalid_iCache_cleaned_edited_file -10 | 0:clean | 1:valid | 0:inval | 1:inserted | 0:not | Test_10_01011_clean_on_valid_cCache_invalid_iCache_inserted_not_edited_file -11 | 0:clean | 1:valid | 0:inval | 1:inserted | 1:yes | Test_11_01011_clean_on_valid_cCache_invalid_iCache_inserted_edited_file -12 | 0:clean | 1:valid | 1:valid | 0:cleaned | 0:not | Test_12_01100_clean_on_valid_iCache_valid_cCache_clean_file_not_edited -13 | 0:clean | 1:valid | 1:valid | 0:cleaned | 1:yes | Test_13_01101_clean_on_valid_iCache_valid_cCache_clean_file_edited -14 | 0:clean | 1:valid | 1:valid | 1:inserted | 0:not | Test_14_01110_clean_on_valid_iCache_valid_cCache_inserted_file_not_edited -15 | 0:clean | 1:valid | 1:valid | 1:inserted | 1:yes | Test_15_01111_clean_on_valid_iCache_valid_cCache_inserted_file_edited -16,17 | 1:insert | 0:inval | 0:inval | 0:cleaned | X:any | Test_16_17_1000X_insert_on_invalid_cCache_invalid_iCache_cleaned_file -18,19 | 1:insert | 0:inval | 0:inval | 1:inserted | X:any | Test_18_19_1001X_insert_on_invalid_cCache_invalid_iCache_inserted_edited_file -20,21 | 1:insert | 0:inval | 1:valid | 0:cleaned | X:any | Test_20_21_1010X_insert_on_invalid_cCache_valid_iCache_cleaned_file -22 | 1:insert | 0:inval | 1:valid | 1:inserted | 0:not | Test_22_10100_insert_on_invalid_cCache_valid_iCache_inserted_not_edited_file -23 | 1:insert | 0:inval | 1:valid | 1:inserted | 1:yes | Test_23_10101_insert_on_invalid_cCache_valid_iCache_inserted_edited_file -24 | 1:insert | 1:valid | 0:inval | 0:cleaned | 0:not | Test_24_11000_insert_on_valid_cCache_invalid_iCache_cleaned_not_edited_file -25 | 1:insert | 1:valid | 0:inval | 0:cleaned | 1:yes | Test_25_11001_insert_on_valid_cCache_invalid_iCache_cleaned_edited_file -26,27 | 1:insert | 1:valid | 0:inval | 1:inserted | X:any | Test_26_27_1010X_insert_on_invalid_cCache_valid_iCache_cleaned_file -28 | 1:insert | 1:valid | 1:valid | 0:cleaned | 0:not | Test_28_11100_insert_on_valid_cCache_valid_iCache_cleaned_not_edited_file -29 | 1:insert | 1:valid | 1:valid | 0:cleaned | 1:yes | Test_29_11100_insert_on_valid_cCache_valid_iCache_cleaned_edited_file -30 | 1:insert | 1:valid | 1:valid | 1:inserted | 0:not | Test_30_11110_insert_on_valid_cCache_valid_iCache_inserted_not_edited_file -31 | 1:insert | 1:valid | 1:valid | 1:inserted | 1:yes | Test_31_11111_insert_on_valid_cCache_valid_iCache_inserted_edited_file - -### 26.4. Possible Trice Cache Editor-Issues And How To Get Around - -* When a `trice i -cache && make && trice c -cache` sequence is executed, it could happen that the editor-view is not refreshed for opened and unedited files containing Trice statements. - * It looks like the Trice IDs were not cleaned. - * Closing and opening the file again shows, that the Trice IDs are indeed cleaned. - * If the file is edited then without refreshing the view, that means with the shown Trice IDs, this is no problem, because after saving the edited file, it gets processed anyway, so no data loss is possible. - * An automatic view refresh (close & open) for the editor could help here. But how to do that in an universal way? -* A workaround is, at least for vsCode, to first run `trice clean` in the build script. - * See `trice/examples/G0B1_inst/build.sh` for an implementation. - - - -## 27. Trice memory needs - -### 27.1. Trice Space example +### 28.1. Trice Space example -* STM32CubeMX generated empty default project: `Program Size: Code=2208 RO-data=236 RW-data=4 ZI-data=1636` +* STM32CubeMX generated empty default project: `Program Size: Code=2208 RO-data=236 RW-data=4 ZI-data=1636` * Same project with default `Trice` instrumentation: `Program Size: Code=2828 RO-data=236 RW-data=44 ZI-data=1836` * Needed [FLASH memory](https://en.wikipedia.org/wiki/Flash_memory): 620 Bytes * Needed [RAM](https://en.wikipedia.org/wiki/Random-access_memory): 40 Bytes plus 200 Bytes for the 2 times 100 Bytes double buffer @@ -2777,7 +2096,7 @@ Nr | Action | cCache | iCache | ID state | Edid state | Test function * No format strings go into the target code anymore. * In general Trice instrumentation **reduces** the needed memory compared to a printf-like implementation. -### 27.2. Memory needs (Legacy ARM example project) +### 28.2. Memory needs (Legacy ARM example project) The following numbers are measured with a legacy encoding, showing that the instrumentation code can be even smaller. @@ -2792,7 +2111,7 @@ The following numbers are measured with a legacy encoding, showing that the inst * The about 50 trices in TriceCheckSet() allocate roughly 2100 (fast mode) or 1500 (small mode) bytes. * trices are removable without code changes with `#define TRICE_OFF 1` before `incude "trice.h"` on file level or generally on project level. -### 27.3. Memory needs (example projects) +### 28.3. Memory needs (example projects) | Project | Compiler | Optimization | Link-Time-Optimization | Result | Remark | |--------------------------------|-------------|--------------|------------------------|-----------------------------------------------|--------------------------------------------------------------------| @@ -2803,17 +2122,17 @@ The following numbers are measured with a legacy encoding, showing that the inst -## 28. Trice Project Image Size Optimization +## 29. Trice Project Image Size Optimization -Modern compilers are optimizing out unused code automatically, but you can help to reduce trice code size if your compiler is not perfect. +Modern compilers are optimizing out unused code automatically, but you can help to reduce trice code size if your compiler is not perfect. -### 28.1. Code Optimization -o3 or -oz (if supported) +### 29.1. Code Optimization -o3 or -oz (if supported) -For debugging it could be helpful to switch off code optimization what increases the code size. A good choice is `-o1`. See also +For debugging it could be helpful to switch off code optimization what increases the code size. A good choice is `-o1`. See also [TRICE_STACK_BUFFER could cause stack overflow with -o0 optimization](#direct-trice-out-(trice_mode-trice_stack_buffer)-could-cause-stack-overflow-with--o0-optimization). -### 28.2. Compiler Independent Setting +### 29.2. Compiler Independent Setting Maybe the following is a bit unhandy but it decreases the code amount, build time and the image size. @@ -2821,45 +2140,45 @@ Maybe the following is a bit unhandy but it decreases the code amount, build tim * For **X=8|16|32|64** and **N=0...12** selectively set `#define ENABLE_Trice`**X**`fn_`**N**` 1` to ` 0` for unused functions in project specific file `triceConfig.h`. * For **X=8|16|32|64** and **N=0...12** selectively set `#define ENABLE_TRice`**X**`fn_`**N**` 1` to ` 0` for unused functions in project specific file `triceConfig.h`. -When having lots of program memory simply let all values be `1`. With specific linker optimization unused functions can get stripped out automatically. +When having lots of program memory simply let all values be `1`. With specific linker optimization unused functions can get stripped out automatically. It is possible to `#define TRICE_SINGLE_MAX_SIZE 12` for example in *triceConfig.h*. This automaticaly disables all Trice messages with payloads > 8 bytes (Trice size is 4 bytes). -### 28.3. Linker Option --split-sections (if supported) +### 29.3. Linker Option --split-sections (if supported) In ARM-MDK uVision `Project -> Options -> C/C++ -> "One EFL section for each function"` allows good optimization and getting rid of unused code without additional linker optimization. This leads to a faster build process and is fine for most cases. It allows excluding unused functions. -### 28.4. Linker Optimization -flto (if supported) +### 29.4. Linker Optimization -flto (if supported) * To get the smallest possible image, do _not_ use option `--split sections`. * Use linker optimization alone. * This increases the build time but reduces the image size significantly. -#### 28.4.1. ARMCC compiler v5 "Linker Feedback" +#### 29.4.1. ARMCC compiler v5 "Linker Feedback" * In ARM-MDK uVision, when using ARMCC compiler v5, there is a check box `Project -> Options -> Target -> "Cross Module Optimization"`. * In ARMCC this works also with the lite version. -#### 28.4.2. ARMCLANG compiler v6 "Link-Time Optimization" +#### 29.4.2. ARMCLANG compiler v6 "Link-Time Optimization" -* In ARM-MDK uVision, when using ARMCLANG compiler v6, the check box `Project -> Options -> C/C++(AC6) -> "Link-Time Optimization"` is usable to set the CLI `-flto` switch. +* In ARM-MDK uVision, when using ARMCLANG compiler v6, the check box `Project -> Options -> C/C++(AC6) -> "Link-Time Optimization"` is usable to set the CLI `-flto` switch. * LTO is not possible with ARMCLANG6 lite: https://developer.arm.com/documentation/ka004054/latest. -#### 28.4.3. GCC +#### 29.4.3. GCC With GCC use the `-flto` CLI switch directly. -#### 28.4.4. LLVM ARM Clang +#### 29.4.4. LLVM ARM Clang This compiler is much faster and creates the smallest images. Right now it uses the GCC libs and linker. -#### 28.4.5. Other IDEΒ΄s and compilers +#### 29.4.5. Other IDEΒ΄s and compilers Please check the manuals and create a pull request or simply let me know. -### 28.5. Legacy STM32F030 Example Project - Different Build Sizes +### 29.5. Legacy STM32F030 Example Project - Different Build Sizes -#### 28.5.1. ARMCC compiler v5 +#### 29.5.1. ARMCC compiler v5 | Compiler | Linker | Result | Comment | |----------|----------------|-------------------------------------------------|-----------------------------------| @@ -2875,9 +2194,9 @@ Please check the manuals and create a pull request or simply let me know. -## 29. Trice Tags and Color +## 30. Trice Tags and Color -### 29.1. How to get +### 30.1. How to get * Add a tag name as color descriptor in front of each Trice format string like `"wrn:Peng!"`. * In file [../internal/emitter/lineTransformerANSI.go](../internal/emitter/lineTransformerANSI.go) the colors are changeable and additional color tags definable. @@ -2889,14 +2208,14 @@ Please check the manuals and create a pull request or simply let me know. * The Trice tool, if knowing `wrn:` as pattern, prepends the appropriate color code. It removes the sequence `wrn:`, if it is known and completely lower case. * The user can define any pattern with any color code to create colored output with the Trice tool. * There is no tag enable switch inside the target code. It would need a back channel and add overhead. -* An option using tag specific ID ranges with optional routing exists. -* The Trice tool offers the 2 command line switches `-pick` and `-ban` to control tag visualization during runtime. +* An option using tag specific ID ranges with optional routing exists. +* The Trice tool offers the 2 command line switches `-pick` and `-ban` to control tag visualization during runtime. -#### 29.1.1. Output options +#### 30.1.1. Output options  -#### 29.1.2. Check Alternatives +#### 30.1.2. Check Alternatives There are over 1000 possibilities: @@ -2904,13 +2223,13 @@ There are over 1000 possibilities: Only file [../internal/emitter/lineTransformerANSI.go](../internal/emitter/lineTransformerANSI.go) needs to be changed and the Trice tool needs to be rebuild afterwards: `go install ./...`. -### 29.2. Color issues under Windows +### 30.2. Color issues under Windows **Currently console colors are not enabled by default in Win10**, so if you see no color but escape sequences on your powershell or cmd window, please refer to [Windows console with ANSI colors handling](https://superuser.com/questions/413073/windows-console-with-ansi-colors-handling/1050078#1050078) or simply use a Linux like terminal under windows, like git-bash. One option is also to install Microsoft *Windows Terminal (Preview)* from inside the Microsoft store and to start the Trice tool inside there. Unfortunately this can not be done automatically right now because of missing command line switches. [Alacritty](../third_party/alacritty/ReadMe.md) is one of other alternatives. -## 30. Trice without UART +## 31. Trice without UART A very performant output path is RTT, if your MCU supports background memory access like the ARM-M ones. @@ -2936,7 +2255,7 @@ Because the Trice tool needs only to receive, a single target UART-TX pin will d -## 31. Trice over RTT +## 32. Trice over RTT > Allows Trice over the debug probe without using a pin or UART. @@ -2951,11 +2270,11 @@ Because the Trice tool needs only to receive, a single target UART-TX pin will d -### 31.1. For the impatient (2 possibilities) +### 32.1. For the impatient (2 possibilities) The default SEGGER tools only suport RTT channel 0. -#### 31.1.1. Start JLink commander and connect over TCP +#### 32.1.1. Start JLink commander and connect over TCP * JLink.exe β `connect β β S β` and keep it active. * You can control the target with `r[eset], g[o], h[alt]` and use other commands too. @@ -3035,9 +2354,9 @@ $ trice l -p TCP4 -args="127.0.0.1:19021" -til ../examples/G0B1_inst/til.json -l In this **G0B1_inst** example we use the additional `-d16` and `-pf none` switches to decode the RTT data correctly. -**This is just a demonstration and test for the `-port TCP4` usage possibility**. Using RTT with J-Link is more easy possible as shown in the next point. +**This is a demonstration and test for the `-port TCP4` usage possibility**. Using RTT with J-Link is more easy possible as shown in the next point. -#### 31.1.2. Start using JLinkLogger +#### 32.1.2. Start using JLinkLogger * Start inside Git-Bash or s.th. similar: `trice l -p JLINK -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0"` * Replace CLI details with your settings. @@ -3045,12 +2364,12 @@ In this **G0B1_inst** example we use the additional `-d16` and `-pf none` switch * You can add the `-verbose` CLI switch for more details. * You may **not** need a Trice tool restart after firmware reload. * For some reason the RTT technique does not work well with Darwin right now. The problem seems to be that the JLinkRTTLogger app cannot work correctly in the background. But there is a workaround: - * In one terminal run `JLinkRTTLogger -Device STM32G0B1RE -if SWD -Speed 4000 -RTTChannel 0 myLogFile.bin` + * In one terminal run `JLinkRTTLogger -Device STM32G0B1RE -if SWD -Speed 4000 -RTTChannel 0 myLogFile.bin` * and in an other terminal execute `trice l -p FILE -args myLogFile.bin -pf none -d16`. -### 31.2. Segger Real Time Transfer (RTT) +### 32.2. Segger Real Time Transfer (RTT) * Prerequisite is a processor with memory background access support like ARM Cortex-M cores. * If you can use a Segger J-Link or an STM ST-Link debug probe (ST Microelectronics eval boards have it) this is an easy and fast way to use Trice without any UART or other port. @@ -3091,14 +2410,14 @@ In this **G0B1_inst** example we use the additional `-d16` and `-pf none` switch -### 31.3. J-Link option +### 32.3. J-Link option * Prerequisite is a SEGGER J-Link debug probe or a development board with an on-board J-Link option. -#### 31.3.1. Convert Evaluation Board onboard ST-Link to J-Link +#### 32.3.1. Convert Evaluation Board onboard ST-Link to J-Link * Following steps describe the needed action for a ST Microelectronics evaluation board and windows - adapt them to your environment. -* It is always possible to turn back to the ST-Link OB firmware with the SEGGER `STLinkReflash.exe` tool but afterwards the ST-Link Upgrade tool should be used again to get the latest version. +* It is always possible to turn back to the ST-Link OB firmware with the SEGGER `STLinkReflash.exe` tool but afterwards the ST-Link Upgrade tool should be used again to get the latest version.First step (to do if some issues occur - otherwise you can skip it)
@@ -3116,7 +2435,7 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st * Check [Converting ST-LINK On-Board Into a J-Link](https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/) * Use `STLinkReflash.exe` to convert NUCLEO from ST-Link on-board to J-Link on-board. *`STM32 Debug+ VCP` wonΒ΄t be detected by Segger reflash utility.* -#### 31.3.2. Some SEGGER tools in short +#### 32.3.2. Some SEGGER tools in short * Download [J-Link Software and Documentation Pack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) and install. * You may need to add `C:\Program Files\SEGGER\JLink` to the %PATH% variable. @@ -3188,7 +2507,7 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st * The Trice tool can watch the output file and display the *Trices*: `trice log -port JLINK -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0"  -#### 31.3.3. JLinkRTTClient.exe +#### 32.3.3. JLinkRTTClient.exe * `JLinkRTTClient.exe` can be used for simple text transmitting to the target, it also displays strings from target coming over channel 0. It is not used by the Trice tool. * **PLUS:** @@ -3196,7 +2515,7 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st * **MINUS:** * Unfortunately it cannot run separately parallel to stimulate the target with any proprietary protocol because it connects to localhost:19021 and therefore blockades the only one possible connection. -#### 31.3.4. JLinkRTTViewer.exe +#### 32.3.4. JLinkRTTViewer.exe * `JLinkRTTViewer.exe` is a GUI tool and connects via the SEGGER API to the target. It expects ASCII codes and is not used by the Trice tool. The switching between the 16 possible terminals is done via `FF 00` ... `FF 0F`. These byte pairs can occur inside the Trice data. @@ -3210,7 +2529,7 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st -### 31.4. Segger RTT +### 32.4. Segger RTT * The main advantages are: * Speed @@ -3219,12 +2538,12 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st * This is, because automatically done by SeggerRTT. This way one can debug code as comfortable as with `printf()` but with all the TRICE advantages. Have a look here:  * Avoid Trice buffering inside target and write with TRICE macro directly into the RTT buffer (direct Trice mode = `#define TRICE_MODE 0` inside [triceConfig.h](../examples/F030_inst/Core/Inc/triceConfig.h)). * Write the bytes per Trice directly (little time & some space overhead on target, but no changes on host side) - +  -### 31.5. Segger J-Link SDK (~800 EUR) Option +### 32.5. Segger J-Link SDK (~800 EUR) Option * Segger offers a SeggerRTT SDK which allows to use more than just channel 0 and you can develop your own tooling with it. * The `trice -port JLINK` is ok for usage **as is** right now. However if you wish more comfort check here: @@ -3234,7 +2553,7 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st -### 31.6. Additional Notes (leftovers) +### 32.6. Additional Notes (leftovers) * `Downloading RTT target package` from [https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/](https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/). * Read the manual [UM08001_JLink.pdf](../third_party/segger.com/UM08001_JLink.pdf). @@ -3243,7 +2562,7 @@ See also [https://github.com/stlink-org/stlink](https://github.com/stlink-org/st -### 31.7. Further development +### 32.7. Further development @@ -3282,21 +2601,21 @@ libusb-1.0.23\examples\bin64> .\listdevs.exe -### 31.8. NUCLEO-F030R8 example +### 32.8. NUCLEO-F030R8 example Info: [https://www.st.com/en/evaluation-tools/nucleo-f030r8.html](https://www.st.com/en/evaluation-tools/nucleo-f030r8.html) -#### 31.8.1. RTT with original on-board ST-LINK firmware +#### 32.8.1. RTT with original on-board ST-LINK firmware * `#define TRICE_RTT_CHANNEL 0`: * If you use a NUCLEO-F030R8 with the original ST-Link on board after firmware download enter: `trice l -p ST-LINK -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0 -RTTSearchRanges 0x20000000_0x2000"`. After pressing the reset button output becomes visible:  * It works with both ST-Link variants (with or without mass storage device.) -#### 31.8.2. Change to J-LINK onboard firmware +#### 32.8.2. Change to J-LINK onboard firmware  -#### 31.8.3. RTT with J-LINK firmware on-board +#### 32.8.3. RTT with J-LINK firmware on-board  @@ -3307,7 +2626,7 @@ Info: [https://www.st.com/en/evaluation-tools/nucleo-f030r8.html](https://www.st -### 31.9. Possible issues +### 32.9. Possible issues * These boards seem not to work reliable with RTT over J-Link on-board firmware. * NUCLEO-G071RB @@ -3316,7 +2635,7 @@ Info: [https://www.st.com/en/evaluation-tools/nucleo-f030r8.html](https://www.st -### 31.10. OpenOCD with Darwin +### 32.10. OpenOCD with Darwin * OpenOCD on MacOS works out of the box after installing it. * When using VS code with Cortex-Debug you cannot use OpenOCD at the same time. @@ -3363,19 +2682,19 @@ Info : Listening on port 4444 for telnet connections ```bash ms@MacBook-Pro G0B1_inst % trice l -p TCP4 -args localhost:9090 -pf none -d16 Nov 14 17:32:33.319451 TCP4: triceExamples.c 10 0_000 Hello! ππ -Nov 14 17:32:33.319463 TCP4: -Nov 14 17:32:33.319463 TCP4: β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨ +Nov 14 17:32:33.319463 TCP4: +Nov 14 17:32:33.319463 TCP4: β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨β¨ Nov 14 17:32:33.319463 TCP4: ππππ NUCLEO-G0B1RE ππππ -Nov 14 17:32:33.319463 TCP4: πππππππππππππππππ -Nov 14 17:32:33.319463 TCP4: -Nov 14 17:32:33.319463 TCP4: +Nov 14 17:32:33.319463 TCP4: πππππππππππππππππ +Nov 14 17:32:33.319463 TCP4: +Nov 14 17:32:33.319463 TCP4: Nov 14 17:32:33.406455 TCP4: triceExamples.c 16 0_037 2.71828182845904523536 <- float number as string Nov 14 17:32:33.505116 TCP4: triceExamples.c 17 0_087 2.71828182845904509080 (double with more ciphers than precision) Nov 14 17:32:33.607518 TCP4: triceExamples.c 18 0_117 2.71828174591064453125 (float with more ciphers than precision) Nov 14 17:32:33.707851 TCP4: triceExamples.c 19 0_146 2.718282 (default rounded float) Nov 14 17:32:33.807685 TCP4: triceExamples.c 20 0_175 A Buffer: -Nov 14 17:32:33.908202 TCP4: triceExamples.c 21 0_204 32 2e 37 31 38 32 38 31 38 32 38 34 35 39 30 34 35 32 33 35 33 36 -Nov 14 17:32:34.007148 TCP4: triceExamples.c 22 0_254 31372e32 31383238 34383238 34303935 35333235 +Nov 14 17:32:33.908202 TCP4: triceExamples.c 21 0_204 32 2e 37 31 38 32 38 31 38 32 38 34 35 39 30 34 35 32 33 35 33 36 +Nov 14 17:32:34.007148 TCP4: triceExamples.c 22 0_254 31372e32 31383238 34383238 34303935 35333235 Nov 14 17:32:35.007949 TCP4: triceExamples.c 23 0_301 ARemoteFunctionName(2e32)(3137)(3238)(3138)(3238)(3438)(3935)(3430)(3235)(3533)(3633) Nov 14 17:32:35.112304 TCP4: triceExamples.c 24 100 times a 16 byte long Trice messages, which not all will be written because of the TRICE_PROTECT: Nov 14 17:32:35.307567 TCP4: triceExamples.c 26 0_379 i=44444400 aaaaaa00 @@ -3386,7 +2705,7 @@ Nov 14 17:32:35.710201 TCP4: triceExamples.c 26 0_504 i=4444440 ... ``` -### 31.11. Links +### 32.11. Links * [https://www.codeinsideout.com/blog/stm32/j-link-rtt/](https://www.codeinsideout.com/blog/stm32/j-link-rtt/) (A good explanation of SEGGER J-Link Realtime Transfer - Fast Debug protocol: - only suitable for ASCII transfer) * [USB over WSL2?](https://twitter.com/beriberikix/status/1487127732190212102?s=20&t=NQVa27qvOqPi2uGz6pJNRA) (Maybe intersting for OpenOCD) @@ -3395,66 +2714,63 @@ Nov 14 17:32:35.710201 TCP4: triceExamples.c 26 0_504 i=4444440 +## 33. Trice Target Code Implementation +### 33.1. TRICE Macro structure -## 32. Trice Target Code Implementation - - -### 32.1. TRICE Macro structure - -#### 32.1.1. TRICE_ENTER +#### 33.1.1. TRICE_ENTER * Optionally disable interrupts. * Prepare `TriceBufferWritePosition` and keep its initial value. -#### 32.1.2. TRICE_PUT +#### 33.1.2. TRICE_PUT * Use and increment `TriceBufferWritePosition`. -#### 32.1.3. TRICE_LEAVE +#### 33.1.3. TRICE_LEAVE * Use `TriceBufferWritePosition` and its initial value for data transfer * Optionally restore interrupt state. -### 32.2. TRICE_STACK_BUFFER +### 33.2. TRICE_STACK_BUFFER * `TRICE_ENTER`: Allocate stack * `TRICE_LEAVE`: Call TriceDirectOut() -### 32.3. TRICE_STATIC_BUFFER +### 33.3. TRICE_STATIC_BUFFER * This is like `TRICE_STACK_BUFFER` but avoids stack allocation, what is better for many stacks. * `TRICE_ENTER`: Set TriceBufferWritePosition to buffer start. * `TRICE_LEAVE`: Call TriceDirectOut(). -### 32.4. TRICE_DOUBLE_BUFFER +### 33.4. TRICE_DOUBLE_BUFFER * `TRICE_ENTER`: Keep TriceBufferWritePosition. * `TRICE_LEAVE`: Optionally call TriceDirectOut(). -### 32.5. TRICE_RING_BUFFER +### 33.5. TRICE_RING_BUFFER * `TRICE_ENTER`: Keep or wrap TriceBufferWritePosition and add offset. * `TRICE_LEAVE`: Optionally call TriceDirectOut(). The `TRICE_RING_BUFFER` allocates incremental ring buffer space and each trice location is read by a deferred task. -### 32.6. Deferred Out +### 33.6. Deferred Out -#### 32.6.1. Double Buffer +#### 33.6.1. Double Buffer * TriceTransfer * TriceOut * TriceNonBlockingWrite( triceID, enc, encLen ); - -#### 32.6.2. Ring Buffer + +#### 33.6.2. Ring Buffer * TriceTransfer * lastWordCount = TriceSingleDeferredOut(addr); * int triceID = TriceIDAndBuffer( pData, &wordCount, &pStart, &Length ); * TriceNonBlockingWrite( triceID, pEnc, encLen ); -### 32.7. Direct Transfer +### 33.7. Direct Transfer * TRICE_LEAVE * TriceDirectWrite(triceSingleBufferStartWritePosition, wordCount); @@ -3465,7 +2781,7 @@ The `TRICE_RING_BUFFER` allocates incremental ring buffer space and each trice l * triceDirectEncode * triceNonBlockingDirectWrite -### 32.8. Possible Target Code Improvements +### 33.8. Possible Target Code Improvements There have been 3 similar implementations for trice encode @@ -3479,7 +2795,7 @@ unsigned TriceEncryptAndCobsFraming32( uint32_t * const triceStart, unsigned wor Now: ```C -size_t TriceEncode( unsigned encrypt, unsigned framing, uint8_t* dst, const uint8_t * buf, size_t len ){ +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 ){ ``` @@ -3509,15 +2825,15 @@ size_t TriceEncode(int* pTriceID, unsigned int pCount, uint32_t * const dest, ui -## 33. Trice Similarities and Differences to printf Usage +## 34. Trice Similarities and Differences to printf Usage -### 33.1. Printf-like functions +### 34.1. Printf-like functions ...have a lot of things to do: Copy format string from FLASH memory into a RAM buffer and parse it for format specifiers. Also parse the variadic parameter list and convert each parameter according to its format specifier into a character sequences, what includes several divisions - costly function calls. Concatenate the parts to a new string and deliver it to the output, what often means copying again. A full-featured printf library consumes plenty space and processing time and several open source projects try to make it better in this or that way. Never ever call a printf-like function in time critical code, like an interrupt - it would crash your target in most cases. The *trice* calls are usable inside interrupts, because they only need a few MCU clocks for execution. Porting legacy code to use it with the Trice library, means mainly to replace Printf-like function calls with `trice` function calls. -### 33.2. Trice IDs +### 34.2. Trice IDs * Each Trice caries a 14-bit nuber ID as replacement for the format string. * This ID is automatically generated (controllable) and in the source code it is the first parameter inside the Trice macro followed by the format string and optional values. @@ -3525,7 +2841,7 @@ The *trice* calls are usable inside interrupts, because they only need a few MCU * The Trice cache makes this invisible to the build system, allowing full translation speed. * The format string is **not** compiled into the target code. It goes together with the ID into a project specific reference list file [til.json](../_test/testdata/til.json) (example). -### 33.3. Trice values bit width +### 34.3. Trice values bit width * No need to explicit express the value bit width. * The default parameter width for the Trice macro is 32 bit. It is changeable to 8, 16 or 64-bit: @@ -3536,7 +2852,7 @@ The *trice* calls are usable inside interrupts, because they only need a few MCU * The fastest Trice macro execution is, when MCU bit width matches the macro bit width. * The implicit TCOBS compression compacts the binary Trice data during the framing. -### 33.4. Many value parameters +### 34.4. Many value parameters * No need to explicit express the values count. * Up to 12 values are supported directly. Example: @@ -3547,13 +2863,13 @@ The *trice* calls are usable inside interrupts, because they only need a few MCU * The _Trice_ tool compares the number of given format specifiers with the written parameters in a precimpile step to minimize the risk of runtime errors. * There is no variadic values scanning during runtime. The C preprocessor does the work. -### 33.5. Floating Point Values +### 34.5. Floating Point Values These types are mixable with integer types but need to be covered by converter function. * *float* types use the `aFloat()` function and need a minimal value bit width of 32, to secure correct data transfer. * Example: - + ```c float x = 7.2; trice( "%f", aFloat(x)); @@ -3592,11 +2908,11 @@ static inline uint64_t aDouble( double x ){ } ``` -### 33.6. Runtime Generated 0-terminated Strings Transfer with triceS +### 34.6. Runtime Generated 0-terminated Strings Transfer with triceS * The `%s` format specifier is supported by the Trice macro too but needs specific treatment. * Strings, known at compile time should be a part of a format string to reduce runtime overhead. -* Strings created at runtime, need a special `TRICE_S` (or `triceS`, `TriceS`, `TRiceS`) macro, which accepts exactly one type `%s` format specifier. Generated strings are allowed to a size of 32764 bytes each, if the configured Trice buffer size is sufficient. +* Strings created at runtime, need a special `TRICE_S` (or `triceS`, `TriceS`, `TRiceS`) macro, which accepts exactly one type `%s` format specifier. Generated strings are allowed to a size of 32764 bytes each, if the configured Trice buffer size is sufficient. * Example: ```c @@ -3604,13 +2920,13 @@ static inline uint64_t aDouble( double x ){ triceS( "A runtime string %20s\n", s; ``` -### 33.7. Runtime Generated counted Strings Transfer with triceN +### 34.7. Runtime Generated counted Strings Transfer with triceN * It is also possible to transfer a buffer with length n using the `TRICE_N` (or `triceN`, `TriceN`, `TRiceN`) macro. * This becomes handy for example, when a possibly not 0-terminated string in FLASH memory needs transmission: `triceN( "msg: FLASH string is %s", addr, 16 );` * There are also specific macros like `trice32B` or `trice16F`. Please look into [triceCheck.c](../_test/testdata/triceCheck.c) for usage or see the following. -### 33.8. Runtime Generated Buffer Transfer with triceB +### 34.8. Runtime Generated Buffer Transfer with triceB * A buffer is transmittable with `TRICE_B` (or `triceB`, `TriceB`, `TRiceB`) and specifying just one format specifier, which is then repeated. Example: @@ -3629,16 +2945,16 @@ static inline uint64_t aDouble( double x ){ If the buffer is not 8 but 16, 32 or 32 bits wide, the macros `TRICE8_B`, `TRICE16_B`, `TRICE32_B` and `TRICE64_B`, are usable in the same manner. -### 33.9. Remote function call syntax support with triceF +### 34.9. Remote function call syntax support with triceF The `TRICE8_F`, `TRICE16_F`, `TRICE32_F`, `TRICE64_F`, macros expect a string without format specifiers which is usable later as a function call. Examples: ```C trice8F( "call:FunctionNameW", b8, sizeof(b8) /sizeof(int8_t) ); //exp: time: default: call:FunctionNameW(00)(ff)(fe)(33)(04)(05)(06)(07)(08)(09)(0a)(0b)(00)(ff)(fe)(33)(04)(05)(06)(07)(08)(09)(0a)(0b) -TRICE16_F( "info:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: 842,150_450default: info:FunctionNameX(0000)(ffff)(fffe)(3344) -TRice16F( "call:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: 842,150_450default: call:FunctionNameX(0000)(ffff)(fffe)(3344) -Trice16F( "call:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: 5_654default: call:FunctionNameX(0000)(ffff)(fffe)(3344) -trice16F( "call:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: default: call:FunctionNameX(0000)(ffff)(fffe)(3344) +TRICE16_F( "info:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: 842,150_450default: info:FunctionNameX(0000)(ffff)(fffe)(3344) +TRice16F( "call:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: 842,150_450default: call:FunctionNameX(0000)(ffff)(fffe)(3344) +Trice16F( "call:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: 5_654default: call:FunctionNameX(0000)(ffff)(fffe)(3344) +trice16F( "call:FunctionNameX", b16, sizeof(b16)/sizeof(int16_t) ); //exp: time: default: call:FunctionNameX(0000)(ffff)(fffe)(3344) TRICE32_F( "info:FunctionNameY", b32, sizeof(b32)/sizeof(int32_t) ); //exp: time: 842,150_450default: info:FunctionNameY(00000000)(ffffffff)(fffffffe)(33445555) TRice32F( "call:FunctionNameY", b32, sizeof(b32)/sizeof(int32_t) ); //exp: time: 842,150_450default: call:FunctionNameY(00000000)(ffffffff)(fffffffe)(33445555) Trice32F( "call:FunctionNameY", b32, sizeof(b32)/sizeof(int32_t) ); //exp: time: 5_654default: call:FunctionNameY(00000000)(ffffffff)(fffffffe)(33445555) @@ -3655,18 +2971,18 @@ The Trice tool displays the parameter buffer in the shown manner. It is planned * `triceD( "dump:32", addr, 160 );` -> The Trice tool dumps in 32 byte rows. * An appropriate syntax is needed. -### 33.10. Extended format specifier possibilities +### 34.10. Extended format specifier possibilities * Because the format string is interpreted by the Trice tool written in [Go](https://en.wikipedia.org/wiki/Go_(programming_language)), the **Go** capabilities partial usable. -#### 33.10.1. Trice format specifier +#### 34.10.1. Trice format specifier * The Trice macros are used in **C** code. * The format strings are interpreted by the Trice tool, which is written in **Go**. * The **C** and **Go** format specifier are not equal but similar. * Therefore, a **T**rice adaption is internally performed. -#### 33.10.2. Overview Table +#### 34.10.2. Overview Table | Format Specifier Type | C | Go | T | (T =Trice) \| remark | |-----------------------------------------------------------------|---|----|---|-----------------------------------------------------------------------------| @@ -3707,7 +3023,7 @@ The Trice tool displays the parameter buffer in the shown manner. It is planned  -### 33.11. UTF-8 Support +### 34.11. UTF-8 Support This is gratis, if you edit your source files containing the format strings in UTF-8: @@ -3715,11 +3031,11 @@ This is gratis, if you edit your source files containing the format strings in U The target does not even "know" about that, because it gets only the Trice IDs. -### 33.12. Switch the language without changing a bit inside the target code +### 34.12. Switch the language without changing a bit inside the target code Once the [til.json](../examples/F030_inst/til.json) list is done the user can translate it in any language and exchanging the list switches to another language. -### 33.13. Format tags prototype specifier examples +### 34.13. Format tags prototype specifier examples This syntax is supported: `%[flags][width][.precision][length]` @@ -3734,28 +3050,28 @@ This syntax is supported: `%[flags][width][.precision][length]` -## 34. Development Environment Setup +## 35. Development Environment Setup * Trice is usable with any C-compiler for any processor type, bit width and endianness. The example projects here are STM32 ones but illustrate how to setup Trice. * The [examples](../examples) folder contains some instrumented example projects together with bare counterparts. Comparing a bare project with its intrumented counterpart gives a quick overview what needs to be done to get started. -### 34.1. Common Information +### 35.1. Common Information - All used tools are **Open Source** (despite the [ARM-Keil Β΅Vision IDE](https://www2.keil.com/mdk5/uvision/), for new projects vsCode is a better choice). - All provided information is just as example and needs adaption to your needs. - There is no need to setup the environment in the given order. -### 34.2. Important to know +### 35.2. Important to know The [ARM-Keil Β΅Vision IDE](https://www2.keil.com/mdk5/uvision/) does sometimes not recognize external file modifications. That means for example: After editing `main.c` by adding a `trice( "Hi!\n" )` and executing `trice insert` as pre-compile step it could happen, that an updated `trice( iD(12345), "Hi!\n" )` was inserted and correct compiled but the update in `main.c` is not shown. Simply close and reopen `main.c` before editing again. This seems to be a [ARM-Keil Β΅Vision IDE](https://www2.keil.com/mdk5/uvision/) "feature" or be caused Windows not signaling a file change. -### 34.3. Animation +### 35.3. Animation (The trice IDs occur just during the compilation.)
-### 34.4. Setup PC
+### 35.4. Setup PC
Setting up a PC is for Linux mostly straightforward but Windows PCs are more problematic. The steps shown here are just one example.
@@ -3778,7 +3094,7 @@ Setting up a PC is for Linux mostly straightforward but Windows PCs are more pro
- Install SEGGER [J-Link Software and Documentation Pack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack)
- Install [Make for Windows](https://sourceforge.net/projects/gnuwin32/) and add its installation bin folder location to the PATH variable.
-#### 34.4.1. Setup Trice
+#### 35.4.1. Setup Trice
- from inside folder `repos` clone trice repo with `git clone https://github.com/rokath/trice.git`.
- Run `go install ./cmd/trice/...` from folder `repos/trice`.
@@ -3790,7 +3106,7 @@ OR
- Put trice/src into `repos` if you want access the trice library code from several projects and have it only once.
- Alternatively copy it into your project.
-#### 34.4.2. Setup ARM Environment
+#### 35.4.2. Setup ARM Environment
Install ARM GCC
@@ -3878,7 +3194,7 @@ InstalledDir: C:\bin\ArmClang\bin The paths must match with the installation locations. -#### 34.4.3. Setup STM32 +#### 35.4.3. Setup STM32Generate Base Project
@@ -3911,7 +3227,7 @@ This step is recommended before re-flashing with the J-Link onboard debugger sof - Selecting the other option, would not allow to update with the SEGGER STLinkReflash tool. - Close -#### 34.4.4. Setup Onboard J-Link on NUCLEO (other ST evaluation boards too) +#### 35.4.4. Setup Onboard J-Link on NUCLEO (other ST evaluation boards too) (https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/) @@ -3925,9 +3241,9 @@ Unfortunately this is not possible with **v3** onboard debugger hardware! But yo - 0: Quit - Download, extract & start https://github.com/rokath/trice/blob/master/third_party/segger.com/STLinkReflash_190812.zip - Re-Flash onboard debugger. - - You can undo this step anytime. + - You can undo this step anytime. -#### 34.4.5. Setup VS-Code +#### 35.4.5. Setup VS-Code - Start VS Code - Install Go rich language support if you want to use Go as well (not needed for ARM debugging). @@ -3948,43 +3264,43 @@ Unfortunately this is not possible with **v3** onboard debugger hardware! But yo - Download file [`./STM32L4x2.svd`](./STM32L4x2.svd) from https://www.st.com/resource/en/svd/stm32l4_svd.zip (example) - Installing the **Cortex Debug** extension allow you to debug the target code. -### 34.5. Makefile with Clang too +### 35.5. Makefile with Clang too - After STM32 CubeMX code generation the Makefile was edited and spitted. - STM32 CubeMX code generation accepts the edited Makefile, so re-generation is no issue. - It modifies the settings according to the changes. -### 34.6. Download Locations +### 35.6. Download Locations -#### 34.6.1. Clang +#### 35.6.1. Clang https://releases.llvm.org/download.html -> https://github.com/llvm/llvm-project/releases/tag/llvmorg-16.0.0 (example) -#### 34.6.2. GCC +#### 35.6.2. GCC https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain -> https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads (example)) -### 34.7. Install Locations +### 35.7. Install Locations Do not use locations containing spaces, like `C:\Program Files`. Take `C:\bin` for example. This avoids trouble caused by spaces inside path names. -### 34.8. Environment Variables +### 35.8. Environment Variables Extend the path variable: - PATH += `C:\bin\ArmGNUToolchain\bin` - PATH += `C:\Program Files\SEGGER\JLink`. -### 34.9. Build command +### 35.9. Build command - Clang: `make` or to get it faster `make -j8`. - GCC: `make GCC`. -### 34.10. Run & Debug +### 35.10. Run & Debug - In terminal after `make` click Run&Debug & click green triangle. -### 34.11. Logging +### 35.11. Logging - In terminal type `make log`. This executes the command in project folder: @@ -3992,7 +3308,7 @@ Extend the path variable:
-### 34.12. Setting up a new project
+### 35.12. Setting up a new project
- Copy this project folder under a new name like `myAwesomeNewProject` or name it as you like.
- Make a temporary folder `myTemp` and generate with STM CubeMX the base project.
@@ -4008,7 +3324,7 @@ Extend the path variable:
-## 35. Example Projects without and with Trice Instrumentation
+## 36. Example Projects without and with Trice Instrumentation
| Project Name | Description |
|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -4027,11 +3343,11 @@ Extend the path variable:
-### 35.1. Nucleo-F030R8 Examples
+### 36.1. Nucleo-F030R8 Examples
-#### 35.1.1. F030_bare
+#### 36.1.1. F030_bare
Folder: [../examples/F030_bare/](../examples/F030_bare/)
@@ -4059,7 +3375,7 @@ This is a STMCubeMX generated project without Trice instrumentation for easy com
- Start a terminal and type `make`. The output should be similar to:
```bash
-PS E:\repos\trice\examples\F030_bare> make -j8
+PS E:\repos\trice\examples\F030_bare> make -j8
mkdir build
arm-none-eabi-gcc -c -mcpu=cortex-m0 -mthumb -DUSE_FULL_LL_DRIVER -DHSE_VALUE=8000000 -DHSE_STARTUP_TIMEOUT=100 -DLSE_STARTUP_TIMEOUT=5000 -DLSE_VALUE=32768 -DHSI_VALUE=8000000 -DLSI_VALUE=40000 -DVDD_VALUE=3300 -DPREFETCH_ENABLE=1 -DINSTRUCTION_CACHE_ENABLE=0 -DDATA_CACHE_ENABLE=0 -DSTM32F030x8 -ICore/Inc -IDrivers/STM32F0xx_HAL_Driver/Inc -IDrivers/CMSIS/Device/ST/STM32F0xx/Include -IDrivers/CMSIS/Include -Og -Wall -fdata-sections -ffunction-sections -g -gdwarf-2 -MMD -MP -MF"build/main.d" -Wa,-a,-ad,-alms=build/main.lst Core/Src/main.c -o build/main.o
@@ -4119,7 +3435,7 @@ PS E:\repos\trice\examples\F030_bare>
__weak int _write(void) { return -1; }
```
-#### 35.1.2. F030_inst
+#### 36.1.2. F030_inst
Folder: [../examples/F030_inst/](../examples/F030_inst/)
@@ -4145,18 +3461,18 @@ This is a working example with deferred encrypted out over UART. By uncommenting
-### 35.2. Nucleo-G0B1 Examples
+### 36.2. Nucleo-G0B1 Examples
-#### 35.2.1. G0B1_bare
+#### 36.2.1. G0B1_bare
Folder: [../examples/G0B1_bare/](../examples/G0B1_bare/)
G0B1_gen Description
-- This is a working example with CLang and also GCC. -- This is a STMCubeMX generated project. It was then manually adapted to Clang. +- This is a working example with CLang and also GCC. +- This is a STMCubeMX generated project. It was then manually adapted to Clang. - It is without TRICE instrumentation for easy compare with [../G0B1_inst](../G0B1_inst) to figure out the needed changes to set up trice.Setting Up G0B1_gen
@@ -4164,7 +3480,7 @@ Folder: [../examples/G0B1_bare/](../examples/G0B1_bare/) - See and adapt steps from [F030_bare](#f030_bare). - Then add/modify the files to reach this folder layot. -#### 35.2.2. G0B1_inst +#### 36.2.2. G0B1_inst Folder: [../examples/G0B1_inst/](../examples/G0B1_inst/) @@ -4183,11 +3499,11 @@ This is an example with direct out without framing over RTT and deferred out in -### 35.3. Nucleo-L432KC Examples +### 36.3. Nucleo-L432KC Examples
-#### 35.3.1. L432_bare
+#### 36.3.1. L432_bare
Folder: [../examples/L432_bare/](../examples/L432_bare/)
@@ -4198,7 +3514,7 @@ Folder: [../examples/L432_bare/](../examples/L432_bare/)
* It was then manually adapted additionally to Clang.
* It was additionally configured for FreeRTOS.
-#### 35.3.2. L432_inst
+#### 36.3.2. L432_inst
Folder: [../examples/L432_inst/](../examples/L432_inst/)
@@ -4281,7 +3597,7 @@ $ trice l -p com8 -hs off -prefix off
```bash
ms@LenovoP51Win11 MINGW64 /e/repos/trice/examples/L432KC_gen_ad_toClang_ed_inst (devel)
-$ openocd -f STLinkOpenOCD.cfg
+$ openocd -f STLinkOpenOCD.cfg
Open On-Chip Debugger 0.12.0 (2024-09-16) [https://github.com/sysprogs/openocd]
Licensed under GNU GPL v2
libusb1 d52e355daa09f17ce64819122cb067b8a2ee0d4b
@@ -4335,7 +3651,7 @@ Nov 16 20:38:16.323665 TCP4: triceExamples.c 19 46_536 2.718282
* [en.stm32cubeprg-win64-v2-17-0.zip]()
* [en.st-link-server-v2-1-1.zip]()
* PATH variable extended with `C:\Program Files (x86)\STMicroelectronics\stlink_server`
- * Copied
+ * Copied
* From: "C:\Program Files (x86)\STMicroelectronics\stlink_server\stlinkserver.exe"
* To: "C:\Program Files (x86)\STMicroelectronics\stlink_server\ST-LINK_gdbserver.exe"
@@ -4348,7 +3664,7 @@ Nov 16 20:38:16.323665 TCP4: triceExamples.c 19 46_536 2.718282
* Copy `C:\bin\libusb-1.0.27\MinGW64\dll\libusb-1.0.dll` to `C:\bin\stlink-1.8.0-win32\bin\libusb-1.0.dll`
```bash
ms@LenovoP51Win11 MINGW64 /e/repos/trice/examples/L432KC_gen_ad_toClang_ed_inst (devel)
-$ st-util.exe
+$ st-util.exe
st-util 1.8.0
libusb: info [get_guid] no DeviceInterfaceGUID registered for 'USB\VID_056A&PID_5105\5&1140C04&0&10'
libusb: info [get_guid] no DeviceInterfaceGUID registered for 'USB\VID_056A&PID_5105&MI_01\6&13339912&0&0001'
@@ -4374,13 +3690,51 @@ Receive signal 0. Exiting...
+## 37. Trice User Manual Changelog
-## 36. Trice User Manual Changelog
-
-Details
-
+
Details (click to expand)
-
| Date | Version | Comment |
|-------------|---------|---------------|
| 2024-DEC-01 | 0.0.0 | Initial Draft |
-
\ No newline at end of file
+
+
+
+
\ No newline at end of file
diff --git a/docs/_Legacy/LeftOvers.md b/docs/_Legacy/LeftOvers.md
new file mode 100644
index 000000000..ccada8d92
--- /dev/null
+++ b/docs/_Legacy/LeftOvers.md
@@ -0,0 +1,532 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+