@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/c/examples/embedded/README.md

@@ -0,0 +1,167 @@
+# Embedded Systems Examples
+
+This directory contains C examples demonstrating embedded systems programming best practices for microcontrollers.
+
+## Examples
+
+### 1. gpio-control.c
+Demonstrates GPIO (General Purpose Input/Output) control:
+- Memory-mapped I/O for hardware registers
+- Volatile keyword for hardware access
+- Bit manipulation techniques
+- Hardware abstraction layer pattern
+- LED control and button reading
+
+**Key Concepts:**
+- Always use `volatile` for hardware registers
+- Use bit manipulation for register access
+- Implement hardware abstraction layers
+- Atomic register operations with BSRR
+
+### 2. timer-isr.c
+Demonstrates timer interrupt service routines:
+- Timer configuration for periodic interrupts
+- ISR implementation best practices
+- Volatile variables for ISR/main communication
+- Minimal ISR execution time
+- Timeout and delay functions
+
+**Key Concepts:**
+- Keep ISRs short and fast
+- Use `volatile` for ISR-shared variables
+- Clear interrupt flags in ISR
+- No blocking operations in ISRs
+- Defer processing to main loop
+
+### 3. uart-communication.c
+Demonstrates UART serial communication:
+- UART initialization and configuration
+- Interrupt-driven reception
+- Circular buffer implementation
+- Non-blocking I/O
+- Error handling
+
+**Key Concepts:**
+- Use circular buffers for data buffering
+- Interrupt-driven reception
+- Polling for transmission
+- Handle overrun and framing errors
+- Non-blocking API design
+
+## Building
+
+These examples are designed for ARM Cortex-M microcontrollers. Adjust register addresses and build commands for your specific hardware.
+
+### For ARM Cortex-M (e.g., STM32)
+
+```bash
+# Using arm-none-eabi-gcc
+arm-none-eabi-gcc -mcpu=cortex-m3 -mthumb -O2 -Wall -Wextra \
+    -o gpio-control.elf gpio-control.c
+
+arm-none-eabi-gcc -mcpu=cortex-m3 -mthumb -O2 -Wall -Wextra \
+    -o timer-isr.elf timer-isr.c
+
+arm-none-eabi-gcc -mcpu=cortex-m3 -mthumb -O2 -Wall -Wextra \
+    -o uart-communication.elf uart-communication.c
+```
+
+### For Simulation/Testing
+
+```bash
+# Compile for host (for structure/syntax checking only)
+gcc -Wall -Wextra -std=c99 -c gpio-control.c
+gcc -Wall -Wextra -std=c99 -c timer-isr.c
+gcc -Wall -Wextra -std=c99 -c uart-communication.c
+```
+
+## Hardware Requirements
+
+- ARM Cortex-M microcontroller (STM32, NXP, etc.)
+- JTAG/SWD debugger
+- LED and button for GPIO example
+- UART-to-USB adapter for UART example
+
+## Register Addresses
+
+**IMPORTANT:** The register addresses in these examples are for demonstration purposes. You MUST adjust them for your specific microcontroller:
+
+- **STM32F1**: Check STM32F1xx reference manual
+- **STM32F4**: Check STM32F4xx reference manual
+- **NXP LPC**: Check LPC user manual
+- **Nordic nRF**: Check nRF product specification
+
+## Best Practices Demonstrated
+
+1. **Volatile Usage**
+   - All hardware registers marked `volatile`
+   - ISR-shared variables marked `volatile`
+   - Prevents compiler optimization issues
+
+2. **ISR Design**
+   - Minimal execution time
+   - No blocking operations
+   - Clear interrupt flags
+   - Use flags for main loop communication
+
+3. **Memory Safety**
+   - No dynamic allocation
+   - Fixed-size buffers
+   - Bounds checking
+   - Circular buffer overflow protection
+
+4. **Hardware Abstraction**
+   - Clean API separation
+   - Register access encapsulation
+   - Portable code structure
+
+5. **Error Handling**
+   - Check buffer full/empty conditions
+   - Handle UART errors
+   - Validate pin numbers
+
+## Common Pitfalls to Avoid
+
+1. **Forgetting `volatile`**
+   ```c
+   // WRONG
+   uint32_t *reg = (uint32_t *)0x40020000;
+   
+   // CORRECT
+   volatile uint32_t *reg = (volatile uint32_t *)0x40020000;
+   ```
+
+2. **Long ISRs**
+   ```c
+   // WRONG - Too much work in ISR
+   void TIM2_IRQHandler(void) {
+       process_data();  // Long operation
+       send_uart();     // Blocking
+   }
+   
+   // CORRECT - Set flag and defer
+   void TIM2_IRQHandler(void) {
+       data_ready = true;  // Just set flag
+   }
+   ```
+
+3. **Non-atomic Operations**
+   ```c
+   // WRONG - Not atomic on 8-bit MCU
+   volatile uint32_t counter;
+   counter++;  // May be interrupted mid-operation
+   
+   // CORRECT - Disable interrupts or use atomic operations
+   __disable_irq();
+   counter++;
+   __enable_irq();
+   ```
+
+## References
+
+- ARM Cortex-M Programming Guide
+- MISRA C:2012 Guidelines for Embedded Systems
+- Embedded C Coding Standard (Barr Group)
+- Microcontroller vendor reference manuals
+- "Making Embedded Systems" by Elecia White
+

package/augment-extensions/coding-standards/c/examples/embedded/gpio-control.c

@@ -0,0 +1,172 @@
+/**
+ * @file gpio-control.c
+ * @brief Example demonstrating GPIO control for embedded systems
+ * 
+ * This example shows:
+ * - Memory-mapped I/O for hardware registers
+ * - Volatile keyword usage for hardware access
+ * - Bit manipulation for GPIO control
+ * - Hardware abstraction layer pattern
+ * - Safe register access
+ * 
+ * Target: Generic ARM Cortex-M microcontroller
+ * Note: This is a demonstration. Actual addresses depend on your hardware.
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+
+// Example GPIO register addresses (adjust for your hardware)
+#define GPIO_BASE_ADDR      0x40020000UL
+#define GPIOA_MODER         (*(volatile uint32_t *)(GPIO_BASE_ADDR + 0x00))
+#define GPIOA_ODR           (*(volatile uint32_t *)(GPIO_BASE_ADDR + 0x14))
+#define GPIOA_IDR           (*(volatile uint32_t *)(GPIO_BASE_ADDR + 0x10))
+#define GPIOA_BSRR          (*(volatile uint32_t *)(GPIO_BASE_ADDR + 0x18))
+
+// GPIO pin definitions
+#define LED_PIN             5
+#define BUTTON_PIN          13
+
+// GPIO modes
+typedef enum {
+    GPIO_MODE_INPUT  = 0x00,
+    GPIO_MODE_OUTPUT = 0x01,
+    GPIO_MODE_AF     = 0x02,
+    GPIO_MODE_ANALOG = 0x03
+} gpio_mode_t;
+
+// GPIO states
+typedef enum {
+    GPIO_LOW  = 0,
+    GPIO_HIGH = 1
+} gpio_state_t;
+
+/**
+ * @brief Initialize a GPIO pin
+ * @param pin Pin number (0-15)
+ * @param mode GPIO mode
+ */
+void gpio_init(uint8_t pin, gpio_mode_t mode) {
+    if (pin > 15) {
+        return;  // Invalid pin
+    }
+
+    // Clear mode bits for this pin
+    uint32_t temp = GPIOA_MODER;
+    temp &= ~(0x3UL << (pin * 2));
+    
+    // Set new mode
+    temp |= ((uint32_t)mode << (pin * 2));
+    GPIOA_MODER = temp;
+}
+
+/**
+ * @brief Set GPIO pin state
+ * @param pin Pin number (0-15)
+ * @param state Desired state (HIGH/LOW)
+ */
+void gpio_write(uint8_t pin, gpio_state_t state) {
+    if (pin > 15) {
+        return;  // Invalid pin
+    }
+
+    // Use BSRR for atomic bit set/reset
+    if (state == GPIO_HIGH) {
+        GPIOA_BSRR = (1UL << pin);  // Set bit
+    } else {
+        GPIOA_BSRR = (1UL << (pin + 16));  // Reset bit
+    }
+}
+
+/**
+ * @brief Read GPIO pin state
+ * @param pin Pin number (0-15)
+ * @return Current pin state
+ */
+gpio_state_t gpio_read(uint8_t pin) {
+    if (pin > 15) {
+        return GPIO_LOW;  // Invalid pin
+    }
+
+    return (GPIOA_IDR & (1UL << pin)) ? GPIO_HIGH : GPIO_LOW;
+}
+
+/**
+ * @brief Toggle GPIO pin state
+ * @param pin Pin number (0-15)
+ */
+void gpio_toggle(uint8_t pin) {
+    if (pin > 15) {
+        return;  // Invalid pin
+    }
+
+    // Read current state and toggle
+    uint32_t current = GPIOA_ODR;
+    GPIOA_ODR = current ^ (1UL << pin);
+}
+
+/**
+ * @brief Simple delay function (busy-wait)
+ * @param count Delay count (hardware-dependent)
+ * 
+ * Note: In production, use hardware timers instead
+ */
+void delay(volatile uint32_t count) {
+    while (count--) {
+        __asm__ volatile ("nop");  // Prevent optimization
+    }
+}
+
+/**
+ * @brief LED blink example
+ */
+void led_blink_example(void) {
+    // Initialize LED pin as output
+    gpio_init(LED_PIN, GPIO_MODE_OUTPUT);
+
+    // Blink LED 10 times
+    for (int i = 0; i < 10; i++) {
+        gpio_write(LED_PIN, GPIO_HIGH);
+        delay(500000);
+        gpio_write(LED_PIN, GPIO_LOW);
+        delay(500000);
+    }
+}
+
+/**
+ * @brief Button-controlled LED example
+ */
+void button_led_example(void) {
+    // Initialize button pin as input
+    gpio_init(BUTTON_PIN, GPIO_MODE_INPUT);
+    
+    // Initialize LED pin as output
+    gpio_init(LED_PIN, GPIO_MODE_OUTPUT);
+
+    // Read button and control LED
+    for (int i = 0; i < 100; i++) {
+        gpio_state_t button_state = gpio_read(BUTTON_PIN);
+        gpio_write(LED_PIN, button_state);
+        delay(10000);
+    }
+}
+
+/**
+ * @brief Main function
+ */
+int main(void) {
+    // Example 1: LED blink
+    led_blink_example();
+
+    // Example 2: Button-controlled LED
+    button_led_example();
+
+    // Infinite loop (typical for embedded systems)
+    while (1) {
+        gpio_toggle(LED_PIN);
+        delay(1000000);
+    }
+
+    return 0;  // Never reached
+}
+

package/augment-extensions/coding-standards/c/examples/embedded/timer-isr.c

@@ -0,0 +1,198 @@
+/**
+ * @file timer-isr.c
+ * @brief Example demonstrating timer interrupt service routine (ISR)
+ * 
+ * This example shows:
+ * - Timer configuration for periodic interrupts
+ * - Interrupt service routine implementation
+ * - Volatile variables for ISR communication
+ * - Atomic operations
+ * - Minimal ISR execution time
+ * 
+ * Target: Generic ARM Cortex-M microcontroller
+ * Note: This is a demonstration. Actual addresses depend on your hardware.
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+
+// Timer register addresses (example for STM32-like MCU)
+#define TIM2_BASE           0x40000000UL
+#define TIM2_CR1            (*(volatile uint32_t *)(TIM2_BASE + 0x00))
+#define TIM2_DIER           (*(volatile uint32_t *)(TIM2_BASE + 0x0C))
+#define TIM2_SR             (*(volatile uint32_t *)(TIM2_BASE + 0x10))
+#define TIM2_CNT            (*(volatile uint32_t *)(TIM2_BASE + 0x24))
+#define TIM2_PSC            (*(volatile uint32_t *)(TIM2_BASE + 0x28))
+#define TIM2_ARR            (*(volatile uint32_t *)(TIM2_BASE + 0x2C))
+
+// Timer control bits
+#define TIM_CR1_CEN         (1UL << 0)   // Counter enable
+#define TIM_DIER_UIE        (1UL << 0)   // Update interrupt enable
+#define TIM_SR_UIF          (1UL << 0)   // Update interrupt flag
+
+// NVIC (Nested Vectored Interrupt Controller)
+#define NVIC_ISER0          (*(volatile uint32_t *)0xE000E100UL)
+#define TIM2_IRQn           28
+
+// Shared variables between ISR and main (must be volatile)
+static volatile uint32_t tick_count = 0;
+static volatile bool timer_flag = false;
+
+/**
+ * @brief Initialize timer for 1ms periodic interrupts
+ * @param sysclk System clock frequency in Hz
+ */
+void timer_init(uint32_t sysclk) {
+    // Disable timer during configuration
+    TIM2_CR1 &= ~TIM_CR1_CEN;
+
+    // Configure prescaler for 1kHz (1ms) tick
+    // PSC = (sysclk / desired_freq) - 1
+    TIM2_PSC = (sysclk / 1000) - 1;
+
+    // Auto-reload value for 1ms period
+    TIM2_ARR = 1000 - 1;
+
+    // Clear counter
+    TIM2_CNT = 0;
+
+    // Enable update interrupt
+    TIM2_DIER |= TIM_DIER_UIE;
+
+    // Enable TIM2 interrupt in NVIC
+    NVIC_ISER0 |= (1UL << TIM2_IRQn);
+
+    // Start timer
+    TIM2_CR1 |= TIM_CR1_CEN;
+}
+
+/**
+ * @brief Timer interrupt service routine
+ * 
+ * IMPORTANT ISR Rules:
+ * - Keep execution time minimal
+ * - No blocking operations
+ * - No printf/malloc/etc
+ * - Use volatile for shared variables
+ * - Clear interrupt flag
+ */
+void TIM2_IRQHandler(void) {
+    // Check if update interrupt occurred
+    if (TIM2_SR & TIM_SR_UIF) {
+        // Clear interrupt flag (MUST do this!)
+        TIM2_SR &= ~TIM_SR_UIF;
+
+        // Increment tick counter (atomic on 32-bit ARM)
+        tick_count++;
+
+        // Set flag for main loop
+        timer_flag = true;
+
+        // Minimal work in ISR - defer processing to main loop
+    }
+}
+
+/**
+ * @brief Get current tick count (thread-safe)
+ * @return Current tick count
+ */
+uint32_t get_tick_count(void) {
+    // Reading 32-bit value is atomic on ARM Cortex-M
+    return tick_count;
+}
+
+/**
+ * @brief Delay for specified milliseconds
+ * @param ms Milliseconds to delay
+ */
+void delay_ms(uint32_t ms) {
+    uint32_t start = get_tick_count();
+    while ((get_tick_count() - start) < ms) {
+        // Wait
+    }
+}
+
+/**
+ * @brief Check and clear timer flag
+ * @return true if flag was set, false otherwise
+ */
+bool check_timer_flag(void) {
+    if (timer_flag) {
+        timer_flag = false;  // Clear flag
+        return true;
+    }
+    return false;
+}
+
+/**
+ * @brief Example: Periodic task execution
+ */
+void periodic_task_example(void) {
+    uint32_t last_tick = 0;
+    const uint32_t TASK_PERIOD_MS = 100;  // Run every 100ms
+
+    while (1) {
+        uint32_t current_tick = get_tick_count();
+
+        if ((current_tick - last_tick) >= TASK_PERIOD_MS) {
+            last_tick = current_tick;
+
+            // Execute periodic task
+            // (In real code, toggle LED, read sensor, etc.)
+        }
+
+        // Check for timer events
+        if (check_timer_flag()) {
+            // Handle 1ms timer event
+        }
+    }
+}
+
+/**
+ * @brief Example: Timeout detection
+ */
+bool wait_with_timeout(uint32_t timeout_ms) {
+    uint32_t start = get_tick_count();
+
+    while (1) {
+        // Check timeout
+        if ((get_tick_count() - start) >= timeout_ms) {
+            return false;  // Timeout occurred
+        }
+
+        // Check for event (example: button press)
+        // if (event_occurred()) {
+        //     return true;
+        // }
+    }
+}
+
+/**
+ * @brief Main function
+ */
+int main(void) {
+    // Initialize timer (assuming 72MHz system clock)
+    timer_init(72000000);
+
+    // Example 1: Simple delay
+    delay_ms(1000);  // 1 second delay
+
+    // Example 2: Periodic task execution
+    // periodic_task_example();  // Uncomment to run
+
+    // Example 3: Timeout detection
+    bool success = wait_with_timeout(5000);  // 5 second timeout
+
+    // Main loop
+    while (1) {
+        // Process timer events
+        if (check_timer_flag()) {
+            // Handle 1ms tick
+        }
+
+        // Other main loop tasks
+    }
+
+    return 0;  // Never reached
+}
+