# Continue Extension Rules for Embedded C Development

## Build & Development Commands
- Always use `make clean && make` for full rebuilds to avoid stale object files
- Use `make flash` or `make program` for deploying to target hardware
- Include `make debug` commands that generate debug symbols (-g flag) and disable optimizations (-O0)
- Set up cross-compilation toolchain commands (arm-none-eabi-gcc, avr-gcc, etc.) based on target MCU
- Use `make size` to check binary size against flash/RAM constraints
- Include static analysis commands: `cppcheck --enable=all src/`, `pc-lint`, or `splint`
- Set up MISRA-C compliance checking commands when applicable
- Use `objdump -d` for disassembly analysis and `nm` for symbol table inspection
- Include commands for generating map files to analyze memory usage
- Set up automated builds with different optimization levels (-Os, -O2, -O3)

## Testing Guidelines
- Write unit tests using Unity, CppUTest, or similar embedded-friendly frameworks
- Test on actual hardware, not just simulation - "it works on my simulator" isn't enough
- Create mock HAL (Hardware Abstraction Layer) functions for testing hardware-dependent code
- Test boundary conditions: maximum/minimum values, buffer overflows, timeout scenarios
- Use hardware-in-the-loop (HIL) testing for critical real-time functions
- Test interrupt service routines (ISRs) for timing constraints and reentrancy
- Validate memory usage doesn't exceed stack/heap limits using tools like Valgrind or static analysis
- Test power consumption scenarios and sleep/wake cycles
- Create stress tests that run for extended periods to catch memory leaks or stack overflow
- Test with different compiler optimization levels to catch optimization-related bugs

## Code Style & Guidelines
- Follow MISRA-C guidelines for safety-critical applications
- Use explicit integer types: `uint8_t`, `int16_t`, `uint32_t` instead of `int`, `char`
- Declare variables at the smallest possible scope
- Use `const` keyword extensively for read-only data and function parameters
- Avoid dynamic memory allocation (`malloc`, `free`) - use static allocation
- Keep functions small and single-purpose (max 50 lines recommended)
- Use meaningful variable names: `timer_count` not `tc`, `sensor_data` not `sd`
- Initialize all variables at declaration: `uint8_t status = 0;`
- Use `volatile` for variables accessed by interrupts or hardware registers
- Prefer bit manipulation over arithmetic: `flag |= (1 << BIT_POS)` instead of `flag += pow(2, BIT_POS)`
- Use `#define` for constants and bit masks: `#define LED_PIN (1 << 5)`
- Implement defensive programming: check function parameters, return values
- Use consistent indentation (4 spaces) and brace placement
- Limit line length to 80-100 characters for readability
- Use header guards or `#pragma once` in all header files

## Documentation Guidelines
- Document all public functions with purpose, parameters, return values, and side effects
- Include timing requirements and constraints in function documentation
- Document interrupt priorities and timing-critical sections
- Maintain a memory map document showing RAM/Flash usage
- Document pin assignments and hardware connections
- Include power consumption estimates for different operational modes
- Document communication protocols (UART, SPI, I2C) with timing diagrams
- Maintain a register map for custom peripherals or complex configurations
- Document calibration procedures and factory default values
- Include example usage code in header file comments
- Document known limitations, workarounds, and hardware errata
- Use Doxygen-style comments for automatic documentation generation:
  ```c
  /**
   * @brief Initializes the ADC peripheral
   * @param[in] channel ADC channel to configure (0-7)
   * @param[in] resolution ADC resolution in bits (8, 10, 12)
   * @return 0 on success, -1 on error
   * @note This function must be called before any ADC operations
   * @warning Calling this function disables all ADC interrupts
   */
  ```
- Include revision history and change logs in source file headers
- Document any assembly language sections with clear explanations

Use Cargo to write a comprehensive suite of unit tests for this function