@mytechtoday/augment-extensions 1.4.0 → 1.5.0

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

@@ -0,0 +1,192 @@
+# Device Drivers Examples
+
+This directory contains Linux device driver examples demonstrating advanced driver development.
+
+## Examples
+
+### 1. platform-driver.c
+Platform device driver with device tree support:
+- Platform driver registration
+- Device tree binding and parsing
+- Resource management with devm_* functions
+- Probe and remove functions
+- Memory-mapped I/O
+
+**Key Concepts:**
+- Use `devm_*` functions for automatic cleanup
+- Parse device tree properties
+- Handle resources (memory, IRQ)
+- Proper error handling in probe
+
+### 2. dma-example.c
+DMA (Direct Memory Access) usage:
+- Coherent DMA allocation
+- Streaming DMA mapping
+- DMA direction handling
+- DMA mask configuration
+- Proper cleanup
+
+**Key Concepts:**
+- Choose coherent vs streaming DMA appropriately
+- Always check `dma_mapping_error()`
+- Unmap before freeing buffers
+- Set appropriate DMA mask
+
+### 3. example.dts
+Device tree source file:
+- Device node definitions
+- Register address mapping
+- Interrupt configuration
+- DMA bindings
+- Custom properties
+
+## Building
+
+```bash
+# Build all drivers
+make
+
+# Build device tree blob
+make dtb
+
+# Clean
+make clean
+```
+
+## Device Tree
+
+### Compiling Device Tree
+
+```bash
+# Compile DTS to DTB
+dtc -I dts -O dtb -o example.dtb example.dts
+
+# Decompile DTB to DTS
+dtc -I dtb -O dts -o example.dts example.dtb
+```
+
+### Device Tree Properties
+
+```dts
+example_device@40000000 {
+    compatible = "example,platform-device";  /* Driver matching */
+    reg = <0x40000000 0x1000>;              /* Base addr, size */
+    interrupts = <0 32 4>;                   /* IRQ configuration */
+    status = "okay";                         /* Enable device */
+};
+```
+
+## Loading and Testing
+
+```bash
+# Load drivers
+sudo insmod platform-driver.ko
+sudo insmod dma-example.ko
+
+# Check kernel logs
+dmesg | tail -30
+
+# List loaded modules
+lsmod | grep -E 'platform|dma'
+
+# Unload drivers
+sudo rmmod dma-example
+sudo rmmod platform-driver
+```
+
+## DMA Usage Guidelines
+
+### Coherent DMA
+Use for buffers accessed simultaneously by CPU and device:
+```c
+void *buf = dma_alloc_coherent(dev, size, &dma_handle, GFP_KERNEL);
+/* Use buffer */
+dma_free_coherent(dev, size, buf, dma_handle);
+```
+
+### Streaming DMA
+Use for one-directional transfers:
+```c
+void *buf = kmalloc(size, GFP_KERNEL);
+dma_addr_t dma_handle = dma_map_single(dev, buf, size, DMA_TO_DEVICE);
+if (dma_mapping_error(dev, dma_handle)) { /* error */ }
+/* Transfer data */
+dma_unmap_single(dev, dma_handle, size, DMA_TO_DEVICE);
+kfree(buf);
+```
+
+### DMA Directions
+- `DMA_TO_DEVICE`: CPU writes, device reads
+- `DMA_FROM_DEVICE`: Device writes, CPU reads
+- `DMA_BIDIRECTIONAL`: Both directions
+
+## Best Practices
+
+1. **Resource Management**
+   - Use `devm_*` functions when possible
+   - Clean up in reverse order of allocation
+   - Handle all error paths
+
+2. **DMA Safety**
+   - Always check `dma_mapping_error()`
+   - Set appropriate DMA mask
+   - Unmap before freeing
+   - Use correct DMA direction
+
+3. **Device Tree**
+   - Use standard property names
+   - Document custom properties
+   - Validate in driver code
+
+4. **Error Handling**
+   - Return appropriate error codes
+   - Log errors with `dev_err()`
+   - Clean up on failure
+
+## Common Pitfalls
+
+1. **Missing DMA Unmap**
+   ```c
+   // WRONG
+   dma_addr = dma_map_single(dev, buf, size, DMA_TO_DEVICE);
+   kfree(buf);  // Forgot to unmap!
+   
+   // CORRECT
+   dma_addr = dma_map_single(dev, buf, size, DMA_TO_DEVICE);
+   dma_unmap_single(dev, dma_addr, size, DMA_TO_DEVICE);
+   kfree(buf);
+   ```
+
+2. **Wrong DMA Direction**
+   ```c
+   // WRONG - Device writes to buffer
+   dma_map_single(dev, buf, size, DMA_TO_DEVICE);
+   
+   // CORRECT
+   dma_map_single(dev, buf, size, DMA_FROM_DEVICE);
+   ```
+
+3. **Incomplete Cleanup**
+   ```c
+   // WRONG
+   static int probe(struct platform_device *pdev) {
+       base = devm_ioremap_resource(&pdev->dev, res);
+       data = kmalloc(size, GFP_KERNEL);  // Not devm!
+       return 0;  // Memory leak on driver removal
+   }
+   
+   // CORRECT
+   static int probe(struct platform_device *pdev) {
+       base = devm_ioremap_resource(&pdev->dev, res);
+       data = devm_kmalloc(&pdev->dev, size, GFP_KERNEL);
+       return 0;  // Auto-freed on removal
+   }
+   ```
+
+## References
+
+- Linux Device Drivers (LDD3)
+- Linux Kernel DMA API: Documentation/core-api/dma-api.rst
+- Device Tree Specification: https://www.devicetree.org/
+- Platform Devices: Documentation/driver-api/driver-model/platform.rst
+

package/augment-extensions/coding-standards/c/examples/drivers/dma-example.c

@@ -0,0 +1,224 @@
+/**
+ * @file dma-example.c
+ * @brief Example DMA (Direct Memory Access) usage in Linux kernel
+ * 
+ * This example demonstrates:
+ * - DMA buffer allocation
+ * - DMA mapping and unmapping
+ * - Coherent vs streaming DMA
+ * - DMA direction handling
+ * - Proper cleanup
+ * 
+ * Build: make
+ * Load: sudo insmod dma-example.ko
+ */
+
+#include <linux/module.h>
+#include <linux/kernel.h>
+#include <linux/platform_device.h>
+#include <linux/dma-mapping.h>
+#include <linux/slab.h>
+
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("Example Author");
+MODULE_DESCRIPTION("Example DMA usage driver");
+MODULE_VERSION("1.0");
+
+#define DMA_BUFFER_SIZE 4096
+
+/**
+ * @brief Device private data
+ */
+struct dma_device {
+    struct device *dev;
+    
+    /* Coherent DMA buffer */
+    void *coherent_buffer;
+    dma_addr_t coherent_dma_handle;
+    
+    /* Streaming DMA buffer */
+    void *streaming_buffer;
+    dma_addr_t streaming_dma_handle;
+};
+
+/**
+ * @brief Example: Allocate and use coherent DMA buffer
+ * 
+ * Coherent DMA is used for buffers shared between CPU and device
+ * that need to be accessed simultaneously.
+ */
+static int coherent_dma_example(struct dma_device *dma_dev)
+{
+    dev_info(dma_dev->dev, "Allocating coherent DMA buffer\n");
+
+    /* Allocate coherent DMA buffer */
+    dma_dev->coherent_buffer = dma_alloc_coherent(dma_dev->dev,
+                                                   DMA_BUFFER_SIZE,
+                                                   &dma_dev->coherent_dma_handle,
+                                                   GFP_KERNEL);
+    if (!dma_dev->coherent_buffer) {
+        dev_err(dma_dev->dev, "Failed to allocate coherent DMA buffer\n");
+        return -ENOMEM;
+    }
+
+    dev_info(dma_dev->dev, "Coherent DMA buffer allocated\n");
+    dev_info(dma_dev->dev, "Virtual address: %p\n", dma_dev->coherent_buffer);
+    dev_info(dma_dev->dev, "DMA address: 0x%llx\n", 
+             (unsigned long long)dma_dev->coherent_dma_handle);
+
+    /* Use the buffer - CPU can write directly */
+    memset(dma_dev->coherent_buffer, 0xAA, DMA_BUFFER_SIZE);
+
+    /* Program device with DMA address */
+    /* Example: writel(dma_dev->coherent_dma_handle, device_dma_addr_reg); */
+
+    return 0;
+}
+
+/**
+ * @brief Example: Allocate and use streaming DMA buffer
+ * 
+ * Streaming DMA is used for one-directional transfers where
+ * CPU and device don't access the buffer simultaneously.
+ */
+static int streaming_dma_example(struct dma_device *dma_dev)
+{
+    dev_info(dma_dev->dev, "Setting up streaming DMA\n");
+
+    /* Allocate regular kernel memory */
+    dma_dev->streaming_buffer = kmalloc(DMA_BUFFER_SIZE, GFP_KERNEL);
+    if (!dma_dev->streaming_buffer) {
+        dev_err(dma_dev->dev, "Failed to allocate streaming buffer\n");
+        return -ENOMEM;
+    }
+
+    /* Fill buffer with data */
+    memset(dma_dev->streaming_buffer, 0x55, DMA_BUFFER_SIZE);
+
+    /* Map buffer for DMA (device will read from it) */
+    dma_dev->streaming_dma_handle = dma_map_single(dma_dev->dev,
+                                                    dma_dev->streaming_buffer,
+                                                    DMA_BUFFER_SIZE,
+                                                    DMA_TO_DEVICE);
+    
+    if (dma_mapping_error(dma_dev->dev, dma_dev->streaming_dma_handle)) {
+        dev_err(dma_dev->dev, "Failed to map streaming DMA buffer\n");
+        kfree(dma_dev->streaming_buffer);
+        dma_dev->streaming_buffer = NULL;
+        return -ENOMEM;
+    }
+
+    dev_info(dma_dev->dev, "Streaming DMA buffer mapped\n");
+    dev_info(dma_dev->dev, "DMA address: 0x%llx\n",
+             (unsigned long long)dma_dev->streaming_dma_handle);
+
+    /* Program device with DMA address */
+    /* Example: writel(dma_dev->streaming_dma_handle, device_dma_addr_reg); */
+
+    /* Start DMA transfer */
+    /* Example: writel(DMA_START, device_control_reg); */
+
+    return 0;
+}
+
+/**
+ * @brief Cleanup coherent DMA resources
+ */
+static void cleanup_coherent_dma(struct dma_device *dma_dev)
+{
+    if (dma_dev->coherent_buffer) {
+        dma_free_coherent(dma_dev->dev,
+                         DMA_BUFFER_SIZE,
+                         dma_dev->coherent_buffer,
+                         dma_dev->coherent_dma_handle);
+        dma_dev->coherent_buffer = NULL;
+        dev_info(dma_dev->dev, "Coherent DMA buffer freed\n");
+    }
+}
+
+/**
+ * @brief Cleanup streaming DMA resources
+ */
+static void cleanup_streaming_dma(struct dma_device *dma_dev)
+{
+    if (dma_dev->streaming_buffer) {
+        /* Unmap DMA buffer */
+        dma_unmap_single(dma_dev->dev,
+                        dma_dev->streaming_dma_handle,
+                        DMA_BUFFER_SIZE,
+                        DMA_TO_DEVICE);
+        
+        /* Free kernel memory */
+        kfree(dma_dev->streaming_buffer);
+        dma_dev->streaming_buffer = NULL;
+        dev_info(dma_dev->dev, "Streaming DMA buffer freed\n");
+    }
+}
+
+/**
+ * @brief Platform driver probe function
+ */
+static int dma_probe(struct platform_device *pdev)
+{
+    struct dma_device *dma_dev;
+    int ret;
+
+    dev_info(&pdev->dev, "Probing DMA example device\n");
+
+    /* Allocate private data */
+    dma_dev = devm_kzalloc(&pdev->dev, sizeof(*dma_dev), GFP_KERNEL);
+    if (!dma_dev)
+        return -ENOMEM;
+
+    dma_dev->dev = &pdev->dev;
+    platform_set_drvdata(pdev, dma_dev);
+
+    /* Set DMA mask (32-bit addressing) */
+    ret = dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(32));
+    if (ret) {
+        dev_err(&pdev->dev, "Failed to set DMA mask\n");
+        return ret;
+    }
+
+    /* Example 1: Coherent DMA */
+    ret = coherent_dma_example(dma_dev);
+    if (ret)
+        return ret;
+
+    /* Example 2: Streaming DMA */
+    ret = streaming_dma_example(dma_dev);
+    if (ret) {
+        cleanup_coherent_dma(dma_dev);
+        return ret;
+    }
+
+    dev_info(&pdev->dev, "DMA example device probed successfully\n");
+    return 0;
+}
+
+/**
+ * @brief Platform driver remove function
+ */
+static int dma_remove(struct platform_device *pdev)
+{
+    struct dma_device *dma_dev = platform_get_drvdata(pdev);
+
+    dev_info(&pdev->dev, "Removing DMA example device\n");
+
+    cleanup_streaming_dma(dma_dev);
+    cleanup_coherent_dma(dma_dev);
+
+    dev_info(&pdev->dev, "DMA example device removed\n");
+    return 0;
+}
+
+static struct platform_driver dma_driver = {
+    .probe = dma_probe,
+    .remove = dma_remove,
+    .driver = {
+        .name = "dma-example",
+    },
+};
+
+module_platform_driver(dma_driver);
+

package/augment-extensions/coding-standards/c/examples/drivers/example.dts

@@ -0,0 +1,64 @@
+/**
+ * @file example.dts
+ * @brief Example Device Tree Source for platform driver
+ * 
+ * This file demonstrates device tree bindings for the platform driver.
+ * 
+ * To compile:
+ *   dtc -I dts -O dtb -o example.dtb example.dts
+ * 
+ * To decompile:
+ *   dtc -I dtb -O dts -o example.dts example.dtb
+ */
+
+/dts-v1/;
+
+/ {
+    model = "Example Platform";
+    compatible = "example,platform";
+    #address-cells = <1>;
+    #size-cells = <1>;
+
+    /* Example platform device */
+    example_device@40000000 {
+        compatible = "example,platform-device";
+        reg = <0x40000000 0x1000>;  /* Base address and size */
+        interrupts = <0 32 4>;       /* IRQ number and flags */
+        status = "okay";
+        
+        /* Custom properties */
+        clock-frequency = <50000000>;
+        device-id = <0>;
+    };
+
+    /* Another example device */
+    example_device@40001000 {
+        compatible = "example,platform-device";
+        reg = <0x40001000 0x1000>;
+        interrupts = <0 33 4>;
+        status = "okay";
+        
+        clock-frequency = <50000000>;
+        device-id = <1>;
+    };
+
+    /* DMA controller example */
+    dma_controller@40002000 {
+        compatible = "example,dma-controller";
+        reg = <0x40002000 0x1000>;
+        interrupts = <0 34 4>;
+        #dma-cells = <1>;
+        status = "okay";
+    };
+
+    /* Device using DMA */
+    uart@40003000 {
+        compatible = "example,uart";
+        reg = <0x40003000 0x100>;
+        interrupts = <0 35 4>;
+        dmas = <&dma_controller 0>;
+        dma-names = "tx-rx";
+        status = "okay";
+    };
+};
+

package/augment-extensions/coding-standards/c/examples/drivers/platform-driver.c

@@ -0,0 +1,174 @@
+/**
+ * @file platform-driver.c
+ * @brief Example Linux platform device driver
+ * 
+ * This example demonstrates:
+ * - Platform driver registration
+ * - Device tree binding
+ * - Probe and remove functions
+ * - Resource management (devm_* functions)
+ * - Platform device matching
+ * 
+ * Device Tree Example:
+ *   example_device {
+ *       compatible = "example,platform-device";
+ *       reg = <0x40000000 0x1000>;
+ *   };
+ * 
+ * Build: make
+ * Load: sudo insmod platform-driver.ko
+ */
+
+#include <linux/module.h>
+#include <linux/kernel.h>
+#include <linux/platform_device.h>
+#include <linux/of.h>
+#include <linux/io.h>
+#include <linux/slab.h>
+
+MODULE_LICENSE("GPL");
+MODULE_AUTHOR("Example Author");
+MODULE_DESCRIPTION("Example platform device driver");
+MODULE_VERSION("1.0");
+
+#define DRIVER_NAME "example-platform"
+
+/**
+ * @brief Private device data structure
+ */
+struct example_device {
+    void __iomem *base;
+    struct device *dev;
+    int irq;
+};
+
+/**
+ * @brief Platform driver probe function
+ * @param pdev Platform device
+ * @return 0 on success, negative error code on failure
+ */
+static int example_probe(struct platform_device *pdev)
+{
+    struct example_device *priv;
+    struct resource *res;
+    int ret;
+
+    dev_info(&pdev->dev, "Probing device\n");
+
+    /* Allocate private data using devm (auto-freed on remove) */
+    priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL);
+    if (!priv)
+        return -ENOMEM;
+
+    priv->dev = &pdev->dev;
+
+    /* Get memory resource from device tree or platform data */
+    res = platform_get_resource(pdev, IORESOURCE_MEM, 0);
+    if (!res) {
+        dev_err(&pdev->dev, "Failed to get memory resource\n");
+        return -ENODEV;
+    }
+
+    /* Map device registers (auto-unmapped on remove) */
+    priv->base = devm_ioremap_resource(&pdev->dev, res);
+    if (IS_ERR(priv->base)) {
+        dev_err(&pdev->dev, "Failed to map registers\n");
+        return PTR_ERR(priv->base);
+    }
+
+    /* Get IRQ (optional) */
+    priv->irq = platform_get_irq(pdev, 0);
+    if (priv->irq < 0) {
+        dev_warn(&pdev->dev, "No IRQ specified\n");
+        priv->irq = -1;
+    } else {
+        dev_info(&pdev->dev, "IRQ: %d\n", priv->irq);
+    }
+
+    /* Store private data in platform device */
+    platform_set_drvdata(pdev, priv);
+
+    /* Initialize hardware */
+    /* Example: Write to control register */
+    /* iowrite32(0x1, priv->base + CTRL_REG_OFFSET); */
+
+    dev_info(&pdev->dev, "Device probed successfully\n");
+    dev_info(&pdev->dev, "Base address: %p\n", priv->base);
+
+    return 0;
+}
+
+/**
+ * @brief Platform driver remove function
+ * @param pdev Platform device
+ * @return 0 on success
+ */
+static int example_remove(struct platform_device *pdev)
+{
+    struct example_device *priv = platform_get_drvdata(pdev);
+
+    dev_info(&pdev->dev, "Removing device\n");
+
+    /* Shutdown hardware */
+    /* Example: Disable device */
+    /* iowrite32(0x0, priv->base + CTRL_REG_OFFSET); */
+
+    /* Resources allocated with devm_* are automatically freed */
+
+    dev_info(&pdev->dev, "Device removed\n");
+    return 0;
+}
+
+/**
+ * @brief Device tree match table
+ */
+static const struct of_device_id example_of_match[] = {
+    { .compatible = "example,platform-device", },
+    { /* sentinel */ }
+};
+MODULE_DEVICE_TABLE(of, example_of_match);
+
+/**
+ * @brief Platform driver structure
+ */
+static struct platform_driver example_driver = {
+    .probe = example_probe,
+    .remove = example_remove,
+    .driver = {
+        .name = DRIVER_NAME,
+        .of_match_table = example_of_match,
+    },
+};
+
+/**
+ * @brief Module initialization
+ */
+static int __init example_init(void)
+{
+    int ret;
+
+    pr_info("example_platform: Registering platform driver\n");
+
+    ret = platform_driver_register(&example_driver);
+    if (ret) {
+        pr_err("example_platform: Failed to register driver\n");
+        return ret;
+    }
+
+    pr_info("example_platform: Driver registered\n");
+    return 0;
+}
+
+/**
+ * @brief Module cleanup
+ */
+static void __exit example_exit(void)
+{
+    pr_info("example_platform: Unregistering platform driver\n");
+    platform_driver_unregister(&example_driver);
+    pr_info("example_platform: Driver unregistered\n");
+}
+
+module_init(example_init);
+module_exit(example_exit);
+