@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/c/examples/embedded/uart-communication.c

@@ -0,0 +1,212 @@
+/**
+ * @file uart-communication.c
+ * @brief Example demonstrating UART communication for embedded systems
+ * 
+ * This example shows:
+ * - UART initialization and configuration
+ * - Interrupt-driven UART transmission
+ * - Circular buffer for received data
+ * - Hardware abstraction layer
+ * - Error handling
+ * 
+ * Target: Generic ARM Cortex-M microcontroller
+ * Note: This is a demonstration. Actual addresses depend on your hardware.
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <string.h>
+
+// UART register addresses (example for STM32-like MCU)
+#define USART1_BASE         0x40013800UL
+#define USART1_SR           (*(volatile uint32_t *)(USART1_BASE + 0x00))
+#define USART1_DR           (*(volatile uint32_t *)(USART1_BASE + 0x04))
+#define USART1_BRR          (*(volatile uint32_t *)(USART1_BASE + 0x08))
+#define USART1_CR1          (*(volatile uint32_t *)(USART1_BASE + 0x0C))
+
+// UART status register bits
+#define USART_SR_TXE        (1UL << 7)   // Transmit data register empty
+#define USART_SR_RXNE       (1UL << 5)   // Read data register not empty
+#define USART_SR_ORE        (1UL << 3)   // Overrun error
+#define USART_SR_FE         (1UL << 1)   // Framing error
+
+// UART control register bits
+#define USART_CR1_UE        (1UL << 13)  // USART enable
+#define USART_CR1_TE        (1UL << 3)   // Transmitter enable
+#define USART_CR1_RE        (1UL << 2)   // Receiver enable
+#define USART_CR1_RXNEIE    (1UL << 5)   // RXNE interrupt enable
+
+// Circular buffer for received data
+#define RX_BUFFER_SIZE      256
+
+typedef struct {
+    uint8_t buffer[RX_BUFFER_SIZE];
+    volatile uint16_t head;
+    volatile uint16_t tail;
+} circular_buffer_t;
+
+static circular_buffer_t rx_buffer = {0};
+
+/**
+ * @brief Initialize circular buffer
+ * @param cb Pointer to circular buffer
+ */
+void buffer_init(circular_buffer_t *cb) {
+    cb->head = 0;
+    cb->tail = 0;
+}
+
+/**
+ * @brief Write byte to circular buffer
+ * @param cb Pointer to circular buffer
+ * @param data Byte to write
+ * @return true if successful, false if buffer full
+ */
+bool buffer_write(circular_buffer_t *cb, uint8_t data) {
+    uint16_t next_head = (cb->head + 1) % RX_BUFFER_SIZE;
+    
+    if (next_head == cb->tail) {
+        return false;  // Buffer full
+    }
+    
+    cb->buffer[cb->head] = data;
+    cb->head = next_head;
+    return true;
+}
+
+/**
+ * @brief Read byte from circular buffer
+ * @param cb Pointer to circular buffer
+ * @param data Pointer to store read byte
+ * @return true if successful, false if buffer empty
+ */
+bool buffer_read(circular_buffer_t *cb, uint8_t *data) {
+    if (cb->head == cb->tail) {
+        return false;  // Buffer empty
+    }
+    
+    *data = cb->buffer[cb->tail];
+    cb->tail = (cb->tail + 1) % RX_BUFFER_SIZE;
+    return true;
+}
+
+/**
+ * @brief Get number of bytes available in buffer
+ * @param cb Pointer to circular buffer
+ * @return Number of bytes available
+ */
+uint16_t buffer_available(const circular_buffer_t *cb) {
+    return (cb->head - cb->tail + RX_BUFFER_SIZE) % RX_BUFFER_SIZE;
+}
+
+/**
+ * @brief Initialize UART
+ * @param baudrate Desired baud rate
+ * @param sysclk System clock frequency in Hz
+ */
+void uart_init(uint32_t baudrate, uint32_t sysclk) {
+    // Disable UART during configuration
+    USART1_CR1 &= ~USART_CR1_UE;
+
+    // Configure baud rate
+    // BRR = sysclk / baudrate
+    USART1_BRR = sysclk / baudrate;
+
+    // Enable UART, transmitter, receiver, and RX interrupt
+    USART1_CR1 = USART_CR1_UE | USART_CR1_TE | USART_CR1_RE | USART_CR1_RXNEIE;
+
+    // Initialize RX buffer
+    buffer_init(&rx_buffer);
+}
+
+/**
+ * @brief UART interrupt service routine
+ */
+void USART1_IRQHandler(void) {
+    // Check for receive interrupt
+    if (USART1_SR & USART_SR_RXNE) {
+        uint8_t data = (uint8_t)(USART1_DR & 0xFF);
+        
+        // Store in circular buffer
+        if (!buffer_write(&rx_buffer, data)) {
+            // Buffer overflow - data lost
+        }
+    }
+
+    // Check for errors
+    if (USART1_SR & (USART_SR_ORE | USART_SR_FE)) {
+        // Clear error by reading DR
+        (void)USART1_DR;
+    }
+}
+
+/**
+ * @brief Send single byte via UART
+ * @param data Byte to send
+ */
+void uart_send_byte(uint8_t data) {
+    // Wait for transmit register to be empty
+    while (!(USART1_SR & USART_SR_TXE)) {
+        // Wait
+    }
+    
+    USART1_DR = data;
+}
+
+/**
+ * @brief Send string via UART
+ * @param str Null-terminated string to send
+ */
+void uart_send_string(const char *str) {
+    while (*str) {
+        uart_send_byte((uint8_t)*str++);
+    }
+}
+
+/**
+ * @brief Receive byte from UART (non-blocking)
+ * @param data Pointer to store received byte
+ * @return true if byte received, false if no data available
+ */
+bool uart_receive_byte(uint8_t *data) {
+    return buffer_read(&rx_buffer, data);
+}
+
+/**
+ * @brief Check if data is available
+ * @return Number of bytes available
+ */
+uint16_t uart_available(void) {
+    return buffer_available(&rx_buffer);
+}
+
+/**
+ * @brief Example: Echo received characters
+ */
+void uart_echo_example(void) {
+    uint8_t data;
+    
+    while (1) {
+        if (uart_receive_byte(&data)) {
+            // Echo back received character
+            uart_send_byte(data);
+        }
+    }
+}
+
+/**
+ * @brief Main function
+ */
+int main(void) {
+    // Initialize UART (115200 baud, 72MHz system clock)
+    uart_init(115200, 72000000);
+
+    // Send startup message
+    uart_send_string("UART Example Started\r\n");
+
+    // Run echo example
+    uart_echo_example();
+
+    return 0;  // Never reached
+}
+

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

@@ -0,0 +1,82 @@
+# Makefile for Linux Kernel Modules
+# Kbuild system for building kernel modules
+
+# Module names
+obj-m += simple-module.o
+obj-m += char-device.o
+obj-m += proc-file.o
+
+# Kernel build directory
+KDIR ?= /lib/modules/$(shell uname -r)/build
+
+# Current directory
+PWD := $(shell pwd)
+
+# Default target
+all:
+	$(MAKE) -C $(KDIR) M=$(PWD) modules
+
+# Clean target
+clean:
+	$(MAKE) -C $(KDIR) M=$(PWD) clean
+
+# Install modules (requires root)
+install:
+	$(MAKE) -C $(KDIR) M=$(PWD) modules_install
+
+# Help target
+help:
+	@echo "Kernel Module Makefile"
+	@echo "======================"
+	@echo "Targets:"
+	@echo "  all      - Build all kernel modules (default)"
+	@echo "  clean    - Remove build artifacts"
+	@echo "  install  - Install modules (requires root)"
+	@echo "  load     - Load all modules (requires root)"
+	@echo "  unload   - Unload all modules (requires root)"
+	@echo ""
+	@echo "Individual module targets:"
+	@echo "  load-simple    - Load simple-module"
+	@echo "  load-chardev   - Load char-device"
+	@echo "  load-proc      - Load proc-file"
+
+# Load modules
+load: all
+	sudo insmod simple-module.ko
+	sudo insmod char-device.ko
+	sudo insmod proc-file.ko
+	@echo "Modules loaded. Check with: lsmod | grep -E 'simple|char|proc'"
+
+# Unload modules
+unload:
+	-sudo rmmod proc-file
+	-sudo rmmod char-device
+	-sudo rmmod simple-module
+	@echo "Modules unloaded"
+
+# Individual module load targets
+load-simple: simple-module.ko
+	sudo insmod simple-module.ko
+	@echo "simple-module loaded"
+
+load-chardev: char-device.ko
+	sudo insmod char-device.ko
+	@echo "char-device loaded. Device: /dev/chardev0"
+
+load-proc: proc-file.ko
+	sudo insmod proc-file.ko
+	@echo "proc-file loaded. Interface: /proc/example_proc"
+
+# Test targets
+test-chardev:
+	@echo "Testing character device..."
+	@echo "test data" | sudo tee /dev/chardev0
+	@sudo cat /dev/chardev0
+
+test-proc:
+	@echo "Testing proc file..."
+	@echo "test value" | sudo tee /proc/example_proc
+	@cat /proc/example_proc
+
+.PHONY: all clean install help load unload load-simple load-chardev load-proc test-chardev test-proc
+

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

@@ -0,0 +1,168 @@
+# Linux Kernel Development Examples
+
+This directory contains Linux kernel module examples demonstrating kernel programming best practices.
+
+## Examples
+
+### 1. simple-module.c
+Basic kernel module structure:
+- Module initialization and cleanup
+- Module parameters
+- Kernel logging with printk
+- Module metadata
+- Error handling
+
+**Key Concepts:**
+- Use `module_init()` and `module_exit()`
+- Always check return values
+- Clean up resources in exit function
+- Use appropriate log levels
+
+### 2. char-device.c
+Character device driver:
+- Device registration with cdev
+- File operations (open, read, write, release)
+- Device number allocation
+- User-kernel space data transfer
+- Device class creation
+
+**Key Concepts:**
+- Use `copy_to_user()` and `copy_from_user()`
+- Proper error handling and cleanup
+- Device file creation in /dev
+- Resource management
+
+### 3. proc-file.c
+/proc filesystem interface:
+- Creating /proc entries
+- Sequence file interface
+- Read/write operations
+- Kernel-user communication
+
+**Key Concepts:**
+- Use seq_file for /proc entries
+- Handle user input safely
+- Proper buffer management
+
+## Building
+
+```bash
+# Build all modules
+make
+
+# Build specific module
+make simple-module.ko
+
+# Clean build artifacts
+make clean
+```
+
+## Loading and Testing
+
+```bash
+# Load modules
+sudo insmod simple-module.ko
+sudo insmod simple-module.ko debug_level=2  # With parameter
+sudo insmod char-device.ko
+sudo insmod proc-file.ko
+
+# Check loaded modules
+lsmod | grep -E 'simple|char|proc'
+
+# View kernel logs
+dmesg | tail -20
+
+# Test character device
+echo "test data" | sudo tee /dev/chardev0
+sudo cat /dev/chardev0
+
+# Test proc file
+echo "test value" | sudo tee /proc/example_proc
+cat /proc/example_proc
+
+# Unload modules
+sudo rmmod proc-file
+sudo rmmod char-device
+sudo rmmod simple-module
+```
+
+## Requirements
+
+- Linux kernel headers: `sudo apt-get install linux-headers-$(uname -r)`
+- GCC compiler
+- Make
+- Root privileges for loading/unloading modules
+
+## Best Practices Demonstrated
+
+1. **Error Handling**
+   - Check all allocation results
+   - Clean up on error paths
+   - Return appropriate error codes
+
+2. **Resource Management**
+   - Free all allocated memory
+   - Unregister devices
+   - Remove proc entries
+
+3. **Kernel Coding Style**
+   - Follow Linux kernel coding style
+   - Use kernel API functions
+   - Proper indentation and naming
+
+4. **Safety**
+   - Validate user input
+   - Use safe copy functions
+   - Check buffer boundaries
+
+## Common Pitfalls to Avoid
+
+1. **Memory Leaks**
+   ```c
+   // WRONG - No cleanup on error
+   data = kmalloc(size, GFP_KERNEL);
+   if (register_device() < 0)
+       return -EFAULT;  // Leaked memory!
+   
+   // CORRECT
+   data = kmalloc(size, GFP_KERNEL);
+   if (register_device() < 0) {
+       kfree(data);
+       return -EFAULT;
+   }
+   ```
+
+2. **Direct User Memory Access**
+   ```c
+   // WRONG - Direct access
+   strcpy(kernel_buf, user_buf);  // Unsafe!
+   
+   // CORRECT
+   if (copy_from_user(kernel_buf, user_buf, size))
+       return -EFAULT;
+   ```
+
+3. **Missing Cleanup**
+   ```c
+   // WRONG - Incomplete cleanup
+   static void __exit module_exit(void) {
+       device_destroy(dev);
+       // Forgot to destroy class!
+   }
+   
+   // CORRECT
+   static void __exit module_exit(void) {
+       device_destroy(chardev_class, dev);
+       class_destroy(chardev_class);
+       cdev_del(&chardev_cdev);
+       unregister_chrdev_region(dev, 1);
+   }
+   ```
+
+## References
+
+- Linux Kernel Documentation: https://www.kernel.org/doc/html/latest/
+- Linux Device Drivers (LDD3)
+- Linux Kernel Development by Robert Love
+- Kernel coding style: Documentation/process/coding-style.rst
+

package/augment-extensions/coding-standards/c/examples/kernel/char-device.c

@@ -0,0 +1,198 @@
+/**
+ * @file char-device.c
+ * @brief Example Linux kernel character device driver
+ * 
+ * This example demonstrates:
+ * - Character device registration
+ * - File operations (open, read, write, release)
+ * - Device number allocation
+ * - Module initialization and cleanup
+ * - Kernel memory allocation
+ * 
+ * Build: make
+ * Load: sudo insmod char-device.ko
+ * Test: echo "test" > /dev/chardev0
+ *       cat /dev/chardev0
+ * Unload: sudo rmmod char-device
+ */
+
+#include <linux/module.h>
+#include <linux/kernel.h>
+#include <linux/fs.h>
+#include <linux/cdev.h>
+#include <linux/device.h>
+#include <linux/slab.h>
+#include <linux/uaccess.h>
+
+#define DEVICE_NAME "chardev"
+#define CLASS_NAME  "chardev_class"
+#define BUFFER_SIZE 1024
+
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("Example Author");
+MODULE_DESCRIPTION("Simple character device driver");
+MODULE_VERSION("1.0");
+
+static int major_number;
+static struct class *chardev_class = NULL;
+static struct device *chardev_device = NULL;
+static struct cdev chardev_cdev;
+
+// Device buffer
+static char *device_buffer = NULL;
+static size_t buffer_size = 0;
+
+/**
+ * @brief Device open function
+ */
+static int chardev_open(struct inode *inode, struct file *file) {
+    pr_info("chardev: Device opened\n");
+    return 0;
+}
+
+/**
+ * @brief Device release function
+ */
+static int chardev_release(struct inode *inode, struct file *file) {
+    pr_info("chardev: Device closed\n");
+    return 0;
+}
+
+/**
+ * @brief Device read function
+ */
+static ssize_t chardev_read(struct file *file, char __user *user_buffer,
+                            size_t count, loff_t *offset) {
+    size_t to_read;
+    
+    if (*offset >= buffer_size) {
+        return 0;  // EOF
+    }
+    
+    to_read = min(count, buffer_size - (size_t)*offset);
+    
+    if (copy_to_user(user_buffer, device_buffer + *offset, to_read)) {
+        return -EFAULT;
+    }
+    
+    *offset += to_read;
+    pr_info("chardev: Read %zu bytes\n", to_read);
+    
+    return to_read;
+}
+
+/**
+ * @brief Device write function
+ */
+static ssize_t chardev_write(struct file *file, const char __user *user_buffer,
+                             size_t count, loff_t *offset) {
+    size_t to_write;
+    
+    if (count > BUFFER_SIZE) {
+        return -EINVAL;
+    }
+    
+    to_write = min(count, (size_t)BUFFER_SIZE);
+    
+    if (copy_from_user(device_buffer, user_buffer, to_write)) {
+        return -EFAULT;
+    }
+    
+    buffer_size = to_write;
+    pr_info("chardev: Wrote %zu bytes\n", to_write);
+    
+    return to_write;
+}
+
+// File operations structure
+static struct file_operations fops = {
+    .owner = THIS_MODULE,
+    .open = chardev_open,
+    .release = chardev_release,
+    .read = chardev_read,
+    .write = chardev_write,
+};
+
+/**
+ * @brief Module initialization
+ */
+static int __init chardev_init(void) {
+    dev_t dev;
+    int ret;
+    
+    pr_info("chardev: Initializing module\n");
+    
+    // Allocate device buffer
+    device_buffer = kmalloc(BUFFER_SIZE, GFP_KERNEL);
+    if (!device_buffer) {
+        pr_err("chardev: Failed to allocate buffer\n");
+        return -ENOMEM;
+    }
+    
+    // Allocate device number
+    ret = alloc_chrdev_region(&dev, 0, 1, DEVICE_NAME);
+    if (ret < 0) {
+        pr_err("chardev: Failed to allocate device number\n");
+        goto fail_alloc;
+    }
+    major_number = MAJOR(dev);
+    
+    // Initialize cdev
+    cdev_init(&chardev_cdev, &fops);
+    chardev_cdev.owner = THIS_MODULE;
+    
+    // Add cdev
+    ret = cdev_add(&chardev_cdev, dev, 1);
+    if (ret < 0) {
+        pr_err("chardev: Failed to add cdev\n");
+        goto fail_cdev;
+    }
+    
+    // Create device class
+    chardev_class = class_create(THIS_MODULE, CLASS_NAME);
+    if (IS_ERR(chardev_class)) {
+        pr_err("chardev: Failed to create class\n");
+        ret = PTR_ERR(chardev_class);
+        goto fail_class;
+    }
+    
+    // Create device
+    chardev_device = device_create(chardev_class, NULL, dev, NULL, DEVICE_NAME "0");
+    if (IS_ERR(chardev_device)) {
+        pr_err("chardev: Failed to create device\n");
+        ret = PTR_ERR(chardev_device);
+        goto fail_device;
+    }
+    
+    pr_info("chardev: Module loaded successfully\n");
+    return 0;
+    
+fail_device:
+    class_destroy(chardev_class);
+fail_class:
+    cdev_del(&chardev_cdev);
+fail_cdev:
+    unregister_chrdev_region(dev, 1);
+fail_alloc:
+    kfree(device_buffer);
+    return ret;
+}
+
+/**
+ * @brief Module cleanup
+ */
+static void __exit chardev_exit(void) {
+    dev_t dev = MKDEV(major_number, 0);
+    
+    device_destroy(chardev_class, dev);
+    class_destroy(chardev_class);
+    cdev_del(&chardev_cdev);
+    unregister_chrdev_region(dev, 1);
+    kfree(device_buffer);
+    
+    pr_info("chardev: Module unloaded\n");
+}
+
+module_init(chardev_init);
+module_exit(chardev_exit);
+