kernelvet 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. kernelvet/__init__.py +10 -0
  2. kernelvet/__main__.py +3 -0
  3. kernelvet/benchmark/__init__.py +1 -0
  4. kernelvet/benchmark/engine.py +180 -0
  5. kernelvet/benchmark/workloads.py +153 -0
  6. kernelvet/cli/__init__.py +1 -0
  7. kernelvet/cli/app.py +64 -0
  8. kernelvet/cli/commands/__init__.py +1 -0
  9. kernelvet/cli/commands/diagnose.py +244 -0
  10. kernelvet/cli/commands/migrate.py +334 -0
  11. kernelvet/cli/commands/misc.py +216 -0
  12. kernelvet/cli/output.py +110 -0
  13. kernelvet/compatibility/__init__.py +1 -0
  14. kernelvet/compatibility/data/rocm_matrix.json +123 -0
  15. kernelvet/compatibility/engine.py +24 -0
  16. kernelvet/compatibility/matrix.py +128 -0
  17. kernelvet/compatibility/validators.py +405 -0
  18. kernelvet/config/__init__.py +10 -0
  19. kernelvet/config/settings.py +112 -0
  20. kernelvet/diagnose/__init__.py +1 -0
  21. kernelvet/diagnose/engine.py +296 -0
  22. kernelvet/diagnose/hardware.py +336 -0
  23. kernelvet/diagnose/runtime.py +332 -0
  24. kernelvet/diagnose/software.py +221 -0
  25. kernelvet/diagnose/system.py +67 -0
  26. kernelvet/execution/__init__.py +1 -0
  27. kernelvet/execution/compiler.py +275 -0
  28. kernelvet/execution/runner.py +125 -0
  29. kernelvet/execution/sandbox.py +51 -0
  30. kernelvet/history/__init__.py +3 -0
  31. kernelvet/history/store.py +157 -0
  32. kernelvet/main.py +19 -0
  33. kernelvet/migration/__init__.py +17 -0
  34. kernelvet/migration/analyzer.py +78 -0
  35. kernelvet/migration/auditor.py +89 -0
  36. kernelvet/migration/hipify.py +268 -0
  37. kernelvet/migration/planner.py +128 -0
  38. kernelvet/migration/rules.py +564 -0
  39. kernelvet/migration/scanner.py +234 -0
  40. kernelvet/migration/workflow.py +135 -0
  41. kernelvet/models/__init__.py +35 -0
  42. kernelvet/models/common.py +102 -0
  43. kernelvet/models/migration.py +236 -0
  44. kernelvet/models/report.py +126 -0
  45. kernelvet/models/system.py +89 -0
  46. kernelvet/reporting/__init__.py +80 -0
  47. kernelvet/reporting/common.py +74 -0
  48. kernelvet/reporting/html.py +149 -0
  49. kernelvet/reporting/json.py +20 -0
  50. kernelvet/reporting/loader.py +48 -0
  51. kernelvet/reporting/markdown.py +256 -0
  52. kernelvet/reporting/sarif.py +79 -0
  53. kernelvet/reporting/terminal.py +276 -0
  54. kernelvet/tui/__init__.py +1 -0
  55. kernelvet/tui/app.py +177 -0
  56. kernelvet/tui/screens/__init__.py +1 -0
  57. kernelvet/tui/screens/base.py +34 -0
  58. kernelvet/tui/screens/devices.py +211 -0
  59. kernelvet/tui/screens/diagnose.py +212 -0
  60. kernelvet/tui/screens/help.py +47 -0
  61. kernelvet/tui/screens/migration.py +573 -0
  62. kernelvet/tui/screens/overview.py +195 -0
  63. kernelvet/tui/screens/tools.py +357 -0
  64. kernelvet/tui/state.py +55 -0
  65. kernelvet/tui/widgets/__init__.py +1 -0
  66. kernelvet/tui/widgets/common.py +82 -0
  67. kernelvet/tui/workers/__init__.py +25 -0
  68. kernelvet/utils/__init__.py +1 -0
  69. kernelvet/utils/paths.py +48 -0
  70. kernelvet/utils/proc.py +178 -0
  71. kernelvet/utils/redact.py +47 -0
  72. kernelvet/utils/versions.py +34 -0
  73. kernelvet-0.1.0.dist-info/METADATA +275 -0
  74. kernelvet-0.1.0.dist-info/RECORD +77 -0
  75. kernelvet-0.1.0.dist-info/WHEEL +4 -0
  76. kernelvet-0.1.0.dist-info/entry_points.txt +2 -0
  77. kernelvet-0.1.0.dist-info/licenses/LICENSE +197 -0
kernelvet/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ """KernelVet: unofficial open-source diagnostics and CUDA-to-HIP migration toolkit for AMD GPUs.
2
+
3
+ KernelVet is an independent community project. It is not affiliated with, sponsored
4
+ by or endorsed by Advanced Micro Devices, Inc. (AMD), is not an AMD product and is
5
+ not a certification authority.
6
+ """
7
+
8
+ __version__ = "0.1.0"
9
+
10
+ __all__ = ["__version__"]
kernelvet/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from kernelvet.main import main
2
+
3
+ main()
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,180 @@
1
+ """Benchmark runner. Measurements only come from real executions on this host."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import sys
7
+ import tempfile
8
+ from dataclasses import dataclass
9
+ from datetime import UTC, datetime
10
+ from pathlib import Path
11
+
12
+ from kernelvet.benchmark.workloads import HIP_BENCH_SOURCE, TORCH_BENCH_SOURCE
13
+ from kernelvet.config.settings import data_dir
14
+ from kernelvet.diagnose.engine import collect_inventory
15
+ from kernelvet.diagnose.runtime import offload_arch_flags
16
+ from kernelvet.models.report import BenchmarkMeasurement, BenchmarkReport, BenchmarkResult
17
+ from kernelvet.utils.proc import HostContext, ProgressCallback, noop_progress
18
+
19
+ ITERATIONS_MIN, ITERATIONS_MAX = 3, 1000 # timed iterations per measurement
20
+
21
+
22
+ @dataclass
23
+ class BenchmarkOptions:
24
+ hip: bool = True
25
+ torch: bool = True
26
+ inference: bool = False
27
+ iterations: int = 20
28
+ profile: bool = False # wrap the HIP benchmark in rocprofv3 when available
29
+ profile_dir: str | None = None
30
+ python: str | None = None
31
+
32
+ def problem(self) -> str | None:
33
+ """Why this combination of options cannot run anything useful, or None."""
34
+ if not self.hip and not self.torch:
35
+ return "nothing to benchmark: both the HIP and the PyTorch benchmarks are disabled"
36
+ if self.profile and not self.hip:
37
+ return "--profile profiles the HIP benchmark, which is disabled"
38
+ if self.inference and not self.torch:
39
+ return "--inference is part of the PyTorch benchmark, which is disabled"
40
+ return None
41
+
42
+
43
+ def default_profile_dir() -> Path:
44
+ """A new, lasting folder for rocprofv3 output (the build folder is temporary)."""
45
+ stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
46
+ return data_dir() / "profiles" / stamp
47
+
48
+
49
+ def parse_hip_bench(stdout: str) -> list[BenchmarkMeasurement]:
50
+ out = []
51
+ for line in stdout.splitlines():
52
+ parts = line.split()
53
+ if len(parts) == 5 and parts[0] == "RESULT":
54
+ try:
55
+ out.append(
56
+ BenchmarkMeasurement(
57
+ name=parts[1], unit=parts[2], value=float(parts[3]), iterations=int(parts[4])
58
+ )
59
+ )
60
+ except ValueError:
61
+ continue
62
+ return out
63
+
64
+
65
+ def run_hip_benchmark(ctx: HostContext, opts: BenchmarkOptions, gfx_targets: list[str]) -> BenchmarkResult:
66
+ res = BenchmarkResult(
67
+ id="hip.core", name="HIP kernels, memory and SGEMM", backend="hip", status="SKIPPED"
68
+ )
69
+ if not ctx.which("hipcc"):
70
+ res.reason = "hipcc not found"
71
+ return res
72
+ if not gfx_targets:
73
+ res.reason = "no AMD GPU detected"
74
+ return res
75
+ with tempfile.TemporaryDirectory(prefix="kernelvet-bench-") as tmp:
76
+ src = Path(tmp) / "bench.hip"
77
+ exe = Path(tmp) / "bench"
78
+ src.write_text("#include <chrono>\n#include <cstdlib>\n" + HIP_BENCH_SOURCE)
79
+ build = ctx.run(
80
+ ["hipcc", "-O3", *offload_arch_flags(gfx_targets), "-o", str(exe), str(src)], timeout=300
81
+ )
82
+ if not build.ok:
83
+ res.status, res.reason = "FAIL", f"benchmark did not compile: {build.describe_failure()}"
84
+ return res
85
+ argv = [str(exe), str(opts.iterations)]
86
+ if opts.profile:
87
+ if ctx.which("rocprofv3"):
88
+ pdir = Path(opts.profile_dir or default_profile_dir()).resolve()
89
+ pdir.mkdir(parents=True, exist_ok=True)
90
+ argv = [
91
+ "rocprofv3",
92
+ "--kernel-trace",
93
+ "--stats",
94
+ "-d",
95
+ str(pdir),
96
+ "-o",
97
+ "kernelvet",
98
+ "--",
99
+ *argv,
100
+ ]
101
+ res.profiler = f"rocprofv3 (output: {pdir})"
102
+ else:
103
+ res.profiler = "requested but rocprofv3 is not installed"
104
+ run = ctx.run(argv, timeout=600)
105
+ res.measurements = parse_hip_bench(run.stdout)
106
+ if run.ok and res.measurements:
107
+ res.status = "PASS"
108
+ else:
109
+ res.status = "FAIL"
110
+ res.reason = run.describe_failure() + (
111
+ "; " + " ".join(line for line in run.stdout.splitlines() if line.startswith("ERROR"))
112
+ )
113
+ return res
114
+
115
+
116
+ def run_torch_benchmark(ctx: HostContext, opts: BenchmarkOptions, torch_rocm: bool) -> BenchmarkResult:
117
+ res = BenchmarkResult(
118
+ id="torch.core", name="PyTorch GPU tensor operations", backend="pytorch", status="SKIPPED"
119
+ )
120
+ if not torch_rocm:
121
+ res.reason = "no ROCm build of PyTorch detected"
122
+ return res
123
+ run = ctx.run(
124
+ [
125
+ opts.python or sys.executable,
126
+ "-c",
127
+ TORCH_BENCH_SOURCE,
128
+ str(opts.iterations),
129
+ "1" if opts.inference else "0",
130
+ ],
131
+ timeout=900,
132
+ )
133
+ try:
134
+ data = json.loads(run.stdout.strip().splitlines()[-1])
135
+ except (json.JSONDecodeError, IndexError):
136
+ res.status, res.reason = "FAIL", run.describe_failure()
137
+ return res
138
+ if "error" in data:
139
+ res.status, res.reason = "FAIL", data["error"]
140
+ return res
141
+ res.measurements = [BenchmarkMeasurement(**r) for r in data["results"]]
142
+ res.status = "PASS"
143
+ if data.get("device"):
144
+ res.name += f" on {data['device']}"
145
+ return res
146
+
147
+
148
+ def run_benchmarks(
149
+ ctx: HostContext | None = None,
150
+ opts: BenchmarkOptions | None = None,
151
+ progress: ProgressCallback = noop_progress,
152
+ ) -> BenchmarkReport:
153
+ ctx = ctx or HostContext()
154
+ opts = opts or BenchmarkOptions()
155
+ progress("Collecting configuration metadata", 0.05)
156
+ host, gpus, sw = collect_inventory(ctx, torch=opts.torch, python=opts.python)
157
+ targets = [g.gfx_target for g in gpus if g.vendor_is_amd and g.gfx_target]
158
+ report = BenchmarkReport(host=host, gpus=gpus, software=sw)
159
+ if opts.hip:
160
+ progress("Compiling and running HIP benchmarks", 0.2)
161
+ hip = run_hip_benchmark(ctx, opts, [t for t in targets if t])
162
+ if opts.profile and hip.profiler is None:
163
+ # the benchmark stopped before rocprofv3 could run; say so instead of dropping the request
164
+ hip.profiler = f"requested but not run (HIP benchmark {hip.status})"
165
+ hip.reason = _with_note(hip.reason, "requested profiling (--profile) was not run")
166
+ report.results.append(hip)
167
+ if opts.torch:
168
+ progress("Running PyTorch benchmarks", 0.6)
169
+ torch = run_torch_benchmark(ctx, opts, bool(sw.torch and sw.torch.is_rocm_build))
170
+ if opts.inference and torch.status != "PASS":
171
+ torch.reason = _with_note(
172
+ torch.reason, "the requested inference benchmark (--inference) produced no results"
173
+ )
174
+ report.results.append(torch)
175
+ progress("Done", 1.0)
176
+ return report
177
+
178
+
179
+ def _with_note(reason: str | None, note: str) -> str:
180
+ return f"{reason}; {note}" if reason else note
@@ -0,0 +1,153 @@
1
+ """Benchmark workload sources. Every number comes from running these on the device."""
2
+
3
+ HIP_BENCH_SOURCE = r"""
4
+ #include <hip/hip_runtime.h>
5
+ #include <cstdio>
6
+ #include <vector>
7
+ #include <algorithm>
8
+
9
+ #define CHECK(x) do { hipError_t e = (x); if (e != hipSuccess) { \
10
+ std::printf("ERROR %s %s\n", #x, hipGetErrorString(e)); return 1; } } while (0)
11
+
12
+ __global__ void vadd(const float* a, const float* b, float* c, size_t n) {
13
+ size_t i = blockIdx.x * (size_t)blockDim.x + threadIdx.x;
14
+ if (i < n) c[i] = a[i] + b[i];
15
+ }
16
+
17
+ template <int T>
18
+ __global__ void sgemm_tiled(const float* A, const float* B, float* C, int n) {
19
+ __shared__ float As[T][T], Bs[T][T];
20
+ int r = blockIdx.y * T + threadIdx.y, c = blockIdx.x * T + threadIdx.x;
21
+ float acc = 0.f;
22
+ for (int k0 = 0; k0 < n; k0 += T) {
23
+ As[threadIdx.y][threadIdx.x] = (r < n && k0 + threadIdx.x < n) ? A[r * n + k0 + threadIdx.x] : 0.f;
24
+ Bs[threadIdx.y][threadIdx.x] = (c < n && k0 + threadIdx.y < n) ? B[(k0 + threadIdx.y) * n + c] : 0.f;
25
+ __syncthreads();
26
+ for (int k = 0; k < T; ++k) acc += As[threadIdx.y][k] * Bs[k][threadIdx.x];
27
+ __syncthreads();
28
+ }
29
+ if (r < n && c < n) C[r * n + c] = acc;
30
+ }
31
+
32
+ static float median(std::vector<float> v) { std::sort(v.begin(), v.end()); return v[v.size() / 2]; }
33
+
34
+ int main(int argc, char** argv) {
35
+ int iters = argc > 1 ? std::atoi(argv[1]) : 20;
36
+ hipDeviceProp_t p; CHECK(hipGetDeviceProperties(&p, 0));
37
+ std::printf("DEVICE %s|%s\n", p.gcnArchName, p.name);
38
+ hipEvent_t s, e; CHECK(hipEventCreate(&s)); CHECK(hipEventCreate(&e));
39
+
40
+ // launch latency: empty-ish kernel on 1 element
41
+ {
42
+ float *d; CHECK(hipMalloc(&d, 3 * sizeof(float)));
43
+ std::vector<float> t;
44
+ for (int i = 0; i < iters * 5; ++i) {
45
+ CHECK(hipEventRecord(s)); vadd<<<1, 1>>>(d, d + 1, d + 2, 1); CHECK(hipEventRecord(e));
46
+ CHECK(hipEventSynchronize(e)); float ms; CHECK(hipEventElapsedTime(&ms, s, e)); t.push_back(ms);
47
+ }
48
+ std::printf("RESULT kernel_launch_latency us %f %d\n", median(t) * 1000.f, iters * 5);
49
+ hipFree(d);
50
+ }
51
+ // host<->device bandwidth (pinned)
52
+ {
53
+ size_t bytes = 256ull << 20; float *h, *d;
54
+ CHECK(hipHostMalloc(&h, bytes)); CHECK(hipMalloc(&d, bytes));
55
+ std::vector<float> th, td;
56
+ for (int i = 0; i < iters; ++i) {
57
+ CHECK(hipEventRecord(s)); CHECK(hipMemcpy(d, h, bytes, hipMemcpyHostToDevice)); CHECK(hipEventRecord(e));
58
+ CHECK(hipEventSynchronize(e)); float ms; CHECK(hipEventElapsedTime(&ms, s, e)); th.push_back(ms);
59
+ CHECK(hipEventRecord(s)); CHECK(hipMemcpy(h, d, bytes, hipMemcpyDeviceToHost)); CHECK(hipEventRecord(e));
60
+ CHECK(hipEventSynchronize(e)); CHECK(hipEventElapsedTime(&ms, s, e)); td.push_back(ms);
61
+ }
62
+ std::printf("RESULT h2d_bandwidth GB/s %f %d\n", bytes / (median(th) * 1e6), iters);
63
+ std::printf("RESULT d2h_bandwidth GB/s %f %d\n", bytes / (median(td) * 1e6), iters);
64
+ hipHostFree(h); hipFree(d);
65
+ }
66
+ // allocation latency
67
+ {
68
+ std::vector<float> t;
69
+ for (int i = 0; i < iters; ++i) {
70
+ void* d; auto t0 = std::chrono::high_resolution_clock::now();
71
+ CHECK(hipMalloc(&d, 64ull << 20)); CHECK(hipFree(d));
72
+ auto t1 = std::chrono::high_resolution_clock::now();
73
+ t.push_back(std::chrono::duration<float, std::micro>(t1 - t0).count());
74
+ }
75
+ std::printf("RESULT malloc_free_64MiB us %f %d\n", median(t), iters);
76
+ }
77
+ // vector add effective bandwidth
78
+ {
79
+ size_t n = 64ull << 20; float *a, *b, *c;
80
+ CHECK(hipMalloc(&a, n * 4)); CHECK(hipMalloc(&b, n * 4)); CHECK(hipMalloc(&c, n * 4));
81
+ CHECK(hipMemset(a, 0, n * 4)); CHECK(hipMemset(b, 0, n * 4));
82
+ std::vector<float> t;
83
+ for (int i = 0; i < iters; ++i) {
84
+ CHECK(hipEventRecord(s)); vadd<<<(n + 255) / 256, 256>>>(a, b, c, n); CHECK(hipEventRecord(e));
85
+ CHECK(hipEventSynchronize(e)); float ms; CHECK(hipEventElapsedTime(&ms, s, e)); t.push_back(ms);
86
+ }
87
+ std::printf("RESULT vector_add_bandwidth GB/s %f %d\n", 3.0 * n * 4 / (median(t) * 1e6), iters);
88
+ hipFree(a); hipFree(b); hipFree(c);
89
+ }
90
+ // tiled sgemm
91
+ {
92
+ int n = 2048; size_t bytes = (size_t)n * n * 4; float *A, *B, *C;
93
+ CHECK(hipMalloc(&A, bytes)); CHECK(hipMalloc(&B, bytes)); CHECK(hipMalloc(&C, bytes));
94
+ CHECK(hipMemset(A, 0, bytes)); CHECK(hipMemset(B, 0, bytes));
95
+ dim3 blk(16, 16), grd((n + 15) / 16, (n + 15) / 16);
96
+ sgemm_tiled<16><<<grd, blk>>>(A, B, C, n); CHECK(hipDeviceSynchronize());
97
+ std::vector<float> t;
98
+ for (int i = 0; i < std::max(3, iters / 4); ++i) {
99
+ CHECK(hipEventRecord(s)); sgemm_tiled<16><<<grd, blk>>>(A, B, C, n); CHECK(hipEventRecord(e));
100
+ CHECK(hipEventSynchronize(e)); float ms; CHECK(hipEventElapsedTime(&ms, s, e)); t.push_back(ms);
101
+ }
102
+ std::printf("RESULT sgemm_2048_tiled GFLOP/s %f %d\n", 2.0 * n * n * (double)n / (median(t) * 1e6), (int)t.size());
103
+ hipFree(A); hipFree(B); hipFree(C);
104
+ }
105
+ return 0;
106
+ }
107
+ """
108
+
109
+ TORCH_BENCH_SOURCE = r"""
110
+ import json, sys, time
111
+ iters = int(sys.argv[1]) if len(sys.argv) > 1 else 20
112
+ inference = len(sys.argv) > 2 and sys.argv[2] == "1"
113
+ out = {"results": [], "device": None}
114
+ try:
115
+ import torch
116
+ except Exception as exc:
117
+ print(json.dumps({"error": f"{type(exc).__name__}: {exc}"})); sys.exit(0)
118
+ if not torch.cuda.is_available():
119
+ print(json.dumps({"error": "torch.cuda.is_available() is False"})); sys.exit(0)
120
+ dev = torch.device("cuda")
121
+ out["device"] = torch.cuda.get_device_name(0)
122
+
123
+ def timed(fn, n):
124
+ for _ in range(3): fn()
125
+ torch.cuda.synchronize()
126
+ ts = []
127
+ for _ in range(n):
128
+ s = torch.cuda.Event(enable_timing=True); e = torch.cuda.Event(enable_timing=True)
129
+ s.record(); fn(); e.record(); torch.cuda.synchronize(); ts.append(s.elapsed_time(e))
130
+ ts.sort(); return ts[len(ts) // 2]
131
+
132
+ for dtype, name in ((torch.float32, "fp32"), (torch.float16, "fp16")):
133
+ n = 4096
134
+ a = torch.randn(n, n, device=dev, dtype=dtype); b = torch.randn(n, n, device=dev, dtype=dtype)
135
+ ms = timed(lambda: a @ b, iters)
136
+ out["results"].append({"name": f"matmul_{n}_{name}", "unit": "TFLOP/s", "value": 2 * n**3 / (ms * 1e9), "iterations": iters})
137
+ x = torch.randn(64 * 1024 * 1024, device=dev)
138
+ ms = timed(lambda: x * 2.0 + 1.0, iters)
139
+ out["results"].append({"name": "elementwise_bandwidth", "unit": "GB/s", "value": 2 * x.numel() * 4 / (ms * 1e6), "iterations": iters})
140
+ h = torch.randn(64 * 1024 * 1024 // 4, pin_memory=True)
141
+ ms = timed(lambda: h.to(dev, non_blocking=False), iters)
142
+ out["results"].append({"name": "h2d_tensor_copy", "unit": "GB/s", "value": h.numel() * 4 / (ms * 1e6), "iterations": iters})
143
+ if inference:
144
+ model = torch.nn.Sequential(torch.nn.Linear(1024, 4096), torch.nn.GELU(), torch.nn.Linear(4096, 1024)).to(dev).half().eval()
145
+ for bs in (1, 64):
146
+ inp = torch.randn(bs, 1024, device=dev, dtype=torch.float16)
147
+ with torch.inference_mode():
148
+ ms = timed(lambda: model(inp), iters)
149
+ out["results"].append({"name": f"mlp_inference_bs{bs}_latency", "unit": "ms", "value": ms, "iterations": iters,
150
+ "detail": "synthetic 2-layer MLP (1024-4096-1024, fp16), random weights"})
151
+ out["results"].append({"name": f"mlp_inference_bs{bs}_throughput", "unit": "samples/s", "value": bs / (ms / 1000), "iterations": iters})
152
+ print(json.dumps(out))
153
+ """
@@ -0,0 +1 @@
1
+
kernelvet/cli/app.py ADDED
@@ -0,0 +1,64 @@
1
+ """Typer application: the `kernelvet` command."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import typer
6
+
7
+ from kernelvet import __version__
8
+ from kernelvet.cli.commands import diagnose as diag
9
+ from kernelvet.cli.commands import migrate, misc
10
+ from kernelvet.models.report import DISCLAIMER, TRADEMARKS
11
+
12
+ EPILOG = (
13
+ "Exit codes: 0 healthy/passed · 1 failure found · 2 usage error · 3 review required "
14
+ "(warnings or unverified stages) · 4 required tool unavailable.\n\n" + DISCLAIMER + "\n\n" + TRADEMARKS
15
+ )
16
+
17
+ app = typer.Typer(
18
+ name="kernelvet",
19
+ help=(
20
+ "KernelVet — Diagnose. Migrate. Verify.\n\n"
21
+ "Unofficial open-source diagnostics and CUDA-to-HIP migration toolkit for AMD GPUs."
22
+ ),
23
+ epilog=EPILOG,
24
+ no_args_is_help=True,
25
+ rich_markup_mode="rich",
26
+ pretty_exceptions_show_locals=False,
27
+ context_settings={"help_option_names": ["-h", "--help"]},
28
+ )
29
+
30
+
31
+ def _version(value: bool) -> None:
32
+ if value:
33
+ print(f"kernelvet {__version__}")
34
+ raise typer.Exit()
35
+
36
+
37
+ @app.callback()
38
+ def main(
39
+ version: bool = typer.Option(
40
+ False, "--version", "-V", callback=_version, is_eager=True, help="Show the version and exit"
41
+ ),
42
+ ) -> None:
43
+ """KernelVet command-line interface."""
44
+
45
+
46
+ @app.command()
47
+ def tui() -> None:
48
+ """Launch the interactive terminal UI."""
49
+ from kernelvet.tui.app import KernelVetApp
50
+
51
+ KernelVetApp().run()
52
+
53
+
54
+ app.command("diagnose")(diag.diagnose)
55
+ app.command("doctor")(diag.doctor)
56
+ app.command("compatibility")(diag.compatibility)
57
+ app.command("benchmark")(misc.benchmark)
58
+ app.command("schema")(misc.schema)
59
+ app.command("history")(misc.history)
60
+ app.command("export")(misc.export)
61
+ app.add_typer(migrate.app, name="migrate")
62
+ app.add_typer(diag.gpu_app, name="gpu")
63
+ app.add_typer(diag.system_app, name="system")
64
+ app.add_typer(misc.config_app, name="config")
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,244 @@
1
+ """`kernelvet diagnose`, `doctor`, `compatibility`, `gpu list`, `system info`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+
7
+ import typer
8
+ from rich.table import Table
9
+ from rich.text import Text
10
+
11
+ from kernelvet.cli.output import (
12
+ FormatOpt,
13
+ OutputOpt,
14
+ emit,
15
+ err,
16
+ out,
17
+ progress,
18
+ resolve_format,
19
+ settings_or_exit,
20
+ write_json,
21
+ )
22
+ from kernelvet.compatibility.engine import evaluate
23
+ from kernelvet.compatibility.matrix import CompatibilityMatrix, MatrixError, load_matrix
24
+ from kernelvet.config import Settings
25
+ from kernelvet.diagnose.engine import DiagnoseOptions, collect_inventory, run_diagnosis
26
+ from kernelvet.history import HistoryError, HistoryStore
27
+ from kernelvet.models.common import CheckStatus, ExitCode
28
+ from kernelvet.models.report import DiagnosticReport
29
+ from kernelvet.reporting import OutputFormat
30
+ from kernelvet.reporting.terminal import (
31
+ OVERALL_STYLE,
32
+ gpu_table,
33
+ host_table,
34
+ render_compatibility,
35
+ render_diagnosis,
36
+ software_table,
37
+ status_text,
38
+ )
39
+ from kernelvet.utils.proc import HostContext
40
+
41
+
42
+ def _ctx(timeout: float) -> HostContext:
43
+ return HostContext(timeout=timeout)
44
+
45
+
46
+ def _matrix_error(exc: MatrixError) -> typer.Exit:
47
+ err.print(f"[red]compatibility matrix error:[/red] {exc}")
48
+ return typer.Exit(ExitCode.USAGE)
49
+
50
+
51
+ def _diagnose_or_exit(s: Settings, opts: DiagnoseOptions) -> DiagnosticReport:
52
+ try:
53
+ with progress() as cb:
54
+ return run_diagnosis(_ctx(s.command_timeout), opts, cb)
55
+ except MatrixError as exc:
56
+ raise _matrix_error(exc) from exc
57
+
58
+
59
+ def _matrix_or_exit(path: str | None) -> CompatibilityMatrix:
60
+ try:
61
+ return load_matrix(path)
62
+ except MatrixError as exc:
63
+ raise _matrix_error(exc) from exc
64
+
65
+
66
+ def _json_or_terminal(fmt: OutputFormat | None, json_out: bool) -> bool:
67
+ """`gpu list` and `system info` print a table or JSON; `--json` is kept as a shorthand for `-f json`."""
68
+ if fmt in (None, OutputFormat.TERMINAL):
69
+ return json_out
70
+ if fmt is OutputFormat.JSON:
71
+ return True
72
+ err.print(f"[red]{fmt.value} is not supported here; use terminal or json[/red]")
73
+ raise typer.Exit(ExitCode.USAGE)
74
+
75
+
76
+ def _record(report: DiagnosticReport, enabled: bool) -> None:
77
+ if not enabled:
78
+ return
79
+ counts = {s: sum(1 for c in report.all_checks() if c.status == s) for s in CheckStatus}
80
+ summary = ", ".join(f"{n} {s.value}" for s, n in counts.items() if n)
81
+ try:
82
+ HistoryStore().record_run("diagnosis", report.status.value, summary, report)
83
+ except HistoryError as exc: # history is best-effort: never lose the report over it
84
+ err.print(f"[yellow]could not record history: {exc}[/yellow]")
85
+
86
+
87
+ def diagnose(
88
+ fmt: OutputFormat | None = FormatOpt,
89
+ output: Path | None = OutputOpt,
90
+ runtime: bool = typer.Option(
91
+ True, "--runtime/--no-runtime", help="Compile and run the HIP probe on the GPU"
92
+ ),
93
+ torch: bool = typer.Option(True, "--torch/--no-torch", help="Detect PyTorch and run GPU tensor checks"),
94
+ python: str | None = typer.Option(None, help="Python interpreter to inspect for PyTorch"),
95
+ matrix: Path | None = typer.Option(
96
+ None, help="Custom compatibility matrix JSON", exists=True, dir_okay=False
97
+ ),
98
+ verbose: bool = typer.Option(False, "--verbose", "-v", help="Show check details"),
99
+ history: bool = typer.Option(True, "--history/--no-history", help="Record this run in local history"),
100
+ ) -> None:
101
+ """Inspect this machine: hardware, software, runtime execution and compatibility."""
102
+ s = settings_or_exit()
103
+ fmt = resolve_format(fmt, output)
104
+ opts = DiagnoseOptions(
105
+ runtime=runtime and s.runtime_checks,
106
+ torch=torch and s.torch_checks,
107
+ python=python or s.python_executable,
108
+ matrix_path=str(matrix) if matrix else s.compatibility_matrix,
109
+ )
110
+ report = _diagnose_or_exit(s, opts)
111
+ _record(report, history and s.history)
112
+ emit(report, fmt, output, lambda: render_diagnosis(report, verbose=verbose))
113
+ raise typer.Exit(ExitCode.for_status(report.status))
114
+
115
+
116
+ def doctor(
117
+ python: str | None = typer.Option(None, help="Python interpreter to inspect for PyTorch"),
118
+ runtime: bool = typer.Option(True, "--runtime/--no-runtime", help="Run GPU execution checks"),
119
+ ) -> None:
120
+ """Quick overall environment health check with the most important fixes."""
121
+ s = settings_or_exit()
122
+ opts = DiagnoseOptions(
123
+ runtime=runtime and s.runtime_checks,
124
+ torch=s.torch_checks,
125
+ python=python or s.python_executable,
126
+ matrix_path=s.compatibility_matrix,
127
+ )
128
+ report = _diagnose_or_exit(s, opts)
129
+ _record(report, s.history)
130
+ checks = report.all_checks()
131
+ counts = {st: sum(1 for c in checks if c.status == st) for st in CheckStatus}
132
+ out.print(Text("KernelVet", style="bold") + Text(" Diagnose. Migrate. Verify.", style="dim"))
133
+ host = report.host
134
+ amd = [g for g in report.gpus if g.vendor_is_amd]
135
+ out.print(f"Host: {host.os_pretty or host.os_name} · kernel {host.kernel} · {host.architecture}")
136
+ out.print(
137
+ f"GPUs: {', '.join(g.marketing_name or g.gfx_target or '?' for g in amd) or 'no AMD GPU detected'}"
138
+ )
139
+ out.print(f"ROCm: {report.software.rocm_version or 'not detected'}")
140
+ out.print(
141
+ "Checks: "
142
+ + " ".join(
143
+ f"[{('green', 'yellow', 'red', 'dim')[i]}]{counts[st]} {st.value}[/]"
144
+ for i, st in enumerate(
145
+ (CheckStatus.PASS, CheckStatus.WARNING, CheckStatus.FAIL, CheckStatus.SKIPPED)
146
+ )
147
+ )
148
+ )
149
+ problems = [c for c in checks if c.status in (CheckStatus.FAIL, CheckStatus.WARNING)]
150
+ if problems:
151
+ t = Table(title="Needs attention", title_justify="left", title_style="bold")
152
+ t.add_column("Check")
153
+ t.add_column("Status")
154
+ t.add_column("What to do")
155
+ for c in sorted(problems, key=lambda c: c.status != CheckStatus.FAIL)[:12]:
156
+ t.add_row(c.name, status_text(c.status), c.remediation or c.summary)
157
+ out.print(t)
158
+ executed = [c for c in checks if c.evidence == "executed" and c.status == CheckStatus.PASS]
159
+ out.print(
160
+ Text(
161
+ f"GPU execution verified: {'yes' if executed else 'no'}", style="green" if executed else "yellow"
162
+ )
163
+ )
164
+ out.print(Text(f"Overall Status: {report.status.value}", style=OVERALL_STYLE[report.status]))
165
+ out.print("[dim]Run `kernelvet diagnose -v` for full details.[/dim]")
166
+ raise typer.Exit(ExitCode.for_status(report.status))
167
+
168
+
169
+ def compatibility(
170
+ fmt: OutputFormat | None = FormatOpt,
171
+ output: Path | None = OutputOpt,
172
+ torch: bool = typer.Option(True, "--torch/--no-torch", help="Include PyTorch compatibility"),
173
+ python: str | None = typer.Option(None, help="Python interpreter to inspect for PyTorch"),
174
+ matrix: Path | None = typer.Option(
175
+ None, help="Custom compatibility matrix JSON", exists=True, dir_okay=False
176
+ ),
177
+ verbose: bool = typer.Option(False, "--verbose", "-v", help="Show check details"),
178
+ ) -> None:
179
+ """Validate this machine against AMD's published ROCm compatibility data (static, no GPU execution)."""
180
+ s = settings_or_exit()
181
+ fmt = resolve_format(fmt, output)
182
+ m = _matrix_or_exit(str(matrix) if matrix else s.compatibility_matrix)
183
+ with progress() as cb:
184
+ cb("Collecting inventory", 0.3)
185
+ host, gpus, sw = collect_inventory(
186
+ _ctx(s.command_timeout), torch=torch and s.torch_checks, python=python or s.python_executable
187
+ )
188
+ cb("Evaluating matrix", 0.8)
189
+ report = evaluate(host, gpus, sw, m)
190
+ emit(report, fmt, output, lambda: render_compatibility(report, verbose=verbose))
191
+ raise typer.Exit(ExitCode.for_status(report.status))
192
+
193
+
194
+ ListFormatOpt = typer.Option(None, "--format", "-f", help="terminal or json", case_sensitive=False)
195
+
196
+ gpu_app = typer.Typer(help="GPU device commands.", no_args_is_help=True)
197
+ system_app = typer.Typer(help="Host system commands.", no_args_is_help=True)
198
+
199
+
200
+ @gpu_app.command("list")
201
+ def gpu_list(
202
+ fmt: OutputFormat | None = ListFormatOpt,
203
+ json_out: bool = typer.Option(False, "--json", help="Same as --format json"),
204
+ ) -> None:
205
+ """List GPUs detected by amd-smi, rocminfo and /sys (static detection)."""
206
+ as_json = _json_or_terminal(fmt, json_out)
207
+ s = settings_or_exit()
208
+ _host, gpus, _sw = collect_inventory(_ctx(s.command_timeout))
209
+ if as_json:
210
+ write_json([g.model_dump() for g in gpus])
211
+ else:
212
+ out.print(gpu_table(gpus))
213
+ raise typer.Exit(ExitCode.OK if any(g.vendor_is_amd for g in gpus) else ExitCode.FAILURE)
214
+
215
+
216
+ @system_app.command("info")
217
+ def system_info(
218
+ fmt: OutputFormat | None = ListFormatOpt,
219
+ json_out: bool = typer.Option(False, "--json", help="Same as --format json"),
220
+ torch: bool = typer.Option(False, "--torch", help="Also inspect PyTorch"),
221
+ python: str | None = typer.Option(None, help="Python interpreter to inspect for PyTorch (with --torch)"),
222
+ ) -> None:
223
+ """Show OS, kernel, ROCm, HIP, driver and tool versions (static detection)."""
224
+ as_json = _json_or_terminal(fmt, json_out)
225
+ s = settings_or_exit()
226
+ host, _gpus, sw = collect_inventory(
227
+ _ctx(s.command_timeout), torch=torch, python=python or s.python_executable
228
+ )
229
+ if as_json:
230
+ write_json({"host": host.model_dump(), "software": sw.model_dump()})
231
+ return
232
+ out.print(host_table(host))
233
+ out.print(software_table(sw))
234
+ t = Table(title="Tools", title_justify="left", title_style="bold")
235
+ for col in ("Tool", "Available", "Version", "Path"):
236
+ t.add_column(col)
237
+ for tool in sw.tools:
238
+ t.add_row(
239
+ tool.name,
240
+ Text("yes", style="green") if tool.available else Text("no", style="dim"),
241
+ tool.version or "",
242
+ tool.path or "",
243
+ )
244
+ out.print(t)