decuda 0.1.1

# decuda Specification

This document defines the contract for decuda's CLI, IR, and per-target
output conventions.

## CLI Subcommands

### `migrate`

Translate CUDA files to one or more targets.

```
decuda migrate -i <input> -o <output> [--target <t>] [--dry-run] [--verbose] [--filter <substr>]
```

| Flag | Description |
|------|-------------|
| `-i, --input` | Input `.cu`/`.cuh` file or directory |
| `-o, --output` | Output directory; each target writes into `<output>/<target>/` |
| `-t, --target` | `hip`, `sycl`, `rust`, `opencl`, or `all` (default: `all`) |
| `--dry-run` | Parse and plan only; do not write output files |
| `-v, --verbose` | Emit progress to stderr |
| `--filter <substr>` | Only process files whose path contains `<substr>` |

### `inspect`

Print the IR nodes found in a file (for debugging).

```
decuda inspect -i <input> [--filter <substr>]
```

### `list-apis`

List all CUDA APIs known to the database.

```
decuda list-apis [--target <t>]
```

## IR Node Kinds

| Node | Description |
|------|-------------|
| `QualifierDecl` | Function/storage qualifier (`__global__`, `__shared__`, ...) |
| `KernelDef` | Kernel definition (`__global__` function with body) |
| `KernelLaunch` | `kernel<<<grid, block, smem, stream>>>(args)` |
| `RuntimeCall` | CUDA runtime API call (`cudaMalloc`, ...) |
| `BuiltinRef` | Built-in variable or sync intrinsic (`threadIdx`, `__syncthreads`) |
| `HeaderInclude` | `#include` directive for a CUDA header |
| `AtomicIntrinsic` | Atomic operation (`atomicAdd`, `atomicCAS`, ...) |
| `Warning` | Untranslatable construct; copied through with a warning |

## Supported CUDA Constructs

| Construct | HIP | SYCL | Rust | OpenCL |
|-----------|-----|------|------|--------|
| `__global__`/`__device__` qualifiers | rewritten | placeholder | placeholder | rewritten |
| Kernel launch `<<<g,b>>>(...)` | `hipLaunchKernelGGL` | `queue.submit` placeholder | `cust` launch placeholder | `clEnqueueNDRangeKernel` |
| `threadIdx`/`blockIdx`/`blockDim`/`gridDim` | kept as-is | `item.get_*()` | `thread_idx`/`block_idx` | `get_local_id(0)`/`get_group_id(0)` |
| `__syncthreads()`/`__syncwarp()` | kept as-is | `item.barrier()` | `group.sync()` | `barrier(CLK_LOCAL_MEM_FENCE)` |
| `atomicAdd`/`atomicCAS`/... | kept as-is | kept as-is | kept as-is | kept as-is |
| `__shared__`/`__constant__` | kept as-is | placeholder | placeholder | `__local`/`__constant` |
| `cudaMalloc`/`cudaFree`/`cudaMemcpy` | `hipMalloc`/etc | flagged | flagged | flagged |
| Streams/events | `hipStream*`/`hipEvent*` | flagged | flagged | flagged |
| `cudaError_t`/`dim3` aliases | `hipError_t`/`dim3` | `sycl::errc`/`sycl::range<3>` | `cust::CUresult`/`(u32,u32,u32)` | `cl_int`/`[usize;3]` |
| `__launch_bounds__` | flagged | flagged | flagged | flagged |
| Inline PTX / texture references | flagged | flagged | flagged | flagged |
| Warp primitives (`__shfl_sync`, `__ballot_sync`, ...) | preserved verbatim | preserved verbatim | preserved verbatim | preserved verbatim |

## Per-Target Output Conventions

| Target | File extension | Output directory |
|--------|---------------|-----------------|
| `hip` | `.hip.cpp` | `<output>/hip/` |
| `sycl` | `.sycl.cpp` | `<output>/sycl/` |
| `rust` | `.rs` | `<output>/rust/` |
| `opencl` | `.cl` | `<output>/opencl/` |

Directory layout of the input is preserved under each target subfolder.

## Migration Report

A `migration-report.json.<timestamp>` file is written next to the output
directories. It contains per-file, per-target warnings for:
- Unmapped CUDA runtime APIs (no automatic translation)
- Untranslatable qualifiers (`__launch_bounds__`, ...)
- Parse errors

A human-readable summary is printed to stdout.