Merge remote-tracking branch 'origin/master'

FilesAndFolders.md

@@ -2,52 +2,45 @@
 
 | name                            | content                                          |
 |---------------------------------|--------------------------------------------------|
+| [./_test](./_test)              | automatic target code tests                      |
+| `.code_snippets/`               | unused code                                      |
+| `.github/`                      |                                                  |
+| `.idea/`                        | GoLand settings                                  |
+| `.vscode/`                      | vsCode settings                                  |
+| [./cmd/cui](./_cmd/_cui)        | (do not use) command user interface tryout code  |
+| [./cmd/_stim](./cmd/_stim)      | (do not use) target stimulation tool tryout code |
+| [./cmd/trice](./cmd/trice)      | `trice` tool command Go sources                  |
+| [./docs](./docs)                | documentation                                    |
+| [./examples](./examples)        | example target projects                          |
+| `./examples/*_inst/temp/`       | project binary logfiles                          |
+| [./internal](./internal)        | `trice` tool internal Go packages                |
+| [./pkg](./pkg)                  | `trice` tool common Go packages                  |
+| [./src/](./src)                 | C sources for trice instrumentation              |
+| `super-linter.report/`          |                                                  |
+| [./third_party](./third_party)  | external components                              |
+| `_config.yml`                   | unused                                           |
 | `.clang-format`                 | See below                                        |
 | `.clang-format-ignore`          | See below                                        |
 | `.editorconfig`                 | See below                                        |
-| `.code_snippets/`               |                                                  |
 | `.git/`                         | version control data base                        |
-| `.github/`                      |                                                  |
 | `.gitattributes`                | See below                                        |
 | `.gitignore`                    |                                                  |
-| `.goreleaser.yml`               |                                                  |
-| `.idea/`                        | GoLand                                           |
+| `.goreleaser.yml`               | goreleaser configuration                         |
 | `.travis.yml`                   |                                                  |
-| `.vscode/`                      |                                                  |
-| `AUTHORS.md`                    |                                                  |
+| `AUTHORS.md`                    | contributors                                     |
 | `CHANGELOG.md`                  |                                                  |
 | `CODE_OF_CONDUCT.md`            |                                                  |
 | `CONTRIBUTING.md`               |                                                  |
-| `FoldersAndFiles.md`            | this file                                        |
+| `FilesAndFolders.md`            | this file                                        |
+| `go.mod`                        |                                                  |
+| `go.sum`                        |                                                  |
 | `GoInfos.txt`                   |                                                  |
 | `LICENSE.md`                    |                                                  |
 | `README.md`                     |                                                  |
-| `_config.yml`                   |                                                  |
-| `branchesInfo.md`               |                                                  |
-| `cmd/`                          |                                                  |
+|                                 |                                                  |
 | `coverage.out`                  |                                                  |
 | `dist/`                         | created by goreleaser                            |
-| `docs/`                         |                                                  |
-| `examples/`                     | real projects                                    |
 | `fmtcoverage.html`              |                                                  |
-| `go.mod`                        |                                                  |
-| `go.sum`                        |                                                  |
-| `internal/`                     | trice Go packages for internal usage only        |
-| `pkg/`                          | trice Go packages usagable externally            |
-| `src/`                          | trice target sources                             |
-| `super-linter.report/`          |                                                  |
-| `temp/`                         | project binary logfiles                          |
-| `third_party/`                  | tools                                            |
-| [./cmd/cui](../cmd/cui)         | (do not use) command user interface tryout code  |
-| [./cmd/stim](../cmd/stim)       | (do not use) target stimulation tool tryout code |
-| [./cmd/trice](../cmd/trice)     | `trice` tool command Go sources                  |
-| [./docs](./docs)                | documentation                                    |
-| [./examples](../examples)       | example target projects                          |
-| [./internal](../internal)       | `trice` tool internal Go packages                |
-| [./pkg](../pkg)                 | `trice` tool common Go packages                  |
-| [./src/](../src)                | C sources for trice instrumentation              |
-| [./test](../test)               | automatic target code tests                      |
-| [./third_party](../third_party) | external components                              |
 
 ## `.clang-format`
 

README.md

@@ -1,4 +1,4 @@
-# ![TriceGirlS.png](./docs/ref/TriceGirl-167x222.png) **Trice** <- **TR**~~ace~~ **I**~~ds~~ **C** **E**~~mbedded~~  
+# ![TriceGirlS.png](./docs/ref/TriceGirl-167x222.png) $${\color{red}Trice}$$ <- $${\color{red}TR}$$~~ace~~ $${\color{red}I}$$~~d's~~ $${\color{red}C}$$   $${\color{red}E}$$~~mbedded~~ 
 
 [github.io/trice/](https://rokath.github.io/trice/)
 
@@ -68,7 +68,7 @@ Start `trice ds` inside a console, option: [third_party/alacritty](./third_party
 - [https://interrupt.memfault.com/blog/trice](https://interrupt.memfault.com/blog/trice)
 - [Trice User Guide](./docs/TriceUserGuide.md)
 - Check the [docs](./docs) folder. No need to read all this stuff - it is just for help and reference.
-- Check issues and discussions including the closed items.
+- Check [issues](https://github.com/rokath/trice/issues)  and [discussions](https://github.com/rokath/trice/discussions) including the closed items.
 
 ## Debugging using VS-Code and Clang for a Trice-instrumented Project in Direct-Out Mode over SEGGER-RTT
 
@@ -94,6 +94,19 @@ The Trice cache keeps copies of all to `trice i` or `trice c` passed files after
 
 For example an auto-formatter should get active **before** the `tice insert` command.
 
+## Wich mode to use?
+
+- For the development direct mode with SEGGER_RTT is recommended.
+- Most use cases are coverable in deferred mode with TRICE_BUFFER == TRICE_RING_BUFFER (less RAM needs) in TRICE_MULTI_PACK_MODE (less transfer data).
+
+## Project Status
+
+Trice is full usable and there are no known bugs (see [issues](https://github.com/rokath/trice/issues)).
+
+## Future 
+
+The documentation could get improved, for example by adding a quick start help. Additional features like remote procedure calls could be described and a separate tlog, maybe written in C, would allow logging on any platforms - not only **Go** supported ones.
+
 ## Support?
 
 Yes please - or simply :star: it. ☺ 

_test/ReadMe.md

@@ -2,16 +2,16 @@
 
 ## General info
 
-This folder is per default renamed into `_test` to avoid vsCode slow down.
+This folder is per default named to `_test` to avoid vsCode slow down.
 
 The main aim of these tests is to automatic compile and run the target code in different compiler switch variants avoiding manual testing this way.
 
 For the user it could be helpful to start with a `triceConfig.h`file from here and to adapt the Trice tool command line from the matching `cgo_test.go` if no close match in the `examples` folder was found.
 
 ## How to run the tests
 
-- In `trice` folder first execute `go clean -cache`. Cleaning the **Go** cache is recommended, because the CGO tests somehow keep pre-compiled files and when editing C-files, this can led to confusing results.
-- To run the tests `cd` into `_test` and execute `go test ./...`.
+- In `_trice` folder first execute `go clean -cache`. Cleaning the **Go** cache is recommended, because the CGO tests keep pre-compiled files and when editing C-files, this can led to confusing results.
+- To run the tests `cd` into `_test` and execute `go test ./...` fom there.
 
 ## Tests Details
 
@@ -27,7 +27,7 @@ To be able to run `go test ./...` successfully without running the [./updateTest
 
 The folders `tf` are Go packages just for tests. They all have the same package name `cgot` and are not included into the trice tool. The different `cgot` packages are independent and could have any names. They do not see each other and are used for target code testing independently.
 
-The `tf/triceConfig.h` files differ and correspondent to the `tf/cgo_test.go` files in the same folder. On test execution, the `./testdata/*.c` files are compiled into the trice test executable together with the trice sources `../src` using the `tf/triceConfig.h` file. 
+The `tf/triceConfig.h` files differ and correspondent to the `tf/cgo_test.go` files in the same folder. On test execution, the `./testdata/*.c` files are compiled into the trice test executable together with the trice sources `../src` using the `tf/triceConfig.h` file.
 
 The individual tests collect the expected results (`//exp: result`) together with the line numbers into a slice to execute the test loop on it. The `triceLogTest` function gets the `triceLog` function as parameter.
 
@@ -46,7 +46,7 @@ The `testdata\cgoPackage.go` file contains a variable `testLines = n`, which lim
 
 ## Test Internals
 
-The `./trice/_test/testdata/*.c` and `./trice/src/*.c` are compiled together with the actual cgot package into one singe Trice test binary, resulting in as many test binaries as there are test folders. Calling its TestFunction(s) causes the activation of the Trice statement(s) inside *triceCheck.c*. The ususally into an embedded device compiled Trice code generates a few bytes according to the configuration into a buffer. These bytes are transmitted usually in real life over a (serial) port or RTT. In the tests here, this buffer is then read out by the Trice tool handler function according to the used CLI switches and processed to a log string using the *til.json* file. This string in then compared to the expected string for the activated line.
+The `./trice/_test/testdata/*.c` and `./trice/src/*.c` are compiled together with the actual cgot package into one singe Trice test binary, resulting in as many test binaries as there are test folders. Calling its TestFunction(s) causes the activation of the Trice statement(s) inside *triceCheck.c*. The ususally into an embedded device compiled Trice code generates a few bytes according to the configuration into a buffer. These bytes are transmitted usually in real life over a (serial) port or RTT. In the tests here, this buffer is then read out by the Trice tool handler function according to the used CLI switches and processed to a log string using the *til.json* file. This string is then compared to the expected string for the activated line.
 
 Each `tf` is a **Go** package, which is not part of any **Go** application. They all named `cgot` and are only used independently for testing different configurations. The `tf/generated_cgoPackage.go` file is identical in all `tf`. Its master is `testdata/cgoPackage.go`. After editing the master, running the command `./updateTestData.sh` copies the master to all `tf` and renames it to `generated_cgoPackage.go`.
 
@@ -57,7 +57,7 @@ When running `go test ./tf`, a Trice tool test executable is build, using the Tr
 During the test, the file `triceCheck.c` is scanned for lines like
 
 ```C
-reak; case __LINE__: TRice( iD(3537), "info:This is a message without values and a 32-bit stamp.\n" ); //exp: time: 842,150_450default: info:This is a message without values and a 32-bit stamp.
+break; case __LINE__: TRice( iD(3537), "info:This is a message without values and a 32-bit stamp.\n" ); //exp: time: 842,150_450default: info:This is a message without values and a 32-bit stamp.
 ```
 
 Some C-code lines contain Trice statements and comments starting with `//exp: ` followed by the expected Trice tool output for that specific line. The **Go** testfunction collects these outputs in a slice together with the line numbers. Then for each found line number the execution of the **Go** function `func triceCheck(n int)` takes part, which in turn calls the CGO compiled C-function `TriceCheck(n)`. The now activated Trice C-code writes the generated trice bytes in a between **C** and **Go** shared buffer using the C-function `TriceWriteDeviceCgo`. After returning from the **Go** function `func triceCheck(n int)` and optionally calling `TriceTransfer` in deferred mode the Trice tool `triceLog()` function converts the Trice buffer bytes to the log string and compares the result with the expected data. The between **Go** and **C** shared buffer limits the executed Trices per line to one, because they use the same buffer from the beginning. This could be done better with an increment to allow several trices in one single line.

_test/_ringB_protect_de_tcobs_ua/TargetActivity.c

@@ -4,10 +4,10 @@
 // Needed safety space is TRICE_DATA_OFFSET + (2*TRICE_SINGLE_MAX_SIZE)-4) = 208
 // TRICE_DEFERRED_BUFFER_SIZE == 324
 char* TargetActivity(void) {                                                                                                                  // -4 bytes TRICE_DATA_OFFSET = 320 bytes space
-	TRice(iD(16204), "Hello ");                                                                                                               // -8 bytes = 312 bytes space
-	TRice(iD(16205), "World!\n");                                                                                                             // -8 bytes = 304 bytes space
-	TRice64(iD(16206), "msg:Twelve 64-bit values: %d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d\n", -1, -2, -3, -4, -5, -6, -7, -8, -9, -10, -11, -12); // -104 bytes = 200 bytes space
+	TRice(iD(16200), "Hello ");                                                                                                               // -8 bytes = 312 bytes space
+	TRice(iD(16201), "World!\n");                                                                                                             // -8 bytes = 304 bytes space
+	TRice64(iD(16202), "msg:Twelve 64-bit values: %d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d\n", -1, -2, -3, -4, -5, -6, -7, -8, -9, -10, -11, -12); // -104 bytes = 200 bytes space
 	// so the next Trice does not fit
-	trice(iD(16207), "Hello again\n"); // -4 bytes -> no fit!
+	trice(iD(16203), "Hello again\n"); // -4 bytes -> no fit!
 	return "feed3322 Hello World!\nfeed3322 Twelve 64-bit values: -1,-2,-3,-4,-5,-6,-7,-8,-9,-10,-11,-12";
 }

_test/be_dblB_de_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_TRANSFER_ORDER_IS_BIG_ENDIAN 1
 
 #define TRICE_DEFERRED_OUTPUT 1

_test/dblB_de_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DEFERRED_OUTPUT 1
 #define TRICE_DEFERRED_OUT_FRAMING TRICE_FRAMING_COBS
 #define TRICE_DEFERRED_UARTA 1

_test/dblB_de_multi_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DEFERRED_TRANSFER_MODE TRICE_MULTI_PACK_MODE
 #define TRICE_DEFERRED_OUTPUT 1
 #define TRICE_DEFERRED_OUT_FRAMING TRICE_FRAMING_COBS

_test/dblB_de_multi_nopf_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_CONFIG_WARNINGS 0
 
 #define TRICE_DEFERRED_TRANSFER_MODE TRICE_MULTI_PACK_MODE

_test/dblB_de_multi_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DEFERRED_TRANSFER_MODE TRICE_MULTI_PACK_MODE
 #define TRICE_DEFERRED_OUTPUT 1
 #define TRICE_DEFERRED_UARTA 1

_test/dblB_de_multi_xtea_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DEFERRED_TRANSFER_MODE TRICE_MULTI_PACK_MODE
 #define TRICE_DEFERRED_OUTPUT 1
 #define TRICE_DEFERRED_XTEA_ENCRYPT 1

_test/dblB_de_multi_xtea_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_CONFIG_WARNINGS 0
 
 #define TRICE_DEFERRED_TRANSFER_MODE TRICE_MULTI_PACK_MODE

_test/dblB_de_nopf_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_CONFIG_WARNINGS 0
 
 #define TRICE_DEFERRED_OUTPUT 1

_test/dblB_de_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DEFERRED_OUTPUT 1
 #define TRICE_DEFERRED_UARTA 1
 #define TRICE_UARTA

_test/dblB_de_xtea_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DEFERRED_OUTPUT 1
 #define TRICE_DEFERRED_XTEA_ENCRYPT 1
 #define TRICE_DEFERRED_OUT_FRAMING TRICE_FRAMING_COBS

_test/dblB_de_xtea_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_CONFIG_WARNINGS 0
 
 #define TRICE_DEFERRED_OUTPUT 1

_test/dblB_di_nopf_rtt32__de_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1
 

_test/dblB_di_nopf_rtt32__de_multi_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1
 

_test/dblB_di_nopf_rtt32__de_multi_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1
 

_test/dblB_di_nopf_rtt32__de_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1
 

_test/dblB_di_nopf_rtt32__de_xtea_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 // trice l -p jlink -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0" -showID "deb:%04x" -hs off -pw MySecret -pf COBS -d16=true
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1

_test/dblB_di_nopf_rtt8__de_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_8BIT_WRITE 1
 

_test/dblB_di_nopf_rtt8__de_multi_cobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_8BIT_WRITE 1
 

_test/dblB_di_nopf_rtt8__de_multi_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_8BIT_WRITE 1
 

_test/dblB_di_nopf_rtt8__de_tcobs_ua/triceConfig.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+#define TRICE_BUFFER TRICE_DOUBLE_BUFFER
+
 #define TRICE_DIRECT_OUTPUT 1
 #define TRICE_DIRECT_SEGGER_RTT_8BIT_WRITE 1