MiniProfiler/docs/PROTOCOL.md

# MiniProfiler Communication Protocol

## Overview

MiniProfiler uses a binary command-response protocol over UART/Serial communication at 115200 baud (configurable).

- **Command packets**: Host → Embedded device
- **Response packets**: Embedded device → Host

## Command Packet Format

Commands are sent from the host to the embedded device.

### Structure

```
┌────────┬─────────┬─────────────┬──────────┬──────────┐
│ Header │ Command │ Payload Len │ Payload  │ Checksum │
│  (1B)  │  (1B)   │    (1B)     │  (8B)    │   (1B)   │
└────────┴─────────┴─────────────┴──────────┴──────────┘
Total: 12 bytes
```

### Fields

| Field | Size | Value | Description |
|-------|------|-------|-------------|
| Header | 1 byte | `0x55` | Packet start marker |
| Command | 1 byte | See table below | Command code |
| Payload Length | 1 byte | 0-8 | Actual payload size |
| Payload | 8 bytes | Variable | Command parameters (padded with 0x00) |
| Checksum | 1 byte | Sum of all bytes & 0xFF | Simple checksum |

### Command Codes

| Command | Code | Description | Payload |
|---------|------|-------------|---------|
| START_PROFILING | `0x01` | Start profiling | None |
| STOP_PROFILING | `0x02` | Stop profiling | None |
| GET_STATUS | `0x03` | Request status | None |
| RESET_BUFFERS | `0x04` | Clear profiling buffers | None |
| GET_METADATA | `0x05` | Request device metadata | None |
| SET_CONFIG | `0x06` | Configure profiler | Config bytes (reserved) |

### Example

Start profiling command:
```
55 01 00 00 00 00 00 00 00 00 00 56
│  │  │  └─────────────────────┘ │
│  │  │         Payload (8B)      │
│  │  └── Payload Length (0)      │
│  └── Command (START_PROFILING)  │
└── Header (0x55)                 └── Checksum
```

## Response Packet Format

Responses are sent from the embedded device to the host.

### Structure

```
┌─────────┬──────┬──────────┬──────────┬────────┬─────┐
│ Header  │ Type │  Length  │ Payload  │  CRC   │ End │
│  (2B)   │ (1B) │   (2B)   │ (N bytes)│  (2B)  │(1B) │
└─────────┴──────┴──────────┴──────────┴────────┴─────┘
Total: 8 + N bytes
```

### Fields

| Field | Size | Value | Description |
|-------|------|-------|-------------|
| Header | 2 bytes | `0xAA55` | Packet start marker (little-endian) |
| Type | 1 byte | See table below | Response type |
| Length | 2 bytes | 0-65535 | Payload size (little-endian) |
| Payload | Variable | Depends on type | Response data |
| CRC16 | 2 bytes | CRC16-CCITT | Checksum of header+type+length+payload |
| End | 1 byte | `0x0A` | Packet end marker (newline) |

### Response Types

| Type | Code | Description | Payload Format |
|------|------|-------------|----------------|
| ACK | `0x01` | Command acknowledged | None |
| NACK | `0x02` | Command failed | None |
| METADATA | `0x03` | Device metadata | See Metadata Payload |
| STATUS | `0x04` | Device status | See Status Payload |
| PROFILE_DATA | `0x05` | Profiling records | See Profile Data Payload |

## Payload Formats

### Metadata Payload (28 bytes)

Sent in response to `GET_METADATA` command or automatically on startup.

```c
struct MetadataPayload {
    uint32_t mcu_clock_hz;    // MCU clock frequency in Hz
    uint32_t timer_freq;      // Profiling timer frequency in Hz
    uint32_t elf_build_id;    // CRC32 of .text section for version matching
    char fw_version[16];      // Firmware version string (null-terminated)
} __attribute__((packed));
```

**Example:**
- MCU Clock: 168,000,000 Hz (168 MHz STM32F4)
- Timer Freq: 1,000,000 Hz (1 MHz for microsecond precision)
- Build ID: 0xDEADBEEF
- FW Version: "v1.0.0"

### Status Payload (10 bytes)

Sent in response to `GET_STATUS` command.

```c
struct StatusPayload {
    uint8_t is_profiling;           // 1 if profiling active, 0 otherwise
    uint32_t buffer_overflows;      // Number of buffer overflow events
    uint32_t records_captured;      // Total records captured
    uint8_t buffer_usage_percent;   // Current buffer usage (0-100)
} __attribute__((packed));
```

### Profile Data Payload (Variable)

Sent automatically during profiling or in response to data requests.

```c
struct ProfileDataPayload {
    uint8_t version;              // Protocol version (0x01)
    uint16_t record_count;        // Number of records in this packet
    ProfileRecord records[];      // Array of profile records
} __attribute__((packed));
```

Each `ProfileRecord` is 14 bytes:

```c
struct ProfileRecord {
    uint32_t func_addr;      // Function address (from instrumentation)
    uint32_t entry_time;     // Entry timestamp in microseconds
    uint32_t duration_us;    // Function duration in microseconds
    uint16_t depth;          // Call stack depth (0 = root)
} __attribute__((packed));
```

**Field Details:**
- `func_addr`: Return address from `__builtin_return_address(0)` in instrumentation hook
- `entry_time`: Microsecond timestamp when function was entered (wraps at ~71 minutes)
- `duration_us`: Time spent in function including children
- `depth`: Call stack depth (0 for main, 1 for functions called by main, etc.)

## Communication Flow

### Initial Connection

```
Host                    Device
  |                        |
  |--- GET_METADATA ------>|
  |<---- METADATA ---------|
  |                        |
  |--- START_PROFILING --->|
  |<---- ACK --------------|
  |                        |
  |<---- PROFILE_DATA -----|  (continuous stream)
  |<---- PROFILE_DATA -----|
  |<---- PROFILE_DATA -----|
  |         ...            |
```

### Typical Session

```
1. Host connects to serial port
2. Host sends GET_METADATA
3. Device responds with METADATA packet
4. Host sends START_PROFILING
5. Device responds with ACK
6. Device begins streaming PROFILE_DATA packets
7. Host processes and visualizes data in real-time
8. Host sends STOP_PROFILING when done
9. Device responds with ACK and stops streaming
```

## Error Handling

### CRC Mismatch
If the host detects a CRC mismatch:
- Log the error
- Discard the packet
- Continue listening for next packet
- No retransmission (real-time streaming)

### Packet Loss
- Sequence numbers not implemented (keeps protocol simple)
- Missing data will create gaps in visualization
- Not critical for profiling use case

### Buffer Overflow
- Device sets `buffer_overflows` counter in status
- Host should warn user
- Options: increase baud rate, reduce instrumentation, or use sampling

## Performance Considerations

### Bandwidth Calculation

At 115200 baud:
- Effective throughput: ~11.5 KB/s
- Profile record size: 14 bytes
- Packet overhead: ~8 bytes per packet
- Records per packet (typical): 20
- Packet size: 8 + 3 + 280 = 291 bytes
- Packets per second: ~39
- Records per second: ~780

**Recommendation:** If profiling >780 function calls/sec, increase baud rate to 460800 or 921600.

### Timing Overhead

Instrumentation overhead per function:
- Entry hook: ~0.5-1 μs
- Exit hook: ~0.5-1 μs
- Total: ~1-2 μs per function call

Target: <5% overhead for typical applications.

## Protocol Versioning

Current version: **0x01**

The `version` field in `ProfileDataPayload` allows for future protocol extensions:
- v0x01: Current format (entry_time + duration)
- v0x02: Future - could add ISR markers, task IDs, etc.
- v0x03: Future - compressed format, delta encoding

Host should check version and handle accordingly or reject unsupported versions.

## Example Packet Dumps

### GET_METADATA Command
```
55 05 00 00 00 00 00 00 00 00 00 5A
```

### METADATA Response
```
AA 55 03 1C 00                    // Header, Type=METADATA, Length=28
00 09 FB 0A                        // mcu_clock_hz = 168000000
40 42 0F 00                        // timer_freq = 1000000
EF BE AD DE                        // build_id = 0xDEADBEEF
76 31 2E 30 2E 30 00 ...          // fw_version = "v1.0.0\0..."
XX XX                              // CRC16
0A                                 // End marker
```

### PROFILE_DATA Response (2 records)
```
AA 55 05 1F 00                    // Header, Type=PROFILE_DATA, Length=31
01                                 // Version = 1
02 00                              // Record count = 2

// Record 1
00 01 00 08                        // func_addr = 0x08000100
E8 03 00 00                        // entry_time = 1000 μs
D0 07 00 00                        // duration = 2000 μs
00 00                              // depth = 0

// Record 2
20 02 00 08                        // func_addr = 0x08000220
F4 01 00 00                        // entry_time = 500 μs
2C 01 00 00                        // duration = 300 μs
01 00                              // depth = 1

XX XX                              // CRC16
0A                                 // End marker
```

## Implementation Notes

### Embedded Side
- Use DMA for UART transmission to minimize CPU overhead
- Implement ring buffer with power-of-2 size for efficient modulo operations
- Send packets in background task or idle hook
- Consider double-buffering: one buffer for capturing, one for transmitting

### Host Side
- Use state machine for packet parsing (don't assume atomicity)
- Handle partial packets gracefully
- Verify CRC before processing payload
- Use background thread for serial reading to not block UI

## References

- CRC16-CCITT: Polynomial 0x1021, initial value 0xFFFF
- Little-endian byte order for multi-byte integers
- GCC instrumentation: `__cyg_profile_func_enter/exit`