Feature/trice bind mvp2 rebase

.clang-format

@@ -177,7 +177,7 @@ PointerAlignment: Left
 PPIndentWidth:   -1
 QualifierAlignment: Leave
 ReferenceAlignment: Pointer
-ReflowComments:  Always
+ReflowComments:  true
 RemoveBracesLLVM: false
 RemoveParentheses: Leave
 RemoveSemicolon: false

.clang-format-ignore

@@ -54,6 +54,12 @@ examples/*_bare/**
 # STM32 HAL driver code is machine-generated and should not be modified.
 examples/*_inst/Drivers/**
 
+# 3) Ignore every vendor middleware tree below ./examples/.
+#
+# These directories contain third-party sources such as FreeRTOS and must stay
+# byte-identical to the versions supplied by their vendors.
+examples/**/Middlewares/**
+
 
 
 ###############################################################################

.github/workflows/clang-format.yml

@@ -4,7 +4,7 @@ name: Clang-Format Check
 # are formatted according to the .clang-format rules.
 #
 # It uses:
-#   - clang-format (installed via apt)
+#   - clang-format 19.1.7 (installed in an isolated Python environment)
 #   - a Go-based helper (cmd/clang-filter) via `go run`
 #   - the shell script `./scripts/_format_c_code.sh` to orchestrate everything
 #
@@ -39,15 +39,20 @@ jobs:
           fetch-depth: 0
 
       #########################################################################
-      # 2) Install clang-format on the runner.
+      # 2) Install the repository's canonical clang-format release.
       #
-      # We rely on Ubuntu's clang-format package. If you require a specific
-      # version, you can pin it here or use a prebuilt toolchain image.
+      # clang-format output changes between releases. An unversioned apt package
+      # therefore makes local formatting and CI checks disagree when the hosted
+      # runner changes its Ubuntu image. The PyPI package supplies the exact
+      # native formatter binary in an isolated environment.
       #########################################################################
       - name: Install clang-format
         run: |
-          sudo apt-get update
-          sudo apt-get install -y clang-format
+          python3 -m venv "$RUNNER_TEMP/clang-format"
+          "$RUNNER_TEMP/clang-format/bin/python" -m pip install \
+            --disable-pip-version-check \
+            "clang-format==19.1.7"
+          echo "$RUNNER_TEMP/clang-format/bin" >> "$GITHUB_PATH"
 
       - name: Show clang-format version
         run: clang-format --version

README.md

@@ -46,9 +46,17 @@ Choose one first path:
 
 For most existing projects, the non-blocking byte writer path is the least disruptive first integration.
 
-## Coming soon
+## Recommended ID workflow: `trice bind`
 
-`trice bind ...` stores the IDs in sidecar build artifacts avoiding this way source code changes. This is complete compiler independent. Try it now in branch `wip`.
+`trice bind` is the successor to the legacy `trice insert` / `trice clean` workflow. It keeps numeric IDs out of bind-managed Trice calls by generating sidecar headers as temporary build artefacts. Existing `insert` / `clean` projects remain fully supported and continue to work unchanged. This technique does not patch the user sources anymore during the build process. See [Trice Bind in User Manual](./docs/TriceUserManual.md#trice-bind) for details.
+
+`trice bind` is currently experimental and is not yet included in an official release. To try it before the next release, build the `trice` tool from this repository and ensure the resulting executable is in your `PATH`:
+
+```sh
+./scripts/buildTriceTool.sh
+```
+
+Try the minimal [`demo`](./demo). It uses only the installed `trice` binary and the target sources in [`src`](./src) from this repository.
 
 ## Details and advanced topics
 
@@ -70,6 +78,8 @@ This reduces target FLASH usage, transfer bandwidth, log files and log-call exec
 
 <details markdown="1"><summary>How ID-based decoding works</summary>
 
+The recommended workflow uses `trice bind` as described above. The following steps describe the legacy source-modifying workflow, which remains supported:
+
 1. Write `trice(...)` calls in firmware code.
 2. Run `trice insert` before compilation.
 3. The compiler sees stable numeric IDs.
@@ -85,9 +95,9 @@ A typical source-level idea is:
 
 </details>
 
-<details markdown="1"><summary>What about source code modification?</summary>
+<details markdown="1"><summary>Legacy source-code ID workflow (still supported)</summary>
 
-Trice assigns IDs by processing source files with `trice insert`.
+The legacy workflow assigns IDs by processing source files with `trice insert`. This workflow remains supported for existing and new projects.
 A call such as this:
 
 ```c
@@ -166,10 +176,16 @@ You can also build your own receiver that reads Trice packages, maps IDs to form
 
 Keep the one accumulated `til.json` to decode all previously released firmware versions.
 The repository example file is [demoTIL.json](./demoTIL.json).
+Each `li.json` entry stores a normalized `File` path relative to the location-file
+directory by default. Use `-liRoot` to select a different project root when
+creating location data. Log output shows only the file name by default; use
+`-liMaxDirs` to include trailing parent directories.
 
 </details>
 
-<details markdown="1"><summary>Three common ID workflows</summary>
+<details markdown="1"><summary>Legacy insert/clean ID workflows (still supported)</summary>
+
+These three source-modifying workflows remain fully supported:
 
 **Keep IDs in source** - good for small projects and maximum robustness.
 
@@ -200,7 +216,7 @@ If other tools also rewrite source files, such as formatters or code generators,
 
 </details>
 
-<details markdown="1"><summary>Trice cache</summary>
+<details markdown="1"><summary>Legacy insert/clean cache (still supported)</summary>
 
 The Trice cache avoids unnecessary rebuilds when using `trice insert` and `trice clean` around the build.
 It keeps cached inserted and cleaned copies of unchanged files.
@@ -225,7 +241,7 @@ See [Trice Cache for Compilation Speed](./docs/TriceUserManual.md#trice-cache-fo
 
 </details>
 
-<details markdown="1"><summary>Normal workflow</summary>
+<details markdown="1"><summary>Legacy insert workflow (still supported)</summary>
 
 1. Add the Trice target sources from [`src/`](./src) to your firmware project.
 2. Add a project-specific `triceConfig.h`.

_test/abc_rx_host/device_abc.c

@@ -5,13 +5,13 @@
 #include "triceRx.h"
 
 const triceAbc_t triceAbc[] = {
-	/* Trice type */  /*   id, bitWidth, function pointer */
-	/* TRICe_C    */ {  1001u,   0u, rx_no_payload },
-	/* TRICE8_C   */ {  1006u,   8u, rx_i8_bulk },
-	/* TRICE16_C  */ {  1002u,  16u, rx_i16 },
-	/* TRIce32_C  */ {  1003u,  32u, rx_i32 },
-	/* Trice64C   */ {  1004u,  64u, rx_i64 },
-	/* TRiceC     */ {  1005u,   0u, rx_nested },
+    /* Trice type */ /*   id, bitWidth, function pointer */
+    /* TRICe_C    */ {1001u, 0u, rx_no_payload},
+    /* TRICE8_C   */ {1006u, 8u, rx_i8_bulk},
+    /* TRICE16_C  */ {1002u, 16u, rx_i16},
+    /* TRIce32_C  */ {1003u, 32u, rx_i32},
+    /* Trice64C   */ {1004u, 64u, rx_i64},
+    /* TRiceC     */ {1005u, 0u, rx_nested},
 };
 
 const unsigned triceAbcElements = sizeof(triceAbc) / sizeof(triceAbc[0]);

_test/abc_rx_host/triceAbcReceiveTest.c

@@ -8,9 +8,9 @@
 // triceLog is a small generated-table stand-in for testing log resolution
 // without adding another generated fixture file.
 const triceLog_t triceLog[] = {
-	{ 2001u, TRICE_DEFAULT_PARAMETER_BIT_WIDTH, 1u, "default:%d" },
-	{ 2002u, 0u, 0u, "cmd:no-payload" },
-	{ 2003u, 16u, TRICE_LOG_PARAM_COUNT_DYNAMIC, "cmd:%d" },
+    {2001u, TRICE_DEFAULT_PARAMETER_BIT_WIDTH, 1u, "default:%d"},
+    {2002u, 0u, 0u, "cmd:no-payload"},
+    {2003u, 16u, TRICE_LOG_PARAM_COUNT_DYNAMIC, "cmd:%d"},
 };
 
 // triceLogElements mirrors the generated element-count symbol used by runtime wrappers.
@@ -154,8 +154,8 @@ static int TriceAbcOnReceive(const uint8_t* pBuf, int len) {
 	}
 
 	rx.abcFnHandler(&rx);
-	//e = TriceDispatchAbc(&rx);
-	return used; //TRICE_RX_RESULT_OK; // (e == TRICE_RX_RESULT_OK || e == TRICE_RX_ERR_NOT_FOUND) ? used : TRICE_RX_ERR_PAYLOAD_LEN_BITWIDTH_MISMATCH;
+	// e = TriceDispatchAbc(&rx);
+	return used; // TRICE_RX_RESULT_OK; // (e == TRICE_RX_RESULT_OK || e == TRICE_RX_ERR_NOT_FOUND) ? used : TRICE_RX_ERR_PAYLOAD_LEN_BITWIDTH_MISMATCH;
 }
 
 // rx_i8_bulk verifies the long-count path and byte-granular payload handling.
@@ -263,7 +263,7 @@ static int triceValidateLogPayload(const triceRx_t* rx) {
 		return (rx->payloadBytes == 0u && rx->paramCount == 0u) ? TRICE_RX_RESULT_OK : TRICE_RX_ERR_PAYLOAD_LEN_BITWIDTH_MISMATCH;
 	}
 	{
-		uint32_t expectedBytes = (uint32_t)rx->paramCount * (uint32_t)(rx->bitWidth>>3);
+		uint32_t expectedBytes = (uint32_t)rx->paramCount * (uint32_t)(rx->bitWidth >> 3);
 		return (rx->payloadBytes == expectedBytes) ? TRICE_RX_RESULT_OK : TRICE_RX_ERR_PAYLOAD_LEN_BITWIDTH_MISMATCH;
 	}
 }
@@ -321,7 +321,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 2: { // Selected int16 payload ABC with 32-bit stamp dispatches one aligned payload record.
-		int16_t payload[2] = { 123, -456 };
+		int16_t payload[2] = {123, -456};
 		uint8_t record[16];
 		int used = rxBuildAbcRecord(record, 1002u, 32u, 0x12345678u, payload, (uint16_t)sizeof(payload), 0);
 		result = TriceAbcOnReceive(record, used);
@@ -330,7 +330,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 3: { // Selected int32 payload ABC without stamp dispatches one no-stamp record.
-		int32_t payload[1] = { 0x11223344 };
+		int32_t payload[1] = {0x11223344};
 		uint8_t record[8];
 		int used = rxBuildAbcRecord(record, 1003u, 0u, 0u, payload, (uint16_t)sizeof(payload), 0);
 		result = TriceAbcOnReceive(record, used);
@@ -339,7 +339,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 4: { // Selected int64 payload ABC with 16-bit stamp returns logical length without padding.
-		int64_t payload[1] = { (int64_t)0x1122334455667788ll };
+		int64_t payload[1] = {(int64_t)0x1122334455667788ll};
 		uint8_t record[16];
 		int used = rxBuildAbcRecord(record, 1004u, 16u, 0x8877u, payload, (uint16_t)sizeof(payload), 1);
 		result = TriceAbcOnReceive(record, used);
@@ -365,7 +365,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 7: { // Misaligned int32 payload size is rejected before handler execution.
-		uint8_t payload[2] = { 1u, 2u };
+		uint8_t payload[2] = {1u, 2u};
 		uint8_t record[8];
 		int used = rxBuildAbcRecord(record, 1003u, 0u, 0u, payload, (uint16_t)sizeof(payload), 0);
 		result = TriceAbcOnReceive(record, used);
@@ -374,7 +374,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 8: { // Truncated selected record is rejected before handler execution.
-		int16_t payload[2] = { 123, -456 };
+		int16_t payload[2] = {123, -456};
 		uint8_t record[16];
 		int used = rxBuildAbcRecord(record, 1002u, 32u, 0x12345678u, payload, (uint16_t)sizeof(payload), 0);
 		result = TriceAbcOnReceive(record, used - 1);
@@ -404,7 +404,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 11: { // Log resolver applies the configured default bit width to no-width log names.
-		int32_t payload[1] = { 0x01020304 };
+		int32_t payload[1] = {0x01020304};
 		uint8_t record[8];
 		triceRx_t rx;
 		int used = rxBuildAbcRecord(record, 2001u, 0u, 0u, payload, (uint16_t)sizeof(payload), 0);
@@ -433,12 +433,12 @@ int TriceAbcRxHostCheck(int n) {
 		rxFailUnless(rx.payload == 0);
 		rxFailUnless(rx.payloadBytes == 0u);
 		result = triceValidateLogPayload(&rx);
-		//rxFailUnless(result == TRICE_RX_ERR_UNSUPPORTED_X0_FRAME);
+		// rxFailUnless(result == TRICE_RX_ERR_UNSUPPORTED_X0_FRAME);
 		rxFailUnless(rxCalls == 0);
 		break;
 	}
 	case 13: { // Explicit log bit widths still win over the no-width default for resolved metadata.
-		int16_t payload[2] = { 11, 22 };
+		int16_t payload[2] = {11, 22};
 		uint8_t record[8];
 		triceRx_t rx;
 		int used = rxBuildAbcRecord(record, 2003u, 0u, 0u, payload, (uint16_t)sizeof(payload), 0);
@@ -451,16 +451,16 @@ int TriceAbcRxHostCheck(int n) {
 		rxFailUnless(rx.paramCount == TRICE_LOG_PARAM_COUNT_DYNAMIC);
 		rxFailUnless(rx.payloadBytes == sizeof(payload));
 		result = triceValidateLogPayload(&rx);
-		//rxFailUnless(result == TRICE_RX_ERR_UNSUPPORTED_X0_FRAME);
+		// rxFailUnless(result == TRICE_RX_ERR_UNSUPPORTED_X0_FRAME);
 		rxFailUnless(rxCalls == 0);
 		break;
 	}
 	case 14: { // TriceLogOnReceive consumes known and unknown log IDs without dispatch side effects.
-		int32_t payload[1] = { 0x55667788 };
+		int32_t payload[1] = {0x55667788};
 		uint8_t record[8];
 		int used = rxBuildAbcRecord(record, 2001u, 0u, 0u, payload, (uint16_t)sizeof(payload), 0);
 		result = TriceLogOnReceive(record, used);
-		//rxFailUnless(result == used);
+		// rxFailUnless(result == used);
 		used = rxBuildAbcRecord(record, 2999u, 0u, 0u, 0, 0u, 0);
 		result = TriceLogOnReceive(record, used);
 		rxFailUnless(result == used);
@@ -473,7 +473,7 @@ int TriceAbcRxHostCheck(int n) {
 		break;
 	}
 	case 15: { // A caller advances through a stream because TriceAbcOnReceive consumes only one record.
-		int32_t payload[1] = { 0x11223344 };
+		int32_t payload[1] = {0x11223344};
 		uint8_t stream[16];
 		int firstLen;
 		int secondLen;

_test/abc_tx_host/triceAbcTransmitTest.c

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-// TRICE_INSERT_OFF - Trice parser exclusion marker 
+// TRICE_INSERT_OFF - Trice parser exclusion marker
 // This is a test file. It must not get the Trice IDs changed!
 
 #include <string.h>
@@ -29,35 +29,35 @@ int TriceAbcTxHostCheck(int n) {
 	abcTxReset();
 	switch (n) {
 	case 1: {
-		static const uint8_t expected[] = { 0x34u, 0x52u, 0xc0u, 0x00u };
+		static const uint8_t expected[] = {0x34u, 0x52u, 0xc0u, 0x00u};
 		triceC(iD(0x1234), "cmd:stop");
 		return abcTxEquals(expected, sizeof(expected)) ? 0 : 1;
 	}
 	case 2: {
-		static const uint8_t expected[] = { 0x23u, 0x81u, 0x23u, 0x81u, 0xcdu, 0xabu, 0xc0u, 0x00u };
+		static const uint8_t expected[] = {0x23u, 0x81u, 0x23u, 0x81u, 0xcdu, 0xabu, 0xc0u, 0x00u};
 		TriceC(iD(0x0123), "cmd:stop", 0xabcdu);
 		return abcTxEquals(expected, sizeof(expected)) ? 0 : 2;
 	}
 	case 3: {
-		static const uint8_t expected[] = { 0x23u, 0xc1u, 0x44u, 0x33u, 0x22u, 0x11u, 0xc0u, 0x00u };
+		static const uint8_t expected[] = {0x23u, 0xc1u, 0x44u, 0x33u, 0x22u, 0x11u, 0xc0u, 0x00u};
 		TRiceC(iD(0x0123), "cmd:stop", 0x11223344u);
 		return abcTxEquals(expected, sizeof(expected)) ? 0 : 3;
 	}
 	case 4: {
-		int8_t payload[] = { 1, 2, 3 };
-		static const uint8_t expected[] = { 0x55u, 0x40u, 0xc0u, 0x03u, 0x01u, 0x02u, 0x03u, 0x00u };
+		int8_t payload[] = {1, 2, 3};
+		static const uint8_t expected[] = {0x55u, 0x40u, 0xc0u, 0x03u, 0x01u, 0x02u, 0x03u, 0x00u};
 		trice8C(iD(0x0055), "cmd:set_leds", payload, 3);
 		return abcTxEquals(expected, sizeof(expected)) ? 0 : 4;
 	}
 	case 5: {
-		int16_t payload[] = { 0x1122, 0x3344 };
-		static const uint8_t expected[] = { 0x23u, 0x81u, 0x23u, 0x81u, 0xcdu, 0xabu, 0xc0u, 0x04u, 0x22u, 0x11u, 0x44u, 0x33u };
+		int16_t payload[] = {0x1122, 0x3344};
+		static const uint8_t expected[] = {0x23u, 0x81u, 0x23u, 0x81u, 0xcdu, 0xabu, 0xc0u, 0x04u, 0x22u, 0x11u, 0x44u, 0x33u};
 		Trice16C(iD(0x0123), "cmd:set_pwm", 0xabcdu, payload, 2);
 		return abcTxEquals(expected, sizeof(expected)) ? 0 : 5;
 	}
 	case 6: {
-		int32_t payload[] = { 0x11223344 };
-		static const uint8_t expected[] = { 0x23u, 0xc1u, 0x04u, 0x03u, 0x02u, 0x01u, 0xc0u, 0x04u, 0x44u, 0x33u, 0x22u, 0x11u };
+		int32_t payload[] = {0x11223344};
+		static const uint8_t expected[] = {0x23u, 0xc1u, 0x04u, 0x03u, 0x02u, 0x01u, 0xc0u, 0x04u, 0x44u, 0x33u, 0x22u, 0x11u};
 		TRice32C(iD(0x0123), "cmd:set_time", 0x01020304u, payload, 1);
 		return abcTxEquals(expected, sizeof(expected)) ? 0 : 6;
 	}

_test/abc_tx_host/triceConfig.h

@@ -15,8 +15,14 @@ extern "C" {
 extern uint32_t abcTxWords[];
 extern uint32_t abcTxLength;
 
-#define TRICE_ENTER do { uint32_t* TriceBufferWritePosition = abcTxWords;
-#define TRICE_LEAVE abcTxLength = (uint32_t)((uint8_t*)TriceBufferWritePosition - (uint8_t*)abcTxWords); } while (0);
+#define TRICE_ENTER \
+	do {            \
+		uint32_t* TriceBufferWritePosition = abcTxWords;
+#define TRICE_LEAVE                                                                      \
+	abcTxLength = (uint32_t)((uint8_t*)TriceBufferWritePosition - (uint8_t*)abcTxWords); \
+	}                                                                                    \
+	while (0)                                                                            \
+		;
 
 #ifdef __cplusplus
 }

_test/alias_dblB_de_tcobs_ua/TargetActivity.c

@@ -4,6 +4,7 @@
 //! \details Go func triceLogSpecialTest parses additionally this file to collect the expected results line by line for later test execution.
 
 #include "trice.h"
+#include "trice_TargetActivity_c_KF1E016F27623CC56.h" // trice-bind: keep as last include before this file's Trice calls
 
 // The strings behind "//exp:" are the expected result for each line (-color=off)
 // Lines ending with a comment starting with `//exp:` are executed during the automatic Go tests.

_test/alias_dblB_de_tcobs_ua/triceConfig.h

@@ -26,12 +26,16 @@ extern "C" {
 //! prints is a user print example with string, float and integer values.
 //! We have to perform a normal print into a buffer, which then is passed to triceS.
 //! This is slow but we can integrate user code without changing it.
-#define prints(id, ...)                                \
-	do {                                               \
-		char buf[96];                                  \
-		npf_snprintf(buf, sizeof(buf), __VA_ARGS__);   \
-		triceS(id, "%s", buf);                         \
+// Route the registered simple alias at its invocation site so bound sources
+// obtain the ID from their sidecar and inserted sources retain their ID argument.
+#define PRINTS_WITH_ID(id, ...)                      \
+	do {                                             \
+		char buf[96];                                \
+		npf_snprintf(buf, sizeof(buf), __VA_ARGS__); \
+		TRICE_INSERT_triceS(id, "%s", buf);          \
 	} while (0)
+#define prints(...) \
+	TRICE_BIND_DISPATCH(TRICE_BIND_ROUTE(TRICE_BIND_FILE_KEY), PRINTS_WITH_ID, __VA_ARGS__)
 
 //
 //////////////////////////////////////////////////////////////////////////////

_test/aliasassert_dblB_de_tcobs_ua/TargetActivity.c

@@ -4,6 +4,7 @@
 //! \details Go func triceLogSpecialTest parses additionally this file to collect the expected results line by line for later test execution.
 
 #include "trice.h"
+#include "trice_TargetActivity_c_K707A6451A08AFEBA.h" // trice-bind: keep as last include before this file's Trice calls
 
 // The strings behind "//exp:" are the expected result for each line (-color=off)
 // Lines ending with a comment starting with `//exp:` are executed during the automatic Go tests.