Merge pull request #269 from SKaiNET-developers/feature/267-arduino-plain-c

Add support for arduino c code generating

Author: michalharakal

README.md

@@ -72,12 +72,25 @@ println(ds.describe())
 ### SKaiNET is Compiler
 
 - MLIR/StableHLO based lowering (modules provided in `SKaiNET-compile-*`)
-
 ```kotlin
 // Illustrative: export graph to JSON/StableHLO IR
 val ir = Compile.toStableHlo(model)
 println(ir.pretty())
 ```
+- **Arduino C Code Generation**: Export models to standalone, optimized C99 code with static memory allocation.
+
+```kotlin
+// Export model to an Arduino library
+val facade = CCodegenFacade()
+facade.exportToArduinoLibrary(
+    model = model,
+    forwardPass = { ctx -> model.forward(input, ctx) },
+    outputPath = "build/arduino",
+    libraryName = "MyModel"
+)
+```
+
+Read the [Deep Technical Explanation](docs/arduino-c-codegen.md) for more details.
 
 ### SKaiNET is for Developers
 

docs/SKaiNET-compiler.svg

@@ -0,0 +1,75 @@
+# Arduino C Code Generation
+
+SKaiNET provides a specialized compiler backend for exporting trained neural networks to highly optimized, standalone C99 code suitable for microcontrollers like Arduino.
+
+## Overview
+
+The Arduino C code generation process transforms a high-level Kotlin model into a memory-efficient C implementation. It prioritizes static memory allocation, minimal overhead, and numerical consistency with the original model.
+
+### Codegen Pipeline
+
+```mermaid
+graph TD
+    A[Kotlin Model] --> B[Recording Pass]
+    B --> C[Execution Tape]
+    C --> D[Compute Graph]
+    D --> E[Graph Validation]
+    E --> F[Memory Layout Calculation]
+    F --> G[C Code Emission]
+    G --> H[Arduino Library Packaging]
+    H --> I[Generated .h/.c files]
+```
+
+## Technical Deep Dive
+
+### 1. Tape-based Tracing
+Instead of static analysis of the Kotlin code, SKaiNET uses a dynamic tracing mechanism. When you call `exportToArduinoLibrary`, the framework executes a single forward pass of your model using a specialized `RecordingContext`.
+- Every operation (Dense, ReLU, etc.) is recorded onto an **Execution Tape**.
+- This approach handles Kotlin's language features (loops, conditionals) naturally, as it only records the actual operations that were executed.
+
+### 2. Compute Graph Construction
+The execution tape is converted into a directed acyclic graph (DAG) called `ComputeGraph`.
+- Nodes represent operations (Ops).
+- Edges represent data flow (Tensors).
+- During this phase, the compiler performs **Shape Inference** to ensure every tensor has a fixed, known size.
+
+### 3. Static Memory Management
+Microcontrollers typically have very limited RAM and lack robust heap management. SKaiNET uses a **Ping-Pong Buffer Strategy** to eliminate dynamic memory allocation (`malloc`/`free`) during inference.
+
+#### Ping-Pong Buffer Strategy
+The compiler calculates the maximum size required for any intermediate tensor in the graph and allocates exactly two static buffers of that size.
+
+```mermaid
+sequenceDiagram
+    participant I as Input
+    participant B1 as Buffer A
+    participant B2 as Buffer B
+    participant O as Output
+    
+    I->>B1: Layer 1 (Input -> A)
+    B1->>B2: Layer 2 (A -> B)
+    B2->>B1: Layer 3 (B -> A)
+    B1->>O: Layer 4 (A -> Output)
+```
+
+- **Buffer Reuse**: Instead of allocating space for every layer's output, buffers are reused.
+- **Direct Output Optimization**: The first layer reads from the input pointer, and the last layer writes directly to the output pointer, avoiding unnecessary copies.
+
+### 4. Code Generation (Emission)
+The `CCodeGenerator` emits C99-compatible code using templates.
+- **Weights & Biases**: Extracted from the trained Kotlin model and serialized as `static const float` arrays. This places them in Flash memory (PROGMEM) on many microcontrollers, saving precious RAM.
+- **Kernel Implementation**: Operations like `Dense` (Linear) are implemented as optimized nested loops.
+- **Header Generation**: Produces a clean API for the user:
+  ```c
+  int model_inference(const float* input, float* output);
+  ```
+
+### 5. Validation
+The generator performs post-generation validation:
+- **Static Allocation Check**: Ensures no dynamic allocation is present in the generated source.
+- **Buffer Alternation Check**: Verifies that the ping-pong strategy is correctly implemented without data races or overwrites.
+
+## Performance and Constraints
+- **Floating Point**: Currently optimized for `FP32`.
+- **Supported Ops**: `Dense`, `ReLU`, `Sigmoid`, `Tanh`, `Add`, `MatMul`.
+- **Memory**: Total memory consumption is `TotalWeights + 2 * MaxIntermediateTensor`.

docs/arduino-c-codegen.md

@@ -32,6 +32,7 @@ include("skainet-lang:skainet-kan")
 include("skainet-compile:skainet-compile-core")
 include("skainet-compile:skainet-compile-dag")
 include("skainet-compile:skainet-compile-json")
+include("skainet-compile:skainet-compile-c")
 
 // ====== BACKENDS
 include("skainet-backends:skainet-backend-cpu")

settings.gradle.kts

@@ -0,0 +1,133 @@
+public final class sk/ainet/compile/c/ArduinoCodegenIntegration {
+	public fun <init> ()V
+	public final fun generateArduinoLibrary (Lsk/ainet/lang/graph/ComputeGraph;Ljava/lang/String;Ljava/lang/String;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+}
+
+public final class sk/ainet/compile/c/ArduinoLibraryPackager {
+	public fun <init> ()V
+	public final fun createLibraryStructure (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lsk/ainet/compile/c/MemoryLayout;[I[I)Lsk/ainet/compile/c/ArduinoLibraryResult;
+}
+
+public final class sk/ainet/compile/c/ArduinoLibraryResult {
+	public fun <init> (Ljava/lang/String;Lsk/ainet/compile/c/MemoryLayout;Ljava/util/List;Ljava/util/List;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component2 ()Lsk/ainet/compile/c/MemoryLayout;
+	public final fun component3 ()Ljava/util/List;
+	public final fun component4 ()Ljava/util/List;
+	public final fun copy (Ljava/lang/String;Lsk/ainet/compile/c/MemoryLayout;Ljava/util/List;Ljava/util/List;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+	public static synthetic fun copy$default (Lsk/ainet/compile/c/ArduinoLibraryResult;Ljava/lang/String;Lsk/ainet/compile/c/MemoryLayout;Ljava/util/List;Ljava/util/List;ILjava/lang/Object;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getGeneratedFiles ()Ljava/util/List;
+	public final fun getLibraryPath ()Ljava/lang/String;
+	public final fun getMemoryRequirements ()Lsk/ainet/compile/c/MemoryLayout;
+	public final fun getSupportedOperations ()Ljava/util/List;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class sk/ainet/compile/c/CCodeGenerator {
+	public static final field Companion Lsk/ainet/compile/c/CCodeGenerator$Companion;
+	public fun <init> (Lsk/ainet/lang/graph/ComputeGraph;)V
+	public final fun calculateMemoryRequirements ()Lsk/ainet/compile/c/MemoryLayout;
+	public final fun extractWeights ()Ljava/util/List;
+	public final fun generateActivationFunction (Lsk/ainet/lang/graph/GraphNode;)Lsk/ainet/compile/c/LayerCode;
+	public final fun generateActivationFunctionWithAccuracy (Lsk/ainet/lang/graph/GraphNode;)Lsk/ainet/compile/c/LayerCode;
+	public final fun generateAllLayers ()Ljava/util/List;
+	public final fun generateDenseLayer (Lsk/ainet/lang/graph/GraphNode;)Lsk/ainet/compile/c/LayerCode;
+	public final fun generateDenseLayerWithAccuracy (Lsk/ainet/lang/graph/GraphNode;)Lsk/ainet/compile/c/LayerCode;
+	public final fun generateTransposeLayer (Lsk/ainet/lang/graph/GraphNode;)Lsk/ainet/compile/c/LayerCode;
+	public final fun validateGeneratedCodeBufferAlternation (Ljava/lang/String;)Lsk/ainet/lang/tensor/ops/ValidationResult;
+	public final fun validateGeneratedCodeStaticAllocation (Ljava/lang/String;)Lsk/ainet/lang/tensor/ops/ValidationResult;
+	public final fun validateGraph ()Lsk/ainet/lang/tensor/ops/ValidationResult;
+	public final fun validateMemoryManagement ()Lsk/ainet/lang/tensor/ops/ValidationResult;
+	public final fun validateOperations ()Lsk/ainet/lang/tensor/ops/ValidationResult;
+}
+
+public final class sk/ainet/compile/c/CCodeGenerator$Companion {
+}
+
+public final class sk/ainet/compile/c/CCodegenFacade {
+	public fun <init> ()V
+	public final fun exportGraphToArduinoLibrary (Lsk/ainet/lang/graph/ComputeGraph;Ljava/lang/String;Ljava/lang/String;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+	public final fun exportToArduinoLibrary (Ljava/lang/Object;Ljava/lang/String;Ljava/lang/String;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+	public final fun exportToArduinoLibrary (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Ljava/lang/String;Ljava/lang/String;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+	public static synthetic fun exportToArduinoLibrary$default (Lsk/ainet/compile/c/CCodegenFacade;Ljava/lang/Object;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+	public static synthetic fun exportToArduinoLibrary$default (Lsk/ainet/compile/c/CCodegenFacade;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lsk/ainet/compile/c/ArduinoLibraryResult;
+}
+
+public final class sk/ainet/compile/c/LayerCode {
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;[I[ILjava/lang/String;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun component3 ()[I
+	public final fun component4 ()[I
+	public final fun component5 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;[I[ILjava/lang/String;)Lsk/ainet/compile/c/LayerCode;
+	public static synthetic fun copy$default (Lsk/ainet/compile/c/LayerCode;Ljava/lang/String;Ljava/lang/String;[I[ILjava/lang/String;ILjava/lang/Object;)Lsk/ainet/compile/c/LayerCode;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getCodeFragment ()Ljava/lang/String;
+	public final fun getInputShape ()[I
+	public final fun getLayerName ()Ljava/lang/String;
+	public final fun getOperationType ()Ljava/lang/String;
+	public final fun getOutputShape ()[I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class sk/ainet/compile/c/MemoryLayout {
+	public fun <init> (IIILjava/util/List;)V
+	public final fun component1 ()I
+	public final fun component2 ()I
+	public final fun component3 ()I
+	public final fun component4 ()Ljava/util/List;
+	public final fun copy (IIILjava/util/List;)Lsk/ainet/compile/c/MemoryLayout;
+	public static synthetic fun copy$default (Lsk/ainet/compile/c/MemoryLayout;IIILjava/util/List;ILjava/lang/Object;)Lsk/ainet/compile/c/MemoryLayout;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getBufferSizes ()Ljava/util/List;
+	public final fun getMaxIntermediateSize ()I
+	public final fun getTotalMemoryRequired ()I
+	public final fun getTotalWeightSize ()I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class sk/ainet/compile/c/Platform_androidKt {
+	public static final fun platformCreateDirectory (Ljava/lang/String;)V
+	public static final fun platformWriteFile (Ljava/lang/String;Ljava/lang/String;)V
+}
+
+public final class sk/ainet/compile/c/WeightArray {
+	public fun <init> (Ljava/lang/String;[F[IZ)V
+	public synthetic fun <init> (Ljava/lang/String;[F[IZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component2 ()[F
+	public final fun component3 ()[I
+	public final fun component4 ()Z
+	public final fun copy (Ljava/lang/String;[F[IZ)Lsk/ainet/compile/c/WeightArray;
+	public static synthetic fun copy$default (Lsk/ainet/compile/c/WeightArray;Ljava/lang/String;[F[IZILjava/lang/Object;)Lsk/ainet/compile/c/WeightArray;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getName ()Ljava/lang/String;
+	public final fun getShape ()[I
+	public final fun getValues ()[F
+	public fun hashCode ()I
+	public final fun isWeight ()Z
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class sk/ainet/compile/c/templates/ExampleTemplate {
+	public static final field INSTANCE Lsk/ainet/compile/c/templates/ExampleTemplate;
+	public final fun generate (Ljava/lang/String;[I[ILjava/lang/String;)Ljava/lang/String;
+	public static synthetic fun generate$default (Lsk/ainet/compile/c/templates/ExampleTemplate;Ljava/lang/String;[I[ILjava/lang/String;ILjava/lang/Object;)Ljava/lang/String;
+	public final fun generateMinimal (Ljava/lang/String;II)Ljava/lang/String;
+}
+
+public final class sk/ainet/compile/c/templates/HeaderTemplate {
+	public static final field INSTANCE Lsk/ainet/compile/c/templates/HeaderTemplate;
+	public final fun generate (Ljava/lang/String;[I[ILsk/ainet/compile/c/MemoryLayout;)Ljava/lang/String;
+}
+
+public final class sk/ainet/compile/c/templates/SourceTemplate {
+	public static final field INSTANCE Lsk/ainet/compile/c/templates/SourceTemplate;
+	public final fun generate (Ljava/lang/String;Ljava/util/List;Ljava/util/List;)Ljava/lang/String;
+}
+