[WIP] Add comprehensive German-language documentation for PTP Grandmaster module

[Copilot]

• Explore codebase (ptp_gm_task.c, app.c, initialization.c, etc.)
• Create firmware/src/README_GM.md with all required sections:
  • Table of Contents
  • Section 1: Call Tree (Aufrufbaum) from main() to PTP_GM_Service()
  • Section 2: State Machine Flow (Zustandsmaschine Ablauf) - all 22 states
  • Section 3: Static Variables (Statische Variablen)
  • Section 4: Function Documentation (Funktionsdokumentation)
  • Section 5: Non-Blocking Architecture (Nicht-Blockierende Architektur)
  • Section 6: LAN8651 Integration
  • Section 7: PTP Protocol Implementation
  • Section 8: Issues and Risks (Probleme und Risiken)
  • Section 9: Optimization Opportunities (Optimierungsmöglichkeiten)
  • Glossary (Glossar)
• Validate that documentation is accurate and complete

Original prompt

Objective

Create a comprehensive German-language documentation file README_GM.md that thoroughly documents the PTP Grandmaster module (ptp_gm_task.c).

Required Content Sections

1. Call Tree (Aufrufbaum)

Document the complete call tree from main() to PTP_GM_Service() including:

• Main initialization path through SYS_Initialize() → APP_Initialize()
• Timer creation and configuration (1ms periodic timer)
• Detailed explanation of the timer interrupt mechanism:
  • TC0 hardware timer configuration (from initialization.c)
  • SYS_TIME service callback handling
  • How GM_TimerCallback() is invoked every 1ms
  • Condition check for PTP_MASTER mode
  • Final invocation of PTP_GM_Service()
• Clear distinction between polled tasks and interrupt-driven execution
• Visual representation (ASCII tree or detailed list)

2. State Machine Flow (Zustandsmaschine Ablauf)

Provide an exhaustive explanation of the state machine including:

• Complete state transition diagram showing all 19+ states
• Detailed description of each state:
  • GM_STATE_IDLE - initial/disabled state
  • GM_STATE_WAIT_PERIOD - periodic sync timing
  • GM_STATE_SEND_SYNC - frame preparation
  • GM_STATE_WRITE_TXMCTL / GM_STATE_WAIT_WRITE_TXMCTL - TX Match control
  • GM_STATE_WAIT_SYNC_TX_DONE - transmission confirmation
  • GM_STATE_WAIT_STATUS0 - timestamp capture polling
  • GM_STATE_READ_TTSCA_H / GM_STATE_WAIT_TTSCA_H - seconds register read
  • GM_STATE_READ_TTSCA_L / GM_STATE_WAIT_TTSCA_L - nanoseconds register read
  • GM_STATE_WRITE_CLEAR / GM_STATE_WAIT_CLEAR - W1C status clear
  • GM_STATE_SEND_FOLLOWUP / GM_STATE_WAIT_FOLLOWUP_TX_DONE - Follow-Up transmission
  • GM_STATE_INIT_WRITE / GM_STATE_WAIT_INIT_WRITE - initialization sequence
  • GM_STATE_DEINIT_WRITE / GM_STATE_WAIT_DEINIT_WRITE - deinitialization sequence
  • Legacy states: GM_STATE_READ_TXMCTL, GM_STATE_WAIT_TXMCTL, GM_STATE_READ_STATUS0
• State transition conditions and timeout handling
• Error recovery paths
• Timing diagrams for typical sync cycle

3. Static Variables (Statische Variablen)

Document all module-level static variables with purpose and usage:

• gm_state - current state machine state
• gm_op_done, gm_op_val - register operation synchronization
• gm_tx_busy - frame transmission flag
• gm_status0, gm_ts_sec, gm_ts_nsec - timestamp capture
• gm_tick_ms, gm_period_start - timing counters
• gm_seq_id, gm_sync_cnt - sequence tracking
• gm_retry_cnt, gm_wait_ticks - retry/timeout management
• gm_sync_interval_ms - configurable sync period
• gm_src_mac - source MAC address
• gm_dst_mode - destination mode (multicast/broadcast)
• gm_seq_step - init/deinit sequence step counter
• Frame buffers: gm_sync_buf, gm_followup_buf, gm_noip_buf
• Configuration arrays: gm_init_addrs/vals, gm_deinit_addrs/vals

4. Function Documentation (Funktionsdokumentation)

For each public and internal function, document:

• Public API functions:
  • PTP_GM_Init() - initialization and async register write kickoff
  • PTP_GM_Service() - main 1ms tick state machine
  • PTP_GM_Deinit() - cleanup and disarm sequence
  • PTP_GM_GetStatus() - status query
  • PTP_GM_SetSyncInterval() - interval configuration
  • PTP_GM_SetDstMode() / PTP_GM_GetDstMode() - destination mode
  • PTP_GM_RequestRegDump() - diagnostic register dump
• Internal helper functions:
  • gm_op_cb() - register read/write callback
  • gm_tx_cb() - frame TX done callback
  • gm_read_register(), gm_write_register() - register access wrappers
  • gm_send_raw_eth_frame() - raw frame transmission
  • gm_get_and_clear_ts_capture() - timestamp retrieval
  • build_eth_header() - Ethernet header construction
  • fill_clock_identity() - EUI-64 clock ID generation
  • build_sync() - PTP Sync message builder
  • build_followup() - PTP Follow-Up message builder
  • build_noip_test_frame() - test frame builder
  • gm_set_state() / gm_state_to_str() - state management

5. Non-Blocking Architecture (Nicht-Blockierende Architektur)

Critical focus area - explain in detail:

• Why non-blocking is essential: Hard real-time 1ms tick constraint, shared SPI bus, PLCA collision avoidance
• Callback-based register access:
  • All DRV_LAN865X_ReadRegister() / WriteRegister() calls use useCallbackProtectedMode=true
  • Callback sets gm_op_done flag and stores result in gm_op_val
  • State machine polls gm_op_done in WAIT states
  • Timeout protection with gm_wait_ticks counter (typically 200ms)
• Asynchronous frame transmission:
  • DRV_LAN865X_SendRawEthFrame() returns immediately
  • gm_tx_cb() clears gm_tx_busy flag when hardware completes TX
  • State machine waits in dedicated TX_DONE states
• Sequential init/deinit sequences:
  • Each register write confirmed via callback before next write
  • gm_seq_step tracks progress thr...

This pull request was created from Copilot chat.