register-debug

# Skill: Professional Embedded Register Debugging

## 1. CMSIS-SVD (System View Description)

* **Role**: XML-based standard defining the memory map of peripherals, registers, and bitfields for a specific MCU.
* **Usage**:
  * **Debugger Loading**: Ensure the `.svd` file is correctly linked in your IDE (e.g., VS Code `cortex-debug.deviceDefinitionPath`).
  * **Symbolic Access**: Use the peripheral names (e.g., `RCC->AHB1ENR`) instead of magic addresses (`0x40023800`).

## 2. Bitfield Manipulation Best Practices

* **Logic**:
  * **Masking (Recommended)**: `REG = (REG & ~MASK) | (VALUE << POS);` ensures only target bits are modified.
  * **Atomic Access**: Leverage hardware-specific atomic features (e.g., ARM Bit-banding or Bit Set/Reset registers like `GPIOx_BSRR`) to avoid race conditions.
* **Avoid**: Using C struct bitfields for hardware mapping unless the compiler's padding and endianness behavior is strictly documented and guaranteed.

## 3. The "Pitfall" Checklist

* **Read-to-Clear (RC)**:
  * *Symptom*: Flags disappear unexpectedly.
  * *Cause*: Debugger "Watch" window or a print statement reads the status register, clearing the flag before code can process it.
  * *Solution*: In debuggers, freeze the peripheral or use variables to cache the register value.
* **Write-Only (WO)**:
  * *Challenge*: Reading returns garbage or 0.
  * *Solution*: Maintain a **Shadow Register** (software variable) that mirrors the last written value.
* **Volatile**:
  * *Rule*: EVERY variable mapping to a hardware register MUST be marked `volatile`.

## 4. Debugging Workflow (AI Prompt)

1. **Identify**: Match chip model (e.g., STM32H7, ESP32-S3) to its SVD/Memory Map.
2. **Verify Reset State**: If a peripheral fails, compare all control registers against the "Reset Value" in the reference manual.
3. **Inspect Clock/Power**: Verify the corresponding clock enable bit (e.g., `RCC_AHB1ENR`) is set before accessing other registers.
4. **Hardware Invariants**: Check for illegal state transitions defined in the hardware logic (e.g., changing baud rate while UART is enabled).