@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/c/examples/realtime/deadline-monitoring.c

@@ -0,0 +1,260 @@
+/**
+ * @file deadline-monitoring.c
+ * @brief Example demonstrating deadline monitoring for real-time tasks
+ * 
+ * This example shows:
+ * - Deadline-driven scheduling
+ * - Execution time monitoring
+ * - Deadline miss detection
+ * - Worst-case execution time (WCET) tracking
+ * - Task timing statistics
+ * 
+ * Compatible with: FreeRTOS, Zephyr RTOS, or POSIX real-time
+ * Build: See README.md for RTOS-specific instructions
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+
+#ifdef USE_FREERTOS
+#include "FreeRTOS.h"
+#include "task.h"
+#include "timers.h"
+#endif
+
+/* Task timing constraints */
+#define TASK_PERIOD_MS          100
+#define TASK_DEADLINE_MS        80
+#define TASK_WCET_MS            50
+
+/* Statistics tracking */
+typedef struct {
+    uint32_t executions;
+    uint32_t deadline_misses;
+    uint32_t min_execution_time_us;
+    uint32_t max_execution_time_us;
+    uint32_t total_execution_time_us;
+} task_stats_t;
+
+static task_stats_t task_stats = {0};
+
+/**
+ * @brief Get current time in microseconds
+ * @return Current time in microseconds
+ */
+static inline uint32_t get_time_us(void)
+{
+#ifdef USE_FREERTOS
+    return (uint32_t)(xTaskGetTickCount() * 1000 / configTICK_RATE_HZ);
+#else
+    /* Platform-specific implementation */
+    return 0;  /* Placeholder */
+#endif
+}
+
+/**
+ * @brief Initialize task statistics
+ */
+static void init_task_stats(task_stats_t *stats)
+{
+    memset(stats, 0, sizeof(task_stats_t));
+    stats->min_execution_time_us = UINT32_MAX;
+}
+
+/**
+ * @brief Update task statistics
+ * @param stats Statistics structure
+ * @param execution_time_us Execution time in microseconds
+ * @param deadline_met Whether deadline was met
+ */
+static void update_task_stats(task_stats_t *stats,
+                              uint32_t execution_time_us,
+                              bool deadline_met)
+{
+    stats->executions++;
+    stats->total_execution_time_us += execution_time_us;
+    
+    if (execution_time_us < stats->min_execution_time_us) {
+        stats->min_execution_time_us = execution_time_us;
+    }
+    
+    if (execution_time_us > stats->max_execution_time_us) {
+        stats->max_execution_time_us = execution_time_us;
+    }
+    
+    if (!deadline_met) {
+        stats->deadline_misses++;
+    }
+}
+
+/**
+ * @brief Print task statistics
+ */
+static void print_task_stats(const task_stats_t *stats)
+{
+    if (stats->executions == 0) {
+        printf("No executions yet\n");
+        return;
+    }
+    
+    uint32_t avg_time = stats->total_execution_time_us / stats->executions;
+    float miss_rate = (float)stats->deadline_misses / stats->executions * 100.0f;
+    
+    printf("\n=== Task Statistics ===\n");
+    printf("Executions:      %u\n", (unsigned int)stats->executions);
+    printf("Deadline misses: %u (%.2f%%)\n", 
+           (unsigned int)stats->deadline_misses, miss_rate);
+    printf("Min exec time:   %u us\n", (unsigned int)stats->min_execution_time_us);
+    printf("Max exec time:   %u us\n", (unsigned int)stats->max_execution_time_us);
+    printf("Avg exec time:   %u us\n", (unsigned int)avg_time);
+    printf("======================\n\n");
+}
+
+/**
+ * @brief Simulate task workload
+ * @param workload_us Workload duration in microseconds
+ */
+static void simulate_workload(uint32_t workload_us)
+{
+    uint32_t start = get_time_us();
+    
+    /* Busy-wait to simulate work */
+    while ((get_time_us() - start) < workload_us) {
+        /* Simulate computation */
+        volatile uint32_t dummy = 0;
+        for (int i = 0; i < 100; i++) {
+            dummy += i;
+        }
+    }
+}
+
+/**
+ * @brief Deadline-monitored task
+ * 
+ * This task monitors its own execution time and detects deadline misses
+ */
+void deadline_monitored_task(void *params)
+{
+    TickType_t last_wake_time;
+    const TickType_t period = pdMS_TO_TICKS(TASK_PERIOD_MS);
+    const uint32_t deadline_us = TASK_DEADLINE_MS * 1000;
+    uint32_t iteration = 0;
+    
+    (void)params;
+    
+    init_task_stats(&task_stats);
+    last_wake_time = xTaskGetTickCount();
+    
+    printf("Deadline-monitored task started\n");
+    printf("Period: %u ms, Deadline: %u ms\n", 
+           TASK_PERIOD_MS, TASK_DEADLINE_MS);
+    
+    while (1) {
+        /* Wait for next period */
+        vTaskDelayUntil(&last_wake_time, period);
+        
+        /* Record start time */
+        uint32_t start_time = get_time_us();
+        TickType_t release_time = xTaskGetTickCount();
+        
+        /* Perform task work */
+        /* Vary workload to demonstrate deadline monitoring */
+        uint32_t workload_us;
+        if (iteration % 10 == 0) {
+            /* Occasionally exceed deadline to demonstrate detection */
+            workload_us = (TASK_DEADLINE_MS + 10) * 1000;
+        } else {
+            /* Normal workload within deadline */
+            workload_us = (TASK_WCET_MS - 10) * 1000;
+        }
+        
+        simulate_workload(workload_us);
+        
+        /* Record end time */
+        uint32_t end_time = get_time_us();
+        uint32_t execution_time_us = end_time - start_time;
+        
+        /* Check deadline */
+        bool deadline_met = (execution_time_us <= deadline_us);
+        
+        /* Update statistics */
+        update_task_stats(&task_stats, execution_time_us, deadline_met);
+        
+        /* Log deadline miss */
+        if (!deadline_met) {
+            printf("DEADLINE MISS! Iteration %u: %u us (deadline: %u us)\n",
+                   (unsigned int)iteration,
+                   (unsigned int)execution_time_us,
+                   (unsigned int)deadline_us);
+        }
+        
+        /* Print statistics every 20 iterations */
+        if (iteration % 20 == 0 && iteration > 0) {
+            print_task_stats(&task_stats);
+        }
+        
+        iteration++;
+    }
+}
+
+/**
+ * @brief Watchdog timer callback for deadline enforcement
+ * 
+ * This timer fires at the deadline to detect if task is still running
+ */
+void deadline_watchdog_callback(TimerHandle_t timer)
+{
+    (void)timer;
+    
+    /* In a real system, this would check if the task completed */
+    /* and take corrective action if deadline was missed */
+    printf("Watchdog: Checking deadline compliance\n");
+}
+
+/**
+ * @brief Initialize deadline monitoring system
+ */
+int main(void)
+{
+    BaseType_t ret;
+    TimerHandle_t watchdog_timer;
+    
+    printf("Starting Deadline Monitoring Example\n");
+    
+    /* Create deadline watchdog timer */
+    watchdog_timer = xTimerCreate("DeadlineWatchdog",
+                                  pdMS_TO_TICKS(TASK_DEADLINE_MS),
+                                  pdTRUE,  /* Auto-reload */
+                                  NULL,
+                                  deadline_watchdog_callback);
+    if (watchdog_timer == NULL) {
+        printf("Failed to create watchdog timer\n");
+        return -1;
+    }
+    
+    /* Create deadline-monitored task */
+    ret = xTaskCreate(deadline_monitored_task,
+                     "DeadlineTask",
+                     512,
+                     NULL,
+                     2,  /* Medium priority */
+                     NULL);
+    if (ret != pdPASS) {
+        printf("Failed to create deadline-monitored task\n");
+        return -1;
+    }
+    
+    /* Start watchdog timer */
+    xTimerStart(watchdog_timer, 0);
+    
+    /* Start scheduler */
+    printf("Starting RTOS scheduler\n");
+    vTaskStartScheduler();
+    
+    /* Should never reach here */
+    printf("Scheduler failed to start\n");
+    return -1;
+}
+

package/augment-extensions/coding-standards/c/examples/realtime/priority-scheduling.c

@@ -0,0 +1,258 @@
+/**
+ * @file priority-scheduling.c
+ * @brief Example demonstrating priority-based task scheduling for RTOS
+ * 
+ * This example shows:
+ * - Task creation with different priorities
+ * - Priority-based preemption
+ * - Task synchronization
+ * - Resource sharing with priority inheritance
+ * - Deadline monitoring
+ * 
+ * Compatible with: FreeRTOS, Zephyr RTOS, or similar
+ * Build: Depends on RTOS (see README.md)
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stdio.h>
+
+/* RTOS-specific includes (example for FreeRTOS) */
+#ifdef USE_FREERTOS
+#include "FreeRTOS.h"
+#include "task.h"
+#include "semphr.h"
+#include "queue.h"
+#endif
+
+/* Task priorities (higher number = higher priority) */
+#define PRIORITY_HIGH       3
+#define PRIORITY_MEDIUM     2
+#define PRIORITY_LOW        1
+
+/* Task periods (in milliseconds) */
+#define PERIOD_HIGH_MS      10
+#define PERIOD_MEDIUM_MS    50
+#define PERIOD_LOW_MS       100
+
+/* Stack sizes */
+#define STACK_SIZE          256
+
+/* Shared resource protection */
+static SemaphoreHandle_t resource_mutex = NULL;
+static uint32_t shared_counter = 0;
+
+/**
+ * @brief High-priority periodic task
+ * 
+ * Runs every 10ms - Critical real-time task
+ */
+void high_priority_task(void *params)
+{
+    TickType_t last_wake_time;
+    const TickType_t period = pdMS_TO_TICKS(PERIOD_HIGH_MS);
+    
+    (void)params;  /* Unused */
+    
+    /* Initialize last wake time */
+    last_wake_time = xTaskGetTickCount();
+    
+    while (1) {
+        /* Wait for next period */
+        vTaskDelayUntil(&last_wake_time, period);
+        
+        /* Critical real-time work */
+        /* Example: Read sensor, update control output */
+        
+        /* Access shared resource with mutex */
+        if (xSemaphoreTake(resource_mutex, pdMS_TO_TICKS(5)) == pdTRUE) {
+            shared_counter++;
+            xSemaphoreGive(resource_mutex);
+        } else {
+            /* Mutex timeout - log error */
+            printf("High priority task: Mutex timeout!\n");
+        }
+        
+        /* Simulate work (replace with actual task) */
+        vTaskDelay(pdMS_TO_TICKS(2));
+    }
+}
+
+/**
+ * @brief Medium-priority periodic task
+ * 
+ * Runs every 50ms - Important but not critical
+ */
+void medium_priority_task(void *params)
+{
+    TickType_t last_wake_time;
+    const TickType_t period = pdMS_TO_TICKS(PERIOD_MEDIUM_MS);
+    
+    (void)params;
+    
+    last_wake_time = xTaskGetTickCount();
+    
+    while (1) {
+        vTaskDelayUntil(&last_wake_time, period);
+        
+        /* Medium priority work */
+        /* Example: Process data, update display */
+        
+        if (xSemaphoreTake(resource_mutex, pdMS_TO_TICKS(10)) == pdTRUE) {
+            /* Read shared resource */
+            uint32_t value = shared_counter;
+            xSemaphoreGive(resource_mutex);
+            
+            printf("Medium task: Counter = %u\n", (unsigned int)value);
+        }
+        
+        vTaskDelay(pdMS_TO_TICKS(5));
+    }
+}
+
+/**
+ * @brief Low-priority periodic task
+ * 
+ * Runs every 100ms - Background processing
+ */
+void low_priority_task(void *params)
+{
+    TickType_t last_wake_time;
+    const TickType_t period = pdMS_TO_TICKS(PERIOD_LOW_MS);
+    
+    (void)params;
+    
+    last_wake_time = xTaskGetTickCount();
+    
+    while (1) {
+        vTaskDelayUntil(&last_wake_time, period);
+        
+        /* Low priority work */
+        /* Example: Logging, housekeeping, diagnostics */
+        
+        if (xSemaphoreTake(resource_mutex, pdMS_TO_TICKS(20)) == pdTRUE) {
+            uint32_t value = shared_counter;
+            xSemaphoreGive(resource_mutex);
+            
+            printf("Low task: Counter = %u\n", (unsigned int)value);
+        }
+        
+        vTaskDelay(pdMS_TO_TICKS(10));
+    }
+}
+
+/**
+ * @brief Aperiodic event handler task
+ * 
+ * Responds to events with high priority
+ */
+void event_handler_task(void *params)
+{
+    QueueHandle_t event_queue = (QueueHandle_t)params;
+    uint32_t event_data;
+    
+    while (1) {
+        /* Wait for event (blocking) */
+        if (xQueueReceive(event_queue, &event_data, portMAX_DELAY) == pdTRUE) {
+            /* Handle event immediately */
+            printf("Event handler: Received event %u\n", (unsigned int)event_data);
+            
+            /* Process event with deadline constraint */
+            /* Must complete within 5ms */
+            TickType_t start_time = xTaskGetTickCount();
+            
+            /* Event processing */
+            vTaskDelay(pdMS_TO_TICKS(3));
+            
+            TickType_t end_time = xTaskGetTickCount();
+            TickType_t elapsed = end_time - start_time;
+            
+            if (elapsed > pdMS_TO_TICKS(5)) {
+                printf("Event handler: Deadline missed! (%u ms)\n",
+                       (unsigned int)(elapsed * portTICK_PERIOD_MS));
+            }
+        }
+    }
+}
+
+/**
+ * @brief Initialize and start real-time tasks
+ */
+int main(void)
+{
+    BaseType_t ret;
+    QueueHandle_t event_queue;
+    
+    printf("Starting Real-Time Priority Scheduling Example\n");
+    
+    /* Create mutex with priority inheritance */
+    resource_mutex = xSemaphoreCreateMutex();
+    if (resource_mutex == NULL) {
+        printf("Failed to create mutex\n");
+        return -1;
+    }
+    
+    /* Create event queue */
+    event_queue = xQueueCreate(10, sizeof(uint32_t));
+    if (event_queue == NULL) {
+        printf("Failed to create event queue\n");
+        return -1;
+    }
+    
+    /* Create high-priority task */
+    ret = xTaskCreate(high_priority_task,
+                     "HighPrio",
+                     STACK_SIZE,
+                     NULL,
+                     PRIORITY_HIGH,
+                     NULL);
+    if (ret != pdPASS) {
+        printf("Failed to create high priority task\n");
+        return -1;
+    }
+    
+    /* Create medium-priority task */
+    ret = xTaskCreate(medium_priority_task,
+                     "MediumPrio",
+                     STACK_SIZE,
+                     NULL,
+                     PRIORITY_MEDIUM,
+                     NULL);
+    if (ret != pdPASS) {
+        printf("Failed to create medium priority task\n");
+        return -1;
+    }
+    
+    /* Create low-priority task */
+    ret = xTaskCreate(low_priority_task,
+                     "LowPrio",
+                     STACK_SIZE,
+                     NULL,
+                     PRIORITY_LOW,
+                     NULL);
+    if (ret != pdPASS) {
+        printf("Failed to create low priority task\n");
+        return -1;
+    }
+    
+    /* Create event handler task */
+    ret = xTaskCreate(event_handler_task,
+                     "EventHandler",
+                     STACK_SIZE,
+                     (void *)event_queue,
+                     PRIORITY_HIGH,
+                     NULL);
+    if (ret != pdPASS) {
+        printf("Failed to create event handler task\n");
+        return -1;
+    }
+    
+    /* Start scheduler */
+    printf("Starting RTOS scheduler\n");
+    vTaskStartScheduler();
+    
+    /* Should never reach here */
+    printf("Scheduler failed to start\n");
+    return -1;
+}
+

package/augment-extensions/coding-standards/c/examples/systems/Makefile

@@ -0,0 +1,34 @@
+# Makefile for Systems Programming Examples
+# Demonstrates POSIX-compliant build process
+
+CC = gcc
+CFLAGS = -Wall -Wextra -Werror -std=c11 -pedantic -O2
+LDFLAGS =
+TARGETS = process-management ipc-pipes signal-handling
+
+.PHONY: all clean test
+
+all: $(TARGETS)
+
+process-management: process-management.c
+	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
+
+ipc-pipes: ipc-pipes.c
+	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
+
+signal-handling: signal-handling.c
+	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
+
+clean:
+	rm -f $(TARGETS) *.o
+
+test: all
+	@echo "Running process-management..."
+	./process-management
+	@echo ""
+	@echo "Running ipc-pipes..."
+	./ipc-pipes
+	@echo ""
+	@echo "Note: signal-handling requires manual testing (Ctrl+C, kill signals)"
+	@echo "Run: ./signal-handling"
+

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

@@ -0,0 +1,123 @@
+# Systems Programming Examples
+
+This directory contains compilable C examples demonstrating POSIX systems programming best practices.
+
+## Examples
+
+### 1. process-management.c
+Demonstrates process creation and management:
+- `fork()` and `exec()` family functions
+- Parent-child process coordination
+- Process exit status handling
+- Multiple child process management
+- Resource cleanup
+
+**Key Concepts:**
+- Always check `fork()` return value
+- Use `waitpid()` to collect child status
+- Handle both normal exit and signal termination
+- Clean up resources on error paths
+
+### 2. ipc-pipes.c
+Demonstrates inter-process communication using pipes:
+- Creating pipes with `pipe()`
+- Unidirectional communication
+- Bidirectional communication with two pipes
+- Proper file descriptor management
+- Error handling
+
+**Key Concepts:**
+- Close unused pipe ends
+- Handle partial reads/writes
+- Check all system call return values
+- Clean up file descriptors
+
+### 3. signal-handling.c
+Demonstrates POSIX signal handling:
+- Installing signal handlers with `sigaction()`
+- Handling SIGINT, SIGTERM, SIGUSR1
+- Async-signal-safe operations
+- Signal masking with `sigprocmask()`
+- Graceful shutdown
+
+**Key Concepts:**
+- Use `sigaction()` instead of `signal()`
+- Only use async-signal-safe functions in handlers
+- Use `volatile sig_atomic_t` for shared flags
+- Implement graceful shutdown
+
+## Building
+
+```bash
+# Build all examples
+make
+
+# Build specific example
+make process-management
+
+# Clean build artifacts
+make clean
+
+# Run automated tests
+make test
+```
+
+## Running
+
+```bash
+# Process management
+./process-management
+
+# IPC pipes
+./ipc-pipes
+
+# Signal handling (interactive)
+./signal-handling
+# In another terminal:
+kill -USR1 <pid>
+kill -TERM <pid>
+```
+
+## Requirements
+
+- POSIX-compliant system (Linux, Unix, macOS, BSD)
+- GCC or compatible C compiler
+- C11 standard support
+
+## Standards Compliance
+
+All examples follow:
+- POSIX.1-2017 (IEEE Std 1003.1-2017)
+- C11 standard (ISO/IEC 9899:2011)
+- Linux/GNU coding standards
+
+## Best Practices Demonstrated
+
+1. **Error Handling**
+   - Check all system call return values
+   - Use `perror()` for error messages
+   - Clean up resources on error paths
+
+2. **Resource Management**
+   - Close file descriptors when done
+   - Free allocated memory
+   - Wait for child processes
+
+3. **Signal Safety**
+   - Use async-signal-safe functions only
+   - Minimize work in signal handlers
+   - Use `volatile sig_atomic_t` for flags
+
+4. **Code Quality**
+   - Compile with `-Wall -Wextra -Werror`
+   - Use meaningful variable names
+   - Add comprehensive comments
+   - Follow consistent style
+
+## References
+
+- POSIX.1-2017: https://pubs.opengroup.org/onlinepubs/9699919799/
+- Advanced Programming in the UNIX Environment (APUE)
+- The Linux Programming Interface (TLPI)
+- GNU C Library Manual: https://www.gnu.org/software/libc/manual/
+