Skip to content

xcplib_cfg.md

Latest commit

 

History

History
184 lines (135 loc) · 9.26 KB

xcplib_cfg.md

File metadata and controls

184 lines (135 loc) · 9.26 KB

XCPlite Configuration Guide

Version: 2.0.0

0 · XCPlite Configuration

The default configuration of XCPlite should work on any platform out of the box, with most featutures enabled and a typical parameter configuration.

However, there are several reasons, why to change the default configuration:

  1. Optimize memory usage
  2. Enable/disable features
  3. Modify communication parameters

Most important parameters are:

  1. Maximum number of calibration segments and events
  2. Maximum size of the DAQ table, on maximum fragmentation, a measurement signal may need up to 6 bytes in DAQ table memory
  3. MTU for UDP (Jumbo frames)
  4. Clock source, epoch and resolution

The size of the transmission queue is a runtime parameter.

1 · xcplib_cfg.h

This section describes the configuration parameters in xcplib_cfg.h.

XCP Protocol Options

Parameter Description
OPTION_ENABLE_TCP Enables TCP transport layer support for XCP communication
OPTION_ENABLE_UDP Enables UDP transport layer support for XCP communication
OPTION_MTU Ethernet packet size (MTU) in bytes. Must be divisible by 8. Jumbo frames are supported (default: 8000)
OPTION_DAQ_MEM_SIZE Memory bytes used for XCP DAQ tables. Each signal needs approximately 5 bytes (default: 32 × 1024 × 5)
OPTION_ENABLE_A2L_UPLOAD Enables A2L file upload through XCP protocol
OPTION_ENABLE_ELF_UPLOAD Enables ELF file upload through XCP protocol
OPTION_SERVER_FORCEFULL_TERMINATION Terminates server threads forcefully instead of waiting for graceful shutdown

Clock Configuration Options

Parameter Description
OPTION_CLOCK_EPOCH_ARB Uses arbitrary epoch (CLOCK_MONOTONIC_RAW on Linux, CLOCK_MONOTONIC on QNX) for DAQ timestamps
OPTION_CLOCK_EPOCH_PTP Uses PTP epoch (CLOCK_REALTIME which may be disciplined by NTP or PTP4L on Linux) for DAQ timestamps
OPTION_CLOCK_TICKS_1NS Sets clock resolution to 1 nanosecond
OPTION_CLOCK_TICKS_1US Sets clock resolution to 1 microsecond

Network Options

Parameter Description
OPTION_ENABLE_GET_LOCAL_ADDR Enables automatic determination of local IP address for A2L files when bound to ANY (0.0.0.0).

Logging Options

Parameter Description
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_MAX_DBG_LEVEL Maximum runtime adjustable debug level, higher level optimized out
OPTION_FIXED_DBG_LEVEL Sets a fixed, not runtime adjustable logging level

2 · xcptl_cfg.h

This section describes the transport layer configuration parameters in xcptl_cfg.h.

Transport Layer Version

Parameter Description
XCP_TRANSPORT_LAYER_VERSION Defines the XCP transport layer version (0x0104)

Packet Size Configuration

Parameter Description
XCPTL_MAX_CTO_SIZE Maximum size of XCP command packets (CRO/CRM) in bytes. Must be divisible by 8 (default: 248)
XCPTL_MAX_DTO_SIZE Maximum size of XCP data packets (DAQ/STIM) in bytes. Must be divisible by 8 (default: 1024)
XCPTL_MAX_SEGMENT_SIZE Maximum data buffer size for socket send operations. For UDP, this is the UDP MTU. Calculated as OPTION_MTU - 32 (IP header)
XCPTL_PACKET_ALIGNMENT Packet alignment for multiple XCP transport layer packets in a message (default: 4)
XCPTL_TRANSPORT_LAYER_HEADER_SIZE Transport layer message header size in bytes (fixed: 4)

Multicast Configuration

Parameter Description
XCPTL_ENABLE_MULTICAST Enables multicast time synchronization for improved synchronization of multiple XCP slaves
XCLTL_RESTRICT_MULTICAST Restricts multicast functionality (optional)
XCPTL_MULTICAST_PORT Port number for multicast communication (default: 5557)

Note on Multicast: Multicast time synchronization is available since XCP V1.3 but requires an additional thread and socket. There's no benefit if PTP time synchronization is used or with only one XCP device. Older CANape versions may expect this option to be enabled by default.

3 · xcp_cfg.h

This section describes the XCP protocol layer configuration parameters in xcp_cfg.h.

Version Configuration

Parameter Description
XCP_DRIVER_VERSION XCP driver version for GET_COMM_MODE_INFO command
XCP_ENABLE_PROTOCOL_LAYER_ETH Enables Ethernet-specific protocol layer commands
XCP_PROTOCOL_LAYER_VERSION XCP protocol layer version (0x0104 - supports PACKED_MODE, CC_START_STOP_SYNCH)

Address and Address Extension Configuration

Parameter Description
XCP_ENABLE_DAQ_ADDREXT Enables individual address extensions for each ODT entry
XCP_ENABLE_REL_ADDRESSING Enables event-based relative addressing modes without asynchronous access
XCP_ADDR_EXT_REL Address extension code for relative address format (default: 0x03)
XCP_ENABLE_DYN_ADDRESSING Enables event-based addressing modes with asynchronous access
XCP_ADDR_EXT_DYN Address extension for dynamic addressing (default: 0x02)
XCP_ADDR_EXT_DYN_COUNT Max number of DYN address extensions for dynamic addressing (default: 14)
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_ADDR_EXT_SEG Address extension for segment relative addressing (must be 0x00)

Protocol Features

Parameter Description
XCP_ENABLE_CAL_PAGE Enables calibration page switching commands GET/SET_CAL_PAGE
XCP_ENABLE_COPY_CAL_PAGE Enables calibration page initialization COPY_CAL_PAGE (FLASH→RAM copy only supported)
XCP_ENABLE_COPY_CAL_PAGE_WORKAROUND Enables a workaround for older CANapes (see xcp_cfg.h)
XCP_ENABLE_FREEZE_CAL_PAGE Enables calibration page freeze functionality (GET/SET_SEGMENT_MODE), required for calibration segment persistence
XCP_ENABLE_CHECKSUM Enables checksum calculation command
XCP_CHECKSUM_TYPE Checksum algorithm type (XCP_CHECKSUM_TYPE_CRC16CCITT or XCP_CHECKSUM_TYPE_ADD44)
XCP_ENABLE_SEED_KEY Enables seed/key security mechanism (commented out by default)
XCP_ENABLE_SERV_TEXT Enables SERV_TEXT events
XCP_ENABLE_IDT_A2L_UPLOAD Enables A2L file upload via XCP (depends on OPTION_ENABLE_A2L_UPLOAD)
XCP_ENABLE_IDT_ELF_UPLOAD Enables ELF file upload via XCP (depends on OPTION_ENABLE_ELF_UPLOAD)
XCP_ENABLE_USER_COMMAND Enables user-defined commands for atomic calibration operations

DAQ Features and Parameters

Parameter Description
XCP_MAX_EVENT_COUNT Maximum number of DAQ events. Must be even. Optimizes DAQ list to event association lookup (default: 256)
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_PRESCALER Enables DAQ prescaler (downsampling)
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
XCP_MAX_EVENT_NAME Maximum length for event names in characters (default: 15)

Calibration Segment Configuration

Parameter Description
XCP_ENABLE_CALSEG_LIST Enables calibration segment list management (not needed for Rust xcp-lite)
XCP_MAX_CALSEG_COUNT Maximum number of calibration segments (default: 32)
XCP_CAL_MEM_SIZE Static memory allocation for calibration segment memory (default: 16 KB)
XCP_ENABLE_CALSEG_LAZY_WRITE Enables lazy write mode for calibration segments with background RCU updates
XCP_CALSEG_AQUIRE_FREE_PAGE_TIMEOUT Timeout for acquiring free calibration segment pages in milliseconds (default: 500)

Clock and Timestamp Configuration

Parameter Description
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

Multicast Clock Synchronization

Parameter Description
XCP_ENABLE_DAQ_CLOCK_MULTICAST Enables GET_DAQ_CLOCK_MULTICAST functionality (not recommended)
XCP_MULTICAST_CLUSTER_ID XCP multicast cluster ID for time synchronization (default: 1)

Queue Runtime Configuration

The queue size is configured at runtime when calling queueInit(buffer_size). The buffer size determines:

  • Total memory allocated for the queue
  • Number of queue entries that can be stored
  • 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.