Refactor addressing modes (#98)

* GET_SEGMENT_INFO and GET_PAGE_INFO
* Use macros to abstract the addressing mode encoding
* Integer limits without floating point format
* Send async command responses via the transmit queue
* SetRelativeAddrMode1/2
* CANape projects updated
* Compatibility with xcp-lite for Rust
* Documentation improvements
* Workaround for CANape COPY_CAL_PAGE limitations
* Workaround CANape handling of EPK segment
* GET_DAQ_EVENT_INFO enabled
* EPK calibration segment optional

Author: RainerZ

.vscode/tasks.json

@@ -307,6 +307,30 @@
             "group": "build",
             "detail": "Kill any running XCP demo processes on Raspberry Pi"
         },
+        {
+            "type": "shell",
+            "label": "XCPlite: Download executables from Pi",
+            "command": "rsync",
+            "args": [
+                "-avz",
+                "--include=\"*.out\"",
+                "--include=\"*.a\"",
+                "--exclude=\"*\"",
+                "[email protected]:~/XCPlite-RainerZ/build/",
+                "./build/"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "shared"
+            },
+            "detail": "Download executable files (*.out, *.a) from Raspberry Pi build directory"
+        },
     ],
     "version": "2.0.0"
 }

README.md

@@ -340,12 +340,20 @@ The addressing mode is indicated by the address extension:
 
 - Sockets (Linux: socket, ...).  
 
-### Known issues and suggestions for improvement
-
-- Initialize RAM (COPY_CAL_PAGE) is executed only on the first calibration segment.  
-- GET_SEGMENT_MODE is executed multiple times on the last calibration segment before freeze request.  
-- Address extension of memory segment is ignored by CANape, using 0 for calibration segment relative addressing.  
-- Request for unique address extension per DAQ list is ignored by CANape (DAQ_KEY_BYTE == DAQ_EXT_DAQ), this forces us to store store the address extension per ODT entry.  
+### Known issues
+
+- COPY_CAL_PAGE: CANape initialize RAM is executed only on the first calibration segment. Workaround: always copy all segments.  
+- CANape ignores segment numbers in A2L, if segment numbering starts with 1, SET_CAL_PAGE is executed on segment 0 and 1
+- GET_ID 5 (EPK) mode = 0x01 is ignored by CANape. Workaround: always provide EPK via upload.  
+- CANape executes GET_SEGMENT_MODE multiple times on the last calibration segment before freeze request.  
+- Address extension of memory segment is ignored by CANape. Workaround: using 0 for calibration segment relative addressing.  
+- Request for unique address extension per DAQ list is ignored by CANape (DAQ_KEY_BYTE == DAQ_EXT_DAQ). Workaround: Store the address extension per ODT entry.  
 - CANape < V24 does not support shared axis in typedefs or THIS. axis references.  
-- Transport Layer counter mutex could be avoided with different counter mode.  
-- Indicate when polling access is not possible.  
+- Transport Layer counter mutex could be avoided with alternative counter mode, which is not default in CANape.  
+- Indicate when polling access is not possible. CANape assumes polling access is always possible.  
+- Configuration for begin/end atomic calibration user defined XCP commend is not default. Must be set once in a new CANape project to 0x01F1 and 0x02F1.  
+
+### Todo
+
+- CANape ignores address extension of loop_histogram in ccp_demo, when saving calibration values to a parameter file
+  loop_histogram is a CHARACTERISTIC array, but it is in a measurement group

docs/xcplib.md

@@ -11,7 +11,6 @@
 5. [A2l Creator](#5-a2l-creator)
 6. [Glossary](#6-glossary)
 
-
 ---
 
 ## 1 · Overview
@@ -22,8 +21,8 @@ All functions are *C linkage* and can therefore be consumed directly from C/C++
 Key features:
 
 - Single‑instance XCP server (TCP or UDP)
-- Lock‑free calibration segments
-- Measurement events to capture global, stack and heap data
+- Lock‑free calibration parameter segments
+- Timestamped measurement events to capture global, stack and heap data
 - Optional A2L file meta data and type generation at runtime
 
 ---
@@ -40,7 +39,7 @@ Key features:
 2. **Set log level (optional)**
 
 ```c
-   XcpSetLogLevel(5); // (1=error, 2=warning, 3=info, 4=debug, 5=trace):
+   XcpSetLogLevel(3); // (1=error, 2=warning, 3=info, 4=debug (XCP commands), 5=trace)
 ```
 
 3. **Initialise the XCP core** *once*:
@@ -66,7 +65,7 @@ Key features:
 
 ## 3 · API Reference
 
-### 3.0 · Initialisation
+### Initialization
 
 #### void XcpInit( bool activate)
 
@@ -111,10 +110,62 @@ All out‑parameters are *optional* and may be passed as `NULL`.
 
 See function and macro documentation in xcplib.h
 
+---
+
 ### 3.3 Events
 
 See function and macro documentation in xcplib.h
 
+---
+
+### 3.4 A2L Generation
+
+#### bool A2lInit(const char *project_name, const char*epk, const uint8_t *address, uint16_t port, bool use_tcp, uint32_t mode_flags)
+
+Initializes the A2L generation system of XCPlite. This function must be called once before any A2L-related macros or API functions are used. It performs the following actions:
+
+- Allocates and initializes all internal data structures and files required for A2L file creation.
+- Enables runtime definition of parameters, measurements, type definitions, groups and conversion rules.
+
+**Parameters:**
+
+- `project_name`: Name of the project, used for the A2L and BIN file names.
+- `epk`: Optional software version string (EPK) for the A2L file. Pass `NULL` to use the default.
+- `address`: Default IPv4 address of the XCP server.
+- `port`: Port number of the XCP server.
+- `use_tcp`: If `true`, TCP transport is used; if `false`, UDP transport.
+- `mode_flags`: Bitwise combination of A2L generation mode flags controlling file creation and runtime behavior:
+  - `A2L_MODE_WRITE_ALWAYS` (0x01): Always write the A2L file, overwriting any existing file.
+  - `A2L_MODE_WRITE_ONCE` (0x02): Write the A2L file (.a2l) once after a rebuild; Uses the binary persistence file (.bin) to keep calibration segment and event numbers stable, even if the registration order changes.
+  - `A2L_MODE_FINALIZE_ON_CONNECT` (0x04): Finalize the A2L file when an XCP client connects, later registrations are not visible to the tool. If not set, the A2L file must be finalized manually.
+  - `A2L_MODE_AUTO_GROUPS` (0x08): Automatically create groups for measurement events and parameter segments in the A2L file.
+
+#### void A2lFinalize(void)
+
+Finalizes and writes the A2L file to disk. This function should be called when all measurements, parameters, events, and calibration segments have been registered and no further A2L definitions are expected. After finalization, the A2L file becomes visible to XCP tools and cannot be modified further during runtime.
+
+#### void A2lSetXxxAddrMode(...)
+
+XCPlite uses relative memory addressing. There are 4 different addressing modes. When an addressing mode is set, it is valid for all subsequent definitions of parameters and measurement variables.
+
+| Macro                   | Description                                                                                  |
+|------------------------ |---------------------------------------------------------------------------------------------|
+| `A2lSetSegmentAddrMode` | Sets segment-relative addressing mode for calibration parameters in a specific segment.      |
+| `A2lSetAbsoluteAddrMode`| Sets absolute addressing mode for variables in global memory space.                         |
+| `A2lSetStackAddrMode`   | Sets stack-relative addressing mode for variables on the stack (relative to frame pointer). |
+| `A2lSetRelativeAddrMode`| Sets relative addressing mode for variables relative to a base address (e.g., heap objects or class instances).|
+
+#### void A2lCreateXxxx(...)
+
+All A2L generation macros and functions are not thread safe. It is up to the user to ensure thread safety and to use once-patterns when definitions are called multiple times in nested functions or from different threads.
+The functions `A2lLock()` and `A2lUnlock()` may be used to lock sequences of A2L definitions. The macro `A2lOnce` may be used to create a once execution pattern for a block of A2L definitions.
+
+Also note that A2L definitions may be lazy, but the A2L file is finalized when an XCP tool connects (or when `A2lFinalize()` is called). All definitions after that point are ignored and not visible to the tool.
+
+All definitions of instances follow the same principle: Set the addressing mode first. The addressing mode is valid for all following definitions. The examples in the `examples/` folder show various ways how to create A2L artifacts.
+
+---
+
 ### 3.5 Miscellaneous Functions
 
 | Function                                                         | Purpose                                                         |
@@ -134,20 +185,8 @@ See function and macro documentation in xcplib.h
 
 See examples folder and README.md for a short descriptions of the example applications.
 
-## 5 · A2L Creator
-
-All A2l generation macros and functions are not thread safe. It is up to the user to take care for thread safety, as well as for once execution, when definitions are called multiple times in nested functions or from different threads.  
-The functions A2lLock() and A2lUnlock() may be used to lock sequences of A2L definitions.  
-The macro A2lOnce may be used to create a once execution pattern for a block of A2L definitions.  
-
-Also note that A2L definitions may be lazy, but the A2L file is finalized when a XCP tool connects. All definitions after that point are ignored and not visible to the tool.  
-
-All definitions of instances follow the sample principle: Set the addressing mode first. The addressing mode is valid for all following definitions.  
-The examples in the examples/folder show various way how to create A2L artifacts.  
-
 ## 6 · Glossary
 
-
 - **A2L** – ASAM MCD‑2 MC description file (measurement & calibration meta‑data).
 - **DAQ** – Data Acquisition (periodic or sporadic transmit of ECU variables).
 - **EPK** – Embedded Program Identifier (software version string embedded in the ECU).

docs/xcplib_cfg.md

@@ -57,6 +57,7 @@ This section describes the configuration parameters in main_cfg.h.
 |-----------|-------------|
 | `OPTION_ENABLE_DBG_PRINTS` | Enables debug print statements throughout the library |
 | `OPTION_DEFAULT_DBG_LEVEL` | Sets default logging level: 1=Error, 2=Warning, 3=Info, 4=Trace, 5=Debug (default: 2) |
+| `OPTION_FIXED_DBG_LEVEL` | Sets fixex logging level, for optimization of unused log prints |
 
 ## 2 · xcptl_cfg.h
 
@@ -111,21 +112,8 @@ This section describes the XCP protocol layer configuration parameters in xcp_cf
 | `XCP_ADDR_EXT_DYN` | Address extension code for dynamic addressing (default: 0x02) |
 | `XCP_ENABLE_ABS_ADDRESSING` | Enables asynchronous absolute addressing mode (not thread safe) |
 | `XCP_ADDR_EXT_ABS` | Address extension code for absolute addressing (default: 0x01) |
-| `XCP_ENABLE_APP_ADDRESSING` | Enables segment or application-specific addressing mode |
-| `XCP_ADDR_EXT_APP` | Address extension for application-specific memory access (default: 0x00) |
 | `XCP_ADDR_EXT_SEG` | Address extension for segment relative addressing (must be 0x00) |
 
-### Special Address Extensions
-
-| Parameter | Description |
-|-----------|-------------|
-| `XCP_ADDR_EXT_EPK` | Address extension for EPK upload memory space (0x00) |
-| `XCP_ADDR_EPK` | Base address for EPK memory space (0x80000000) |
-| `XCP_ADDR_EXT_A2L` | Address extension for A2L upload memory space (0xFD) |
-| `XCP_ADDR_A2l` | Base address for A2L memory space (0x00000000) |
-| `XCP_ADDR_EXT_PTR` | Address extension indicating gXcp.MtaPtr is valid (0xFE) |
-| `XCP_UNDEFINED_ADDR_EXT` | Undefined address extension marker (0xFF) |
-
 ### Protocol Features
 
 | Parameter | Description |
@@ -149,7 +137,7 @@ This section describes the XCP protocol layer configuration parameters in xcp_cf
 | `XCP_DAQ_MEM_SIZE` | Static memory allocation for DAQ tables. Each ODT entry needs 5 bytes, each DAQ list 12 bytes, each ODT 8 bytes |
 | `XCP_ENABLE_DAQ_RESUME` | Enables DAQ resume mode functionality |
 | `XCP_ENABLE_DAQ_EVENT_LIST` | Enables event list management (not needed for Rust xcp-lite) |
-| `XCP_ENABLE_DAQ_EVENT_INFO` | Enables XCP_GET_EVENT_INFO command (overrides A2L event information) |
+| `XCP_ENABLE_DAQ_EVENT_INFO` | Enables XCP_GET_EVENT_INFO command |
 | `XCP_MAX_EVENT_NAME` | Maximum length for event names in characters (default: 15) |
 
 ### Calibration Segment Configuration
@@ -166,8 +154,7 @@ This section describes the XCP protocol layer configuration parameters in xcp_cf
 
 | Parameter | Description |
 |-----------|-------------|
-| `XCP_DAQ_CLOCK_32BIT` | Uses 32-bit timestamps (commented out) |
-| `XCP_DAQ_CLOCK_64BIT` | Uses 64-bit timestamps (default) |
+| `XCP_DAQ_CLOCK_64BIT` | Uses XCP V1.3 64-bit timestamps (default) |
 | `XCP_TIMESTAMP_UNIT` | Timestamp unit (DAQ_TIMESTAMP_UNIT_1US or DAQ_TIMESTAMP_UNIT_1NS) |
 | `XCP_TIMESTAMP_TICKS` | Ticks per timestamp unit (default: 1) |
 | `XCP_ENABLE_PTP` | Enables PTP (Precision Time Protocol) grandmaster clock support |
@@ -212,27 +199,6 @@ The queue implementation can be configured using one of three mutually exclusive
 | `CACHE_LINE_SIZE` | Cache line size used to align queue entries and queue header. Set to 128 bytes to accommodate most modern CPU architectures |
 | `MAX_ENTRY_SIZE` | Maximum size of a single queue entry, calculated as `XCPTL_MAX_DTO_SIZE + XCPTL_TRANSPORT_LAYER_HEADER_SIZE`. Must be aligned to `XCPTL_PACKET_ALIGNMENT` |
 
-### Performance Testing and Profiling (Development Only)
-
-**Warning**: These parameters have significant performance impact and should NOT be enabled in production builds.
-
-| Parameter | Description |
-|-----------|-------------|
-| `TEST_ACQUIRE_LOCK_TIMING` | Enables timing measurement for queue acquire operations. Collects statistics on lock acquisition times including maximum, sum, and histogram data |
-| `TEST_ACQUIRE_SPIN_COUNT` | Enables spin count statistics for producer acquire operations. Tracks how many spin loops are needed during contention |
-| `TEST_CONSUMER_SEQ_LOCK_SPIN_COUNT` | Enables spin count statistics for consumer sequence lock operations. Tracks consumer spinning behavior with sequence locks |
-
-### Profiling Configuration Constants
-
-When profiling is enabled, the following constants control the statistics collection:
-
-| Parameter | Description |
-|-----------|-------------|
-| `LOCK_TIME_HISTOGRAM_SIZE` | Size of lock time histogram array (default: 100 entries) |
-| `LOCK_TIME_HISTOGRAM_STEP` | Step size for lock time measurements (10ns steps) |
-| `SPIN_COUNT_HISTOGRAM_SIZE` | Size of spin count histogram for producer statistics (default: 100 entries) |
-| `SEQ_LOCK_HISTOGRAM_SIZE` | Size of sequence lock histogram for consumer statistics (default: 200 entries) |
-
 ### Queue Runtime Configuration
 
 The queue size is configured at runtime when calling `QueueInit(buffer_size)`. The buffer size determines:
@@ -242,21 +208,3 @@ The queue size is configured at runtime when calling `QueueInit(buffer_size)`. T
 - Maximum throughput capacity
 
 **Memory Calculation**: Each queue entry requires `MAX_ENTRY_SIZE` bytes plus alignment overhead. The effective queue size is `buffer_size - MAX_ENTRY_SIZE`.
-
-### Platform Requirements
-
-The 64-bit queue implementation requires:
-
-- 64-bit POSIX platform (Linux or macOS)
-- Support for atomic operations
-- C11 or later for `stdatomic.h`
-
-On 32-bit platforms or Windows, the system automatically falls back to the 32-bit queue implementation (`xcpQueue32.c`).
-
-### Performance Recommendations
-
-1. **For High Throughput**: Use `QUEUE_MUTEX` if worst-case producer latency is acceptable
-2. **For Low Latency**: Use `QUEUE_SEQ_LOCK` but expect higher CPU usage due to spinning
-3. **For Balanced Performance**: Use `QUEUE_NO_LOCK` (default) for most applications
-4. **Buffer Sizing**: Allocate sufficient buffer size to handle peak data rates with some headroom
-5. **Testing**: Always benchmark different configurations with your specific workload patterns