dsh-plugin-amdgpu-inspect

Readme

# AMDGPU Inspect

Structured AMDGPU code-object and ISA inspection for DeepSeek Harness.

The plugin turns an existing HSACO or AMDGPU ELF file into bounded JSON that an agent can query. It reports compiler artifacts without compiling source, executing a kernel, predicting performance, or prescribing an optimization.

```text
AMDGPU ELF -> llvm-readelf + llvm-objdump -> normalized object model -> DSH tools
```

## Tools

### `amdgpu_object_inspect`

List kernels and report public code-object metadata plus instruction-category counts:

```json
{ "path": "/tmp/vector-add.hsaco" }
```

### `amdgpu_isa_query`

Query one kernel's normalized instruction stream without placing the complete disassembly in model context:

```json
{
  "path": "/tmp/vector-add.hsaco",
  "kernel": "vector_add",
  "opcodes": ["scratch_*", "s_waitcnt"],
  "cursor": 0,
  "limit": 40
}
```

The result contains addresses, opcodes, operands, categories, and a `nextCursor` when more matches remain.

## Install

Requirements:

- Linux
- DeepSeek Harness developer preview
- ROCm LLVM tools in `/opt/rocm/llvm/bin` or on `PATH`

Install the bundle from GitHub:

```sh
dsh plugin --profile web add github:yujiaoliang/dsh-plugin-amdgpu-inspect
dsh --profile web
```

The package ships plain ESM JavaScript and needs no install-time build script.

## Kernel X-Ray Skill

[`skills/kernel-xray/SKILL.md`](skills/kernel-xray/SKILL.md) is the opinionated layer: it tells an agent how to compile before/after artifacts, query this plugin, form hypotheses, and require a workload measurement before claiming a speedup. The plugin itself remains a low-level facts API.

## Design

- `llvm-readelf --notes` supplies public AMDGPU metadata.
- `llvm-objdump --disassemble --demangle` supplies ISA.
- A one-artifact cache is keyed by absolute path, size, and modification time.
- ISA queries are capped at 200 records and support deterministic cursors.
- Child processes run without a shell and honor tool-call cancellation.
- Inputs are limited to regular files no larger than 256 MiB.

## Security boundary

This version invokes LLVM and reads the artifact directly on the DSH host. It does not inherit a deployment's virtual filesystem or subprocess provider, so treat access as host-local rather than sandboxed. It never loads the artifact into an HSA runtime or executes GPU code. LLVM diagnostics can expose local paths.

## Limitations

- Parsing follows the text emitted by current ROCm LLVM tools; fixture coverage cannot guarantee every historical or future output spelling.
- Kernel arguments, symbols, relocations, control-flow graphs, and binary encodings are not exposed yet.
- The plugin reports static facts only. Resource counts and instruction counts do not establish performance.

## Development

Tests use synthetic public-format metadata and disassembly; no GPU or ROCm installation is required:

```sh
npm test
```

## License

MIT. ROCm and LLVM are external tools and are not redistributed.