Skip to content

TOPOLOGY.adoc

Latest commit

 

History

History
151 lines (117 loc) · 4.69 KB

TOPOLOGY.adoc

File metadata and controls

151 lines (117 loc) · 4.69 KB
Raw

TOPOLOGY — halideiser

Module dependency graph for the halideiser codebase.

High-Level Flow

halideiser.toml  ──►  Pipeline Parser  ──►  Idris2 ABI Proofs
                       (src/manifest/)       (src/interface/abi/)
                             │                      │
                             ▼                      ▼
                      Halide Codegen  ◄────  Generated C Headers
                      (src/codegen/)        (src/interface/generated/)
                             │
                             ▼
                      Schedule Tuner  ──►  Compiled Pipeline
                      (auto-tuning)        (native code)
                             │
                             ▼
                       Zig FFI Bridge
                      (src/interface/ffi/)

Directory Map

Directory Language Purpose

src/main.rs

Rust

CLI entry point (clap subcommands)

src/lib.rs

Rust

Library API surface

src/manifest/

Rust

Parse and validate halideiser.toml

src/codegen/

Rust

Emit Halide algorithm + schedule code

src/abi/

Rust

Runtime ABI types mirroring Idris2 proofs

src/interface/abi/Types.idr

Idris2

Pipeline stage types, scheduling primitives, hardware targets

src/interface/abi/Layout.idr

Idris2

Halide buffer_t memory layout proofs

src/interface/abi/Foreign.idr

Idris2

FFI declarations for pipeline compilation and execution

src/interface/ffi/src/main.zig

Zig

C-ABI FFI implementation

src/interface/ffi/build.zig

Zig

Build shared/static library

src/interface/ffi/test/

Zig

Integration tests verifying FFI matches ABI

src/interface/generated/abi/

C

Auto-generated headers from Idris2 ABI

tests/

Rust

End-to-end pipeline tests

examples/

TOML/Rust

Example pipeline manifests

verification/

—

Formal verification artifacts

container/

—

Stapeln container definitions

docs/

AsciiDoc

Architecture, theory, attribution

.machine_readable/

A2ML/TOML

State, ecosystem, policies, bot directives

Rust Module Graph

main.rs
  ├── manifest::load_manifest()
  ├── manifest::validate()
  ├── codegen::generate_all()
  ├── codegen::build()
  └── codegen::run()

lib.rs
  ├── pub mod abi        (Rust-side ABI types)
  ├── pub mod codegen    (Halide code generation)
  └── pub mod manifest   (TOML parser + validator)

Idris2 ABI Module Graph

Halideiser.ABI.Types
  ├── PipelineStage      (blur, sharpen, resize, convolve, ...)
  ├── SchedulePrimitive  (tile, vectorize, parallelize, compute_at, ...)
  ├── HardwareTarget     (x86_SSE, x86_AVX, ARM_NEON, CUDA, OpenCL, WASM)
  ├── TileSize           (with proof: divides dimension)
  ├── BufferDimension    (width, height, channels, frames)
  └── Result, Handle, Platform (shared ABI base)

Halideiser.ABI.Layout
  ├── imports Types
  ├── HalideBufferLayout (stride, extent, min per dimension)
  ├── BufferBoundsProof  (all accesses within allocated memory)
  └── LayoutCompatibility (producer output fits consumer input)

Halideiser.ABI.Foreign
  ├── imports Types, Layout
  ├── halideiser_compile_pipeline  (pipeline description → compiled code)
  ├── halideiser_execute_pipeline  (run compiled pipeline on buffer)
  ├── halideiser_autotune          (search schedule space)
  └── halideiser_init / halideiser_free (lifecycle)

Zig FFI Module Graph

src/main.zig
  ├── halideiser_init()           → allocate pipeline context
  ├── halideiser_free()           → release resources
  ├── halideiser_compile_pipeline() → invoke Halide AOT compiler
  ├── halideiser_execute_pipeline() → run compiled pipeline on buffers
  ├── halideiser_autotune()       → auto-tune schedule parameters
  ├── halideiser_version()        → version string
  └── halideiser_last_error()     → thread-local error

test/integration_test.zig
  └── verifies all exported functions match ABI contract

Data Flow

User: halideiser.toml
  │
  ├─ [workload]
  │    name, entry, strategy
  │
  ├─ [pipeline]
  │    stages = ["gaussian_blur", "sharpen", "resize"]
  │
  ├─ [buffers]
  │    input  = { width = 1920, height = 1080, channels = 3, type = "uint8" }
  │    output = { width = 960, height = 540, channels = 3, type = "uint8" }
  │
  ├─ [schedule]
  │    tile_x = 32, tile_y = 8
  │    vectorize_width = 8
  │    parallelize = true
  │
  └─ [target]
       hardware = "x86_avx2"