kernelvet 0.1.0__tar.gz

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 (105) hide show
  1. kernelvet-0.1.0/.gitignore +36 -0
  2. kernelvet-0.1.0/LICENSE +197 -0
  3. kernelvet-0.1.0/PKG-INFO +275 -0
  4. kernelvet-0.1.0/README.md +241 -0
  5. kernelvet-0.1.0/docs/architecture.md +80 -0
  6. kernelvet-0.1.0/examples/README.md +48 -0
  7. kernelvet-0.1.0/examples/config.toml +28 -0
  8. kernelvet-0.1.0/pyproject.toml +91 -0
  9. kernelvet-0.1.0/src/kernelvet/__init__.py +10 -0
  10. kernelvet-0.1.0/src/kernelvet/__main__.py +3 -0
  11. kernelvet-0.1.0/src/kernelvet/benchmark/__init__.py +1 -0
  12. kernelvet-0.1.0/src/kernelvet/benchmark/engine.py +180 -0
  13. kernelvet-0.1.0/src/kernelvet/benchmark/workloads.py +153 -0
  14. kernelvet-0.1.0/src/kernelvet/cli/__init__.py +1 -0
  15. kernelvet-0.1.0/src/kernelvet/cli/app.py +64 -0
  16. kernelvet-0.1.0/src/kernelvet/cli/commands/__init__.py +1 -0
  17. kernelvet-0.1.0/src/kernelvet/cli/commands/diagnose.py +244 -0
  18. kernelvet-0.1.0/src/kernelvet/cli/commands/migrate.py +334 -0
  19. kernelvet-0.1.0/src/kernelvet/cli/commands/misc.py +216 -0
  20. kernelvet-0.1.0/src/kernelvet/cli/output.py +110 -0
  21. kernelvet-0.1.0/src/kernelvet/compatibility/__init__.py +1 -0
  22. kernelvet-0.1.0/src/kernelvet/compatibility/data/rocm_matrix.json +123 -0
  23. kernelvet-0.1.0/src/kernelvet/compatibility/engine.py +24 -0
  24. kernelvet-0.1.0/src/kernelvet/compatibility/matrix.py +128 -0
  25. kernelvet-0.1.0/src/kernelvet/compatibility/validators.py +405 -0
  26. kernelvet-0.1.0/src/kernelvet/config/__init__.py +10 -0
  27. kernelvet-0.1.0/src/kernelvet/config/settings.py +112 -0
  28. kernelvet-0.1.0/src/kernelvet/diagnose/__init__.py +1 -0
  29. kernelvet-0.1.0/src/kernelvet/diagnose/engine.py +296 -0
  30. kernelvet-0.1.0/src/kernelvet/diagnose/hardware.py +336 -0
  31. kernelvet-0.1.0/src/kernelvet/diagnose/runtime.py +332 -0
  32. kernelvet-0.1.0/src/kernelvet/diagnose/software.py +221 -0
  33. kernelvet-0.1.0/src/kernelvet/diagnose/system.py +67 -0
  34. kernelvet-0.1.0/src/kernelvet/execution/__init__.py +1 -0
  35. kernelvet-0.1.0/src/kernelvet/execution/compiler.py +275 -0
  36. kernelvet-0.1.0/src/kernelvet/execution/runner.py +125 -0
  37. kernelvet-0.1.0/src/kernelvet/execution/sandbox.py +51 -0
  38. kernelvet-0.1.0/src/kernelvet/history/__init__.py +3 -0
  39. kernelvet-0.1.0/src/kernelvet/history/store.py +157 -0
  40. kernelvet-0.1.0/src/kernelvet/main.py +19 -0
  41. kernelvet-0.1.0/src/kernelvet/migration/__init__.py +17 -0
  42. kernelvet-0.1.0/src/kernelvet/migration/analyzer.py +78 -0
  43. kernelvet-0.1.0/src/kernelvet/migration/auditor.py +89 -0
  44. kernelvet-0.1.0/src/kernelvet/migration/hipify.py +268 -0
  45. kernelvet-0.1.0/src/kernelvet/migration/planner.py +128 -0
  46. kernelvet-0.1.0/src/kernelvet/migration/rules.py +564 -0
  47. kernelvet-0.1.0/src/kernelvet/migration/scanner.py +234 -0
  48. kernelvet-0.1.0/src/kernelvet/migration/workflow.py +135 -0
  49. kernelvet-0.1.0/src/kernelvet/models/__init__.py +35 -0
  50. kernelvet-0.1.0/src/kernelvet/models/common.py +102 -0
  51. kernelvet-0.1.0/src/kernelvet/models/migration.py +236 -0
  52. kernelvet-0.1.0/src/kernelvet/models/report.py +126 -0
  53. kernelvet-0.1.0/src/kernelvet/models/system.py +89 -0
  54. kernelvet-0.1.0/src/kernelvet/reporting/__init__.py +80 -0
  55. kernelvet-0.1.0/src/kernelvet/reporting/common.py +74 -0
  56. kernelvet-0.1.0/src/kernelvet/reporting/html.py +149 -0
  57. kernelvet-0.1.0/src/kernelvet/reporting/json.py +20 -0
  58. kernelvet-0.1.0/src/kernelvet/reporting/loader.py +48 -0
  59. kernelvet-0.1.0/src/kernelvet/reporting/markdown.py +256 -0
  60. kernelvet-0.1.0/src/kernelvet/reporting/sarif.py +79 -0
  61. kernelvet-0.1.0/src/kernelvet/reporting/terminal.py +276 -0
  62. kernelvet-0.1.0/src/kernelvet/tui/__init__.py +1 -0
  63. kernelvet-0.1.0/src/kernelvet/tui/app.py +177 -0
  64. kernelvet-0.1.0/src/kernelvet/tui/screens/__init__.py +1 -0
  65. kernelvet-0.1.0/src/kernelvet/tui/screens/base.py +34 -0
  66. kernelvet-0.1.0/src/kernelvet/tui/screens/devices.py +211 -0
  67. kernelvet-0.1.0/src/kernelvet/tui/screens/diagnose.py +212 -0
  68. kernelvet-0.1.0/src/kernelvet/tui/screens/help.py +47 -0
  69. kernelvet-0.1.0/src/kernelvet/tui/screens/migration.py +573 -0
  70. kernelvet-0.1.0/src/kernelvet/tui/screens/overview.py +195 -0
  71. kernelvet-0.1.0/src/kernelvet/tui/screens/tools.py +357 -0
  72. kernelvet-0.1.0/src/kernelvet/tui/state.py +55 -0
  73. kernelvet-0.1.0/src/kernelvet/tui/widgets/__init__.py +1 -0
  74. kernelvet-0.1.0/src/kernelvet/tui/widgets/common.py +82 -0
  75. kernelvet-0.1.0/src/kernelvet/tui/workers/__init__.py +25 -0
  76. kernelvet-0.1.0/src/kernelvet/utils/__init__.py +1 -0
  77. kernelvet-0.1.0/src/kernelvet/utils/paths.py +48 -0
  78. kernelvet-0.1.0/src/kernelvet/utils/proc.py +178 -0
  79. kernelvet-0.1.0/src/kernelvet/utils/redact.py +47 -0
  80. kernelvet-0.1.0/src/kernelvet/utils/versions.py +34 -0
  81. kernelvet-0.1.0/tests/conftest.py +250 -0
  82. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/CMakeLists.txt +16 -0
  83. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/Makefile +12 -0
  84. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/README.md +3 -0
  85. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/include/common.cuh +27 -0
  86. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/src/gemm.cpp +28 -0
  87. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/src/reduce.cu +46 -0
  88. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/src/vector_add.cu +25 -0
  89. kernelvet-0.1.0/tests/fixtures/cuda/vector_project/tests/test_vector_add.cu +17 -0
  90. kernelvet-0.1.0/tests/fixtures/hip/partial_migration/CMakeLists.txt +5 -0
  91. kernelvet-0.1.0/tests/fixtures/hip/partial_migration/src/main.hip +26 -0
  92. kernelvet-0.1.0/tests/fixtures/host/README.md +6 -0
  93. kernelvet-0.1.0/tests/fixtures/host/mi300x/amd-smi-static.json +28 -0
  94. kernelvet-0.1.0/tests/fixtures/host/mi300x/hipcc-version.txt +5 -0
  95. kernelvet-0.1.0/tests/fixtures/host/mi300x/os-release +6 -0
  96. kernelvet-0.1.0/tests/fixtures/host/mi300x/rocminfo.txt +79 -0
  97. kernelvet-0.1.0/tests/integration/test_cli.py +404 -0
  98. kernelvet-0.1.0/tests/integration/test_real_tools.py +48 -0
  99. kernelvet-0.1.0/tests/integration/test_tui.py +341 -0
  100. kernelvet-0.1.0/tests/unit/test_compatibility.py +208 -0
  101. kernelvet-0.1.0/tests/unit/test_diagnose.py +240 -0
  102. kernelvet-0.1.0/tests/unit/test_execution.py +202 -0
  103. kernelvet-0.1.0/tests/unit/test_migration.py +305 -0
  104. kernelvet-0.1.0/tests/unit/test_reporting.py +159 -0
  105. kernelvet-0.1.0/tests/unit/test_utils.py +121 -0
@@ -0,0 +1,36 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv/
6
+ venv/
7
+ build/
8
+ dist/
9
+ .pytest_cache/
10
+ .mypy_cache/
11
+ .ruff_cache/
12
+ .coverage
13
+ htmlcov/
14
+
15
+ # KernelVet local output
16
+ .scratch-*/
17
+ *-hip/
18
+ /reports/
19
+
20
+ # Environment / secrets
21
+ .env
22
+ .env.*
23
+ *.pem
24
+ *.key
25
+
26
+ # Logs
27
+ *.log
28
+
29
+ # OS / editors
30
+ .DS_Store
31
+ .idea/
32
+ .vscode/
33
+ *.swp
34
+
35
+ # Personal AI-tool config
36
+ opencode.json
@@ -0,0 +1,197 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, made available under
32
+ the License, as indicated by a copyright notice that is included in
33
+ or attached to the work (an example is provided in the Appendix below).
34
+
35
+ "Derivative Works" shall mean any work, whether in Source or Object
36
+ form, that is based on (or derived from) the Work and for which the
37
+ editorial revisions, annotations, elaborations, or other modifications
38
+ represent, as a whole, an original work of authorship. For the purposes
39
+ of this License, Derivative Works shall not include works that remain
40
+ separable from, or merely link (or bind by name) to the interfaces of,
41
+ the Work and Derivative Works thereof.
42
+
43
+ "Contribution" shall mean any work of authorship, including
44
+ the original version of the Work and any modifications or additions
45
+ to that Work or Derivative Works thereof, that is intentionally
46
+ submitted to Licensor for inclusion in the Work by the copyright owner
47
+ or by an individual or Legal Entity authorized to submit on behalf of
48
+ the copyright owner. For the purposes of this definition, "submitted"
49
+ means any form of electronic, verbal, or written communication sent
50
+ to the Licensor or its representatives, including but not limited to
51
+ communication on electronic mailing lists, source code control systems,
52
+ and issue tracking systems that are managed by, or on behalf of, the
53
+ Licensor for the purpose of discussing and improving the Work, but
54
+ excluding communication that is conspicuously marked or otherwise
55
+ designated in writing by the copyright owner as "Not a Contribution."
56
+
57
+ "Contributor" shall mean Licensor and any individual or Legal Entity
58
+ on behalf of whom a Contribution has been received by Licensor and
59
+ subsequently incorporated within the Work.
60
+
61
+ 2. Grant of Copyright License. Subject to the terms and conditions of
62
+ this License, each Contributor hereby grants to You a perpetual,
63
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
64
+ copyright license to reproduce, prepare Derivative Works of,
65
+ publicly display, publicly perform, sublicense, and distribute the
66
+ Work and such Derivative Works in Source or Object form.
67
+
68
+ 3. Grant of Patent License. Subject to the terms and conditions of
69
+ this License, each Contributor hereby grants to You a perpetual,
70
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
71
+ (except as stated in this section) patent license to make, have made,
72
+ use, offer to sell, sell, import, and otherwise transfer the Work,
73
+ where such license applies only to those patent claims licensable
74
+ by such Contributor that are necessarily infringed by their
75
+ Contribution(s) alone or by combination of their Contribution(s)
76
+ with the Work to which such Contribution(s) was submitted. If You
77
+ institute patent litigation against any entity (including a
78
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
79
+ or a Contribution incorporated within the Work constitutes direct
80
+ or contributory patent infringement, then any patent licenses
81
+ granted to You under this License for that Work shall terminate
82
+ as of the date such litigation is filed.
83
+
84
+ 4. Redistribution. You may reproduce and distribute copies of the
85
+ Work or Derivative Works thereof in any medium, with or without
86
+ modifications, and in Source or Object form, provided that You
87
+ meet the following conditions:
88
+
89
+ (a) You must give any other recipients of the Work or
90
+ Derivative Works a copy of this License; and
91
+
92
+ (b) You must cause any modified files to carry prominent notices
93
+ stating that You changed the files; and
94
+
95
+ (c) You must retain, in the Source form of any Derivative Works
96
+ that You distribute, all copyright, patent, trademark, and
97
+ attribution notices from the Source form of the Work,
98
+ excluding those notices that do not pertain to any part of
99
+ the Derivative Works; and
100
+
101
+ (d) If the Work includes a "NOTICE" text file as part of its
102
+ distribution, then any Derivative Works that You distribute must
103
+ include a readable copy of the attribution notices contained
104
+ within such NOTICE file, excluding those notices that do not
105
+ pertain to any part of the Derivative Works, in at least one
106
+ of the following places: within a NOTICE text file distributed
107
+ as part of the Derivative Works; within the Source form or
108
+ documentation, if provided along with the Derivative Works; or,
109
+ within a display generated by the Derivative Works, if and
110
+ wherever such third-party notices normally appear. The contents
111
+ of the NOTICE file are for informational purposes only and
112
+ do not modify the License. You may add Your own attribution
113
+ notices within Derivative Works that You distribute, alongside
114
+ or as an addendum to the NOTICE text from the Work, provided
115
+ that such additional attribution notices cannot be construed
116
+ as modifying the License.
117
+
118
+ You may add Your own copyright statement to Your modifications and
119
+ may provide additional or different license terms and conditions
120
+ for use, reproduction, or distribution of Your modifications, or
121
+ for any such Derivative Works as a whole, provided Your use,
122
+ reproduction, and distribution of the Work otherwise complies with
123
+ the conditions stated in this License.
124
+
125
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
126
+ any Contribution intentionally submitted for inclusion in the Work
127
+ by You to the Licensor shall be under the terms and conditions of
128
+ this License, without any additional terms or conditions.
129
+ Notwithstanding the above, nothing herein shall supersede or modify
130
+ the terms of any separate license agreement you may have executed
131
+ with Licensor regarding such Contributions.
132
+
133
+ 6. Trademarks. This License does not grant permission to use the trade
134
+ names, trademarks, service marks, or product names of the Licensor,
135
+ except as required for reasonable and customary use in describing the
136
+ origin of the Work and reproducing the content of the NOTICE file.
137
+
138
+ 7. Disclaimer of Warranty. Unless required by applicable law or
139
+ agreed to in writing, Licensor provides the Work (and each
140
+ Contributor provides its Contributions) on an "AS IS" BASIS,
141
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
142
+ implied, including, without limitation, any warranties and
143
+ conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
144
+ FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
145
+ determining the appropriateness of using or redistributing the Work
146
+ and assume any risks associated with Your exercise of permissions
147
+ under this License.
148
+
149
+ 8. Limitation of Liability. In no event and under no legal theory,
150
+ whether in tort (including negligence), contract, or otherwise,
151
+ unless required by applicable law (such as deliberate and grossly
152
+ negligent acts) or agreed to in writing, shall any Contributor be
153
+ liable to You for damages, including any direct, indirect, special,
154
+ incidental, or consequential damages of any character arising as a
155
+ result of this License or out of the use or inability to use the
156
+ Work (including but not limited to damages for loss of goodwill,
157
+ work stoppage, computer failure or malfunction, or any and all
158
+ other commercial damages or losses), even if such Contributor
159
+ has been advised of the possibility of such damages.
160
+
161
+ 9. Accepting Warranty or Additional Liability. While redistributing
162
+ the Work or Derivative Works thereof, You may choose to offer,
163
+ and charge a fee for, acceptance of support, warranty, indemnity,
164
+ or other liability obligations and/or rights consistent with this
165
+ License. However, in accepting such obligations, You may act only
166
+ on Your own behalf and on Your sole responsibility, not on behalf
167
+ of any other Contributor, and only if You agree to indemnify,
168
+ defend, and hold each Contributor harmless for any liability
169
+ incurred by, or claims asserted against, such Contributor by reason
170
+ of your accepting any such warranty or additional liability.
171
+
172
+ END OF TERMS AND CONDITIONS
173
+
174
+ APPENDIX: How to apply the Apache License to your work.
175
+
176
+ To apply the Apache License to your work, attach the following
177
+ boilerplate notice, with the fields enclosed by brackets "[]"
178
+ replaced with your own identifying information. (Don't include
179
+ the brackets!) The text should be enclosed in the appropriate
180
+ comment syntax for the file format. We also recommend that a
181
+ file or class name and description of purpose be included on the
182
+ same "printed page" as the copyright notice for easier
183
+ identification within third-party archives.
184
+
185
+ Copyright 2026 KernelVet contributors
186
+
187
+ Licensed under the Apache License, Version 2.0 (the "License");
188
+ you may not use this file except in compliance with the License.
189
+ You may obtain a copy of the License at
190
+
191
+ http://www.apache.org/licenses/LICENSE-2.0
192
+
193
+ Unless required by applicable law or agreed to in writing, software
194
+ distributed under the License is distributed on an "AS IS" BASIS,
195
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
196
+ See the License for the specific language governing permissions and
197
+ limitations under the License.
@@ -0,0 +1,275 @@
1
+ Metadata-Version: 2.5
2
+ Name: kernelvet
3
+ Version: 0.1.0
4
+ Summary: Unofficial open-source diagnostics and CUDA-to-HIP migration toolkit for AMD GPUs. Not affiliated with AMD.
5
+ Project-URL: Homepage, https://github.com/seyhunak/kernelvet
6
+ Project-URL: Issues, https://github.com/seyhunak/kernelvet/issues
7
+ Author: KernelVet contributors
8
+ License-Expression: Apache-2.0
9
+ License-File: LICENSE
10
+ Keywords: amd,cuda,diagnostics,gpu,hip,hipify,rocm,tui
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Build Tools
20
+ Classifier: Topic :: System :: Hardware
21
+ Requires-Python: >=3.11
22
+ Requires-Dist: pydantic>=2.7
23
+ Requires-Dist: rich>=13.7
24
+ Requires-Dist: textual>=0.80
25
+ Requires-Dist: typer>=0.12
26
+ Provides-Extra: dev
27
+ Requires-Dist: build>=1.2; extra == 'dev'
28
+ Requires-Dist: jsonschema>=4.21; extra == 'dev'
29
+ Requires-Dist: mypy>=1.10; extra == 'dev'
30
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
31
+ Requires-Dist: pytest>=8; extra == 'dev'
32
+ Requires-Dist: ruff>=0.6; extra == 'dev'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # KernelVet
36
+
37
+ [![CI](https://github.com/seyhunak/kernelvet/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/seyhunak/kernelvet/actions/workflows/ci.yml)
38
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/seyhunak/kernelvet/blob/main/LICENSE)
39
+ [![Python 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://github.com/seyhunak/kernelvet/blob/main/pyproject.toml)
40
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
41
+ [![Checked with mypy](https://img.shields.io/badge/mypy-checked-2a6db2.svg)](https://mypy-lang.org/)
42
+ [![Platform: Linux + ROCm](https://img.shields.io/badge/platform-Linux%20%2B%20ROCm-555555.svg)](https://rocm.docs.amd.com/)
43
+ [![Last commit](https://img.shields.io/github/last-commit/seyhunak/kernelvet/main.svg)](https://github.com/seyhunak/kernelvet/commits/main)
44
+
45
+ **Diagnose. Migrate. Verify.**
46
+
47
+ KernelVet is an open-source, terminal-native toolkit for AMD GPU developers. It
48
+ checks whether a machine can really run ROCm workloads, and helps move CUDA
49
+ projects to HIP using AMD's own tools. A command-line interface (`kernelvet`) and
50
+ a keyboard-driven terminal UI (`kernelvet tui`) share one engine.
51
+
52
+ > KernelVet is an independent open-source community project. It is **not
53
+ > affiliated with, sponsored by or endorsed by AMD**, is not an AMD product, and is
54
+ > not a certification authority. Always confirm support questions against the
55
+ > live [AMD ROCm documentation](https://rocm.docs.amd.com/). See
56
+ > [Disclaimer and trademarks](#disclaimer-and-trademarks).
57
+
58
+ ## What it does
59
+
60
+ | Area | What you get |
61
+ | --- | --- |
62
+ | **Diagnose** | Detects the OS, kernel, GPUs (`amd-smi`, `rocminfo`, sysfs), ROCm, the HIP compiler, the `amdgpu` driver, ROCm libraries and PyTorch. Then it **compiles and runs** a small HIP program on each GPU and runs real PyTorch tensor operations. |
63
+ | **Compatibility** | Checks the host against a dated snapshot of AMD's published compatibility data. Each check names the page its data came from. |
64
+ | **Migrate** | Scans a CUDA project, classifies every CUDA construct, scores readiness, plans the migration, converts it with **AMD HIPIFY** into a separate directory, audits the result, builds it with `hipcc` and runs its tests. |
65
+ | **Benchmark** | Times a HIP bandwidth kernel and PyTorch matmuls on the GPU. `--profile` runs the HIP benchmark under `rocprofv3`; its output is saved to `--profile-dir`, or by default to `profiles/<timestamp>` in the data directory. Results come only from real runs. |
66
+ | **Report** | Writes terminal, JSON, Markdown, self-contained HTML and SARIF (for findings). |
67
+ | **TUI** | Eight sections: Overview, Diagnose, GPU Devices, Compatibility, CUDA→HIP Migration, Benchmarks, Reports, Settings. Long tasks run in background workers. |
68
+
69
+ ## The honesty rules
70
+
71
+ KernelVet is built to never claim more than it observed.
72
+
73
+ * Every check is **PASS**, **WARNING**, **FAIL** or **SKIPPED**.
74
+ * Every check also records *how* it knows its result: `detected` (static
75
+ inspection), `executed` (code ran on the device), `configured`, or `none`.
76
+ * If a tool is missing or there is no GPU, the check is **SKIPPED** and says why.
77
+ It is never reported as PASS.
78
+ * The overall status is:
79
+ * **UNHEALTHY** if any check fails.
80
+ * **REVIEW REQUIRED** if anything is a warning or was skipped.
81
+ * **HEALTHY** only if every check passed.
82
+ * A CUDA migration goes through five separate verification stages:
83
+ 1. static conversion
84
+ 2. static audit
85
+ 3. compilation
86
+ 4. tests
87
+ 5. GPU validation
88
+
89
+ Passing one stage is never shown as passing a later one.
90
+ * GPU validation passes only when the tests passed **and** at least one test ran
91
+ on a detected AMD GPU. On a CPU-only machine it is reported as **UNAVAILABLE**.
92
+ * Benchmarks are never estimated or simulated.
93
+
94
+ ## Install
95
+
96
+ You need Python 3.11 or newer. The tool itself runs anywhere, including
97
+ CPU-only machines and macOS. On those machines the GPU checks simply report
98
+ SKIPPED or UNAVAILABLE.
99
+
100
+ ```bash
101
+ pip install kernelvet
102
+ ```
103
+
104
+ The latest `main`, before it is released:
105
+
106
+ ```bash
107
+ pip install "git+https://github.com/seyhunak/kernelvet.git"
108
+ ```
109
+
110
+ From a checkout:
111
+
112
+ ```bash
113
+ pip install -e ".[dev]"
114
+ ```
115
+
116
+ KernelVet calls AMD's tools; it does not bundle them. Install whichever you
117
+ need from ROCm:
118
+
119
+ * `rocminfo` and `amd-smi`: detection
120
+ * `hipcc`: the runtime probe, builds and benchmarks
121
+ * `hipify-clang` or `hipify-perl`: conversion
122
+ * `rocprofv3`: profiling
123
+
124
+ You never need root to run KernelVet.
125
+
126
+ ## Quick start
127
+
128
+ ```bash
129
+ kernelvet doctor # short health summary with the top fixes
130
+ kernelvet diagnose -v # every check, with details
131
+ kernelvet diagnose --format json > diagnosis.json
132
+ kernelvet diagnose -o report.html # format inferred from the extension
133
+ kernelvet compatibility # static check against AMD's published data
134
+ kernelvet gpu list
135
+ kernelvet system info --torch
136
+ kernelvet tui
137
+ ```
138
+
139
+ ### Migrating a CUDA project
140
+
141
+ ```bash
142
+ kernelvet migrate analyze ./my-cuda-app # read-only classification + readiness score
143
+ kernelvet migrate plan ./my-cuda-app # dry run: what will happen, file by file
144
+ kernelvet migrate convert ./my-cuda-app -o ./my-cuda-app-hip
145
+ kernelvet migrate audit ./my-cuda-app-hip # leftover CUDA, risky patterns, file:line
146
+ kernelvet migrate build ./my-cuda-app-hip
147
+ kernelvet migrate test ./my-cuda-app-hip
148
+ kernelvet migrate report ./my-cuda-app-hip --format sarif -o findings.sarif
149
+ ```
150
+
151
+ The analyzer sorts every finding into one of four categories:
152
+
153
+ * `AUTO_CONVERTIBLE`
154
+ * `REQUIRES_VERIFICATION`
155
+ * `MANUAL_INTERVENTION`
156
+ * `UNSUPPORTED`
157
+
158
+ `convert` never modifies the CUDA project. It refuses an output directory that:
159
+
160
+ * is the source directory,
161
+ * is inside the source, or
162
+ * contains the source.
163
+
164
+ It also refuses a non-empty output directory unless you pass `--force`. Each
165
+ stage saves its state in `<hip-project>/.kernelvet/`, so later stages and
166
+ `report` can pick it up. This includes the full HIPIFY log in `conversion.log`.
167
+
168
+ `build` and `test` can run inside Docker:
169
+
170
+ ```bash
171
+ kernelvet config set isolation docker
172
+ ```
173
+
174
+ The container has no network and drops every Linux capability.
175
+ `/dev/kfd` and `/dev/dri` are passed through only for GPU runs.
176
+
177
+ ## Output and exit codes
178
+
179
+ * With `--format json`, stdout contains **only** the JSON document. Progress
180
+ goes to stderr, so piping into `jq` is safe.
181
+ * `kernelvet schema diagnosis|compatibility|migration|benchmark` prints the JSON
182
+ Schema of each report type.
183
+
184
+ | Exit code | Meaning |
185
+ | --- | --- |
186
+ | 0 | Healthy / stage passed |
187
+ | 1 | A failure was found |
188
+ | 2 | Usage error |
189
+ | 3 | Review required (warnings, skipped checks or unverified stages) |
190
+ | 4 | A required tool is unavailable (e.g. no HIPIFY installed) |
191
+ | 70 | Internal error |
192
+
193
+ ## Configuration
194
+
195
+ `kernelvet config show` prints the effective configuration. Settings are
196
+ resolved in this order:
197
+
198
+ 1. the defaults,
199
+ 2. the config file (`kernelvet config path`, usually
200
+ `~/.config/kernelvet/config.toml`),
201
+ 3. `KERNELVET_<FIELD>` environment variables.
202
+
203
+ `kernelvet config set KEY VALUE` changes one setting, for example
204
+ `kernelvet config set isolation docker`. An empty value resets the setting to
205
+ its default (`kernelvet config set isolation ""`). `none` clears a setting that
206
+ can be left unset, such as `offload_arch`.
207
+
208
+ `KERNELVET_CONFIG_DIR` and `KERNELVET_DATA_DIR` move the config and data
209
+ directories. History (SQLite) and saved reports live in the data directory.
210
+ Turn history off with `history = false`.
211
+
212
+ See [`examples/config.toml`](https://github.com/seyhunak/kernelvet/blob/main/examples/config.toml) for every option.
213
+
214
+ ## Compatibility data
215
+
216
+ The bundled matrix is
217
+ [`src/kernelvet/compatibility/data/rocm_matrix.json`](https://github.com/seyhunak/kernelvet/blob/main/src/kernelvet/compatibility/data/rocm_matrix.json).
218
+
219
+ * It was transcribed by hand from AMD's system-requirements page,
220
+ compatibility-matrix page and release-history page.
221
+ * It records the ROCm version (10.1.0), the date it was retrieved, and every
222
+ source URL.
223
+ * AMD's pages sometimes disagree with each other. Those conflicts are written
224
+ into the file's `notes` instead of being resolved silently.
225
+ * A value earns PASS only if AMD lists it explicitly. Unlisted values are
226
+ WARNING, and known incompatibilities are FAIL.
227
+
228
+ To use your own matrix, pass `--matrix FILE` or set `compatibility_matrix`.
229
+
230
+ ## What has and has not been verified
231
+
232
+ The test suite runs on CPU-only machines:
233
+
234
+ * It replays recorded command output through a fake command runner.
235
+ * It builds fake filesystem roots (`/sys`, `/opt/rocm`, `/etc/os-release`) for
236
+ each test.
237
+ * The host fixtures in `tests/fixtures/host/` were **constructed** to match the
238
+ documented output formats. They were not recorded on real hardware; see
239
+ [`tests/fixtures/host/README.md`](https://github.com/seyhunak/kernelvet/blob/main/tests/fixtures/host/README.md).
240
+
241
+ The tests in `tests/integration/test_real_tools.py` are **skipped** unless the
242
+ real tools are present. They are marked `hipify` (HIPIFY installed) and `gpu`
243
+ (AMD GPU present). Run them on a ROCm machine with:
244
+
245
+ ```bash
246
+ pytest -m "gpu or hipify"
247
+ ```
248
+
249
+ Bug reports with real `rocminfo` / `amd-smi` output are very welcome.
250
+
251
+ ## Documentation
252
+
253
+ * [Architecture](https://github.com/seyhunak/kernelvet/blob/main/docs/architecture.md)
254
+ * [Contributing](https://github.com/seyhunak/kernelvet/blob/main/CONTRIBUTING.md)
255
+ * [Security policy](https://github.com/seyhunak/kernelvet/blob/main/SECURITY.md)
256
+ * [Code of Conduct](https://github.com/seyhunak/kernelvet/blob/main/CODE_OF_CONDUCT.md)
257
+ * [Notes for AI coding agents](https://github.com/seyhunak/kernelvet/blob/main/AGENTS.md)
258
+
259
+ ## License
260
+
261
+ Apache License 2.0. See [LICENSE](https://github.com/seyhunak/kernelvet/blob/main/LICENSE).
262
+
263
+ ## Disclaimer and trademarks
264
+
265
+ KernelVet is an independent, community-maintained open-source project. It is
266
+ not affiliated with, sponsored by, or endorsed by Advanced Micro Devices, Inc.
267
+ (AMD), and it is not an AMD product. Its results are not an official AMD
268
+ statement of support or certification. For authoritative information, use the
269
+ [AMD ROCm documentation](https://rocm.docs.amd.com/).
270
+
271
+ AMD, AMD ROCm, AMD Instinct, AMD CDNA, AMD RDNA and Radeon are trademarks of
272
+ Advanced Micro Devices, Inc. CUDA is a trademark of NVIDIA Corporation. Other
273
+ names are used for identification purposes only and may be trademarks of their
274
+ respective owners. KernelVet uses these names only to say which hardware and
275
+ software it works with. It does not use AMD logos.