/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright (c) 2026 Embedya.
 *
 * TraxProbe porting layer (reference port). Licensed under the Apache License,
 * Version 2.0 (see LICENSE-Apache-2.0.txt). You may copy and modify this file
 * to support additional hardware or RTOS targets.
 *
 * This file depends on TraxProbe core headers, which remain licensed under the
 * TraxProbe Commercial License and are NOT relicensed by this notice.
 */

/**
 ******************************************************************************
 * @file           : trax_transport_config.h
 * @brief          : SEGGER RTT Transport Configuration for TraxProbe
 * @version        : 2.0.0
 ******************************************************************************
 * @attention
 * 
 * This is the ONLY file you need to modify for TraxProbe RTT configuration.
 * 
 * Architecture:
 *   ┌──────────────────┐     ┌─────────────┐     ┌────────┐
 *   │ TraxProbe Buffer │ ──► │ RTT UP      │ ──► │ J-Link │ ──► Host
 *   │     (4 KB)       │     └─────────────┘     └────────┘
 *   └──────────────────┘
 *                            ┌─────────────┐     ┌────────┐
 *   Command Parser     ◄──── │ RTT DOWN    │ ◄── │ J-Link │ ◄── Host
 *                            └─────────────┘     └────────┘
 * 
 ******************************************************************************
 */

#ifndef TRAX_TRANSPORT_CONFIG_H_
#define TRAX_TRANSPORT_CONFIG_H_

/*=============================================================================
 *                      RTT CHANNEL CONFIGURATION
 *============================================================================*/

#ifndef TRAX_RTT_UP_CHANNEL
#define TRAX_RTT_UP_CHANNEL         1
#endif

#ifndef TRAX_RTT_DOWN_CHANNEL
#define TRAX_RTT_DOWN_CHANNEL       1
#endif

/*=============================================================================
 *                      RTT BUFFER SIZE CONFIGURATION
 *============================================================================*/

#ifndef TRAX_RTT_BUFFER_SIZE_UP
#define TRAX_RTT_BUFFER_SIZE_UP     16384
#endif

#ifndef TRAX_RTT_BUFFER_SIZE_DOWN
#define TRAX_RTT_BUFFER_SIZE_DOWN   64
#endif

/*-----------------------------------------------------------------------------
 * RTT up-buffer mode — SEGGER_RTT_MODE_NO_BLOCK_SKIP (mandatory)
 *
 * TraxProbe deliberately uses non-blocking SKIP semantics on the up-channel.
 * Why:
 *
 *   1. Frame atomicity. The wire protocol is frame-granular; a half-written
 *      frame would desync the host parser. SKIP is all-or-nothing for the
 *      NumBytes we pass — exactly the contract we need. (TRIM is byte-
 *      granular and would corrupt frames; never use it here.)
 *
 *   2. No spin pathology. BLOCK_IF_FIFO_FULL drives SEGGER's _WriteBlocking
 *      into a tight loop that re-publishes an unchanged WrOff to uncached
 *      SRAM on every iteration while holding SEGGER_RTT_LOCK. On systems
 *      where the J-Link probe shares the AHB-AP with the CPU, that bus
 *      pressure has been observed to cause the J-Link GDB Server's RTT-
 *      telnet bridge to silently drop 4-byte chunks on Windows. SKIP never
 *      enters _WriteBlocking, so the pathology cannot occur. No headroom
 *      hack is needed.
 *
 *   3. All-or-stop on overflow. When the RTT ring is full,
 *      trax_transport_write() returns 0 (nothing written). That short write is
 *      a hard transport failure: trax_send_frames() does NOT advance the read
 *      pointer and arms TRAX_STOP_REASON_TRANSPORT_FAIL, so the host always
 *      gets an unambiguous stop instead of silently dropped frames. Size the
 *      up-buffer (TRAX_RTT_BUFFER_SIZE_UP) and drain rate so the ring does not
 *      overflow during a session.
 *
 * Override only if you intentionally want lossy semantics (TRIM is still
 * unsafe). For lossless operation, leave this as SKIP.
 *---------------------------------------------------------------------------*/
#ifndef TRAX_RTT_MODE
#define TRAX_RTT_MODE               SEGGER_RTT_MODE_NO_BLOCK_SKIP
#endif

/*=============================================================================
 *                      SEGGER RTT CONFIGURATION
 * 
 * These defines override SEGGER defaults in SEGGER_RTT_Conf.h.
 * SEGGER uses #ifndef guards, so defining them here takes precedence.
 * 
 * Channel 0: SEGGER terminal / printf  (uses SEGGER default buffer sizes)
 * Channel 1: TraxProbe binary stream   (buffers allocated in trax_transport_rtt.c)
 *============================================================================*/

#define SEGGER_RTT_MAX_NUM_UP_BUFFERS   2
#define SEGGER_RTT_MAX_NUM_DOWN_BUFFERS 2

#endif /* TRAX_TRANSPORT_CONFIG_H_ */
