Дорожная карта новой версии проекта (com.sixik.gpu). Документ рассчитан на то, чтобы человек или нейросеть, не
знавшие контекста, сразу поняли, что строится, по каким правилам и что делать дальше.
Состояние на 2026-11-09: M0–M13 выполнены, M14 в работе.
Порядок чтения: README.md → этот файл → REWORK_ARCHITECTURE.md (все решения с обоснованиями; ссылки вида «разд.
5.10» указывают туда) → OldCodeConcept (как автор хочет видеть язык).
Кто за что отвечает:
REWORK_ARCHITECTURE.md— источник истины по решениям. Пометка[DECIDED]= решено автором, не пересматривать без его согласия. Пометкаделегировано Claude — пересматриваемо= можно предложить изменение с обоснованием.ROADMAP.md(этот файл) — план и статусы: цели, объём, критерии приёмки, порядок. При расхождении побеждаетREWORK_ARCHITECTURE.md; поправьте оба файла.- Новые решения записывайте в
REWORK_ARCHITECTURE.md, затем отражайте здесь.
Статусы: [ ] не начато · [~] в работе · [x] готово.
Legacy: прежняя реализация (JavaToGpu 0.1.0-alpha.5, ~1000 файлов) лежит в git-теге legacy-alpha5. Читать:
git show legacy-alpha5:<путь>. Портировать можно правила, знания, тест-кейсы; архитектуру копировать нельзя (
см. разд. 10).
Сборка: нужен JDK 25 (Gradle подбирает его через toolchain, сам Gradle запускается на 21+). ./gradlew build должен
быть зелёным на каждом коммите. Задача verifyModuleBoundaries входит в check.
В одном абзаце. Пользователь пишет GPU-код на Java (строго подмножество, не произвольный код); библиотека на этапе сборки превращает его в компактный бинарный IR, а в рантайме (JIT) генерирует OpenCL C под конкретное устройство, компилирует, кэширует и запускает. Если GPU нет — тот же метод выполняется на JVM. Архитектура рассчитана на будущий перенос ядра на Rust (AnyToGpu) без переписывания дизайна.
Ключевая боль, ради которой всё затеяно: адаптация кода под разные видеокарты (AMD / NVIDIA / Intel) и распределение работы между несколькими, в т.ч. разнородными GPU. Это будущие планы (разд. 8), в v1 закладываются только швы.
| ID | Цель |
|---|---|
| G1 | Метод с @Kernel на Java-подмножестве работает на OpenCL-устройстве через обычный вызов K.f(a, b) |
| G2 | Единственный канонический, сериализуемый, детерминированный IR (контракт Java↔Rust) |
| G3 | Строгая диагностика на этапе компиляции (GPU####, позиция в исходнике, подсказка) |
| G4 | Корректность проверяется без железа: IR-интерпретатор + golden-файлы + JVM-эталон |
| G5 | JVM-fallback и @GPUTest: тот же метод и тесты работают без GPU |
| G6 | Простая модульная структура с проверяемыми границами; никакого over-engineering |
| G7 | Возможности v1: скаляры, массивы, векторы, @Struct, pointer-типы, local memory, barrier, atomics, helper-функции |
Оптимизатор (e-graph), CUDA/SPIR-V/ROCm-эмиттеры, ASM-фронтенд (сделан после M14 — frontend-asm, раздел 17
архитектуры), images/samplers, async-API, multi-GPU,
Benchmark/AutoTune, вендорная адаптация кодгена, @GpuNative, разбиение одного запуска между картами. В языке: объекты
и куча, виртуальные вызовы, исключения, рекурсия, мониторы, labeled break/continue, try/finally, assert, строки.
- Данные плоские (DOD). IR и все таблицы ядра — SoA на примитивных массивах (
int[] op, type, a, b, c+ боковые таблицы). Ссылки — целочисленные id, не объекты. Строки интернируются. НикакихObject-графов,Map<String,String>как модели, reflection, иерархий узлов. - Логика — статические функции над данными. Запрещены
Registry / Factory / Provider / Service / Catalog / Contributor / Hook-паттерны в ядре. Разрешены ровно три точки расширения:Backend,OptimizerPass,EventListener(разд. 10 архитектуры). - Нет глобального изменяемого состояния в ядре. Контекст (
GpuContext) — явный объект. Единственное «ambient»-место — тонкий хост-фасад пользователя (ленивый default-контекст + scoped override). - Ошибки — значения. Ядро (
ir,codegen-opencl,ir-interpreter,runtime-core) возвращаетResult/списокDiagnostic(код + позиция + сообщение + подсказка). Исключения — только на публичной границе (GpuExceptionс полным отчётом) и во фронтенде для javacMessager. - Детерминизм. Один и тот же вход → побайтово тот же IR, хэш и OpenCL C. Нет зависимости от порядка
HashMap,String.hashCode, времени, пути. - Один канонический IR. Запрещены текстовый IR, обратный парсинг IR в исходник, параллельные представления.
Текстовый дамп (в
tools) — только для людей и golden-тестов, в IR не парсится обратно. - IR vendor-neutral и backend-neutral. Вендорная/бэкендовая специализация — только на выходе, в кодгене (
emit(IrModule, Target)). - Нет кастов в IR и в исходнике ради типов. Знак — метка типа; опкоды полиморфны; неявных приведений нет;
convertтолько явный. Касты кunsignedдопустимы лишь внутри сгенерированного C (чтобы дать Java-семантику). - Java-семантика целых и
float→intгарантирована контрактом IR (оборот знаковых, маскирование сдвигов, насыщение, NaN→0); деление на ноль — «не определено, без падения». - JVM ≡ GPU по конструкции. Подмножество языка и валидатор исключают расхождения (векторы immutable;
@Structбез aliasing). Float сравнивается «в ULP» из таблицы builtins, точного равенства не обещаем. - Платформа: Java 25, FFM (
java.lang.foreign) для OpenCL, без LWJGL и сторонних нативов. ASM — только вweaver. - Границы модулей проверяются сборкой. Не обходите
verifyModuleBoundaries— меняйте граф осознанно (и запись вREWORK_ARCHITECTURE.md, разд. 11). - Единый источник истины. Builtins — один декларативный файл;
Gpu.java, типы и таблицы генерируются, руками не правятся. - Каждый новый узел IR / правило / публичный метод — с тестом, и узел IR сразу в трёх местах: валидатор, интерпретатор, кодген.
[Сборка пользователя] @Kernel Java --frontend-java (javac Tree API)--> IR (бинарный, колонками) в ресурсах
--weaver (ASM)--> тело метода → делегат хост-фасаду; оригинал → <name>$jvm
[Выполнение] вызов K.f(a,b) → хост-фасад → GpuContext
IR → (optimize: identity в v1) → codegen-opencl: emit(IrModule, Target) → OpenCL C
→ компиляция драйвером → кэш (память + диск) → запуск → результат
нет устройства → JVM-fallback поверх <name>$jvm
| Модуль | Роль | Зависит от | Внешние библиотеки |
|---|---|---|---|
api |
аннотации, типы (vec/ptr/struct), builtins Gpu.* (генерируются) |
— | — |
ir |
SoA-таблицы, типы, builder, валидатор, сериализация, hash, ABI-layout | — | — |
ir-interpreter |
эталонный CPU-интерпретатор IR | ir |
— |
codegen-opencl |
IR → OpenCL C, чистая функция | ir |
— |
runtime |
GpuContext, устройства (SPI DeviceApiProvider), GpuBuffer, кэш, запуск, JVM-fallback, хост-фасад; Java 17 |
api, ir, ir-optimizer, codegen-opencl |
— |
runtime-opencl-ffm |
драйвер OpenCL через FFM, Java 25 (по умолчанию) | runtime |
— |
runtime-opencl-lwjgl |
драйвер OpenCL через lwjgl-opencl, Java 17 (Minecraft 1.18–1.21.x) |
runtime |
org.lwjgl |
frontend-common |
общий код фронтендов: атрибуты ядра, таблица диагностик, формат ресурсов | ir |
— |
frontend-java |
annotation processor → IR, subset-валидатор, диагностики | api, ir, ir-optimizer, frontend-common |
— (javac API из JDK) |
frontend-asm |
class-файлы → тот же IR (gpu { frontend = 'asm' }), device-функции из jar |
ir, ir-optimizer, frontend-common |
org.ow2.asm |
weaver |
подмена тела @Kernel-метода (ASM, чистая функция над ClassNode) |
— | org.ow2.asm |
gradle-plugin |
подключает зависимости, фронтенд (processor или ASM), weave-шаг, --enable-native-access |
weaver, frontend-asm |
Gradle API |
test-support |
GpuAssert, @GPUTest, KernelSample |
api, ir, ir-interpreter, runtime |
org.junit |
tools |
дамп IR, golden-генерация, отчёты (не публикуется) | ir, codegen-opencl, ir-interpreter, runtime |
— |
Корневой пакет: com.sixik.gpu (com.sixik.gpu.ir, .codegen.opencl, .runtime, .frontend.java, …).
Запрещено в api/ir/ir-interpreter/codegen-opencl: java.lang.foreign, javax.annotation.processing,
javax.lang.model, com.sun.*, ASM, LWJGL, импорты runtime/frontend/weaver/tools; в ir и codegen-opencl
дополнительно java.nio.file, java.io.File*, java.net.*.
| Тема | Решение | Где |
|---|---|---|
| Режим | JIT: IR при сборке, кодоген в рантайме с кэшем | разд. 3 |
| Форма IR | Structured IR (регионы if/loop/do_while/switch/block) + плоская арена выражений |
5 |
| Типы | Фиксированные скаляры BOOL,I8,U8,I16,U16,I32,U32,I64,U64,F32,F64 (знак — метка); арифметика только на 32/64-бит и float/double; I8..U16 — типы хранения |
5.1 |
| Векторы | Первоклассные (скаляр × lanes∈{2,3,4,8,16}); float3 в памяти = 16 байт |
5.2 |
| Struct | Value-тип; field_get/field_set/struct_build; массивов в struct нет в v1 |
5.3 |
| Локали | Изменяемые в IR (local_decl/get/set); SSA — внутренняя форма будущего оптимизатора |
5.4 |
| Массивы/указатели | Array(space,elem) с неявной длиной (ptr + int len в C) ≠ Ptr; память только через elem_ptr/field_ptr/load/store |
5.5, 5.10 |
| Функции | Модуль = набор функций + call; рекурсия запрещена; helper'ы — транзитивным замыканием |
5.6 |
| Builtins | Один декларативный файл → генерация Gpu.java, таблиц, допусков в ULP |
5.7 |
| Control flow | Без labeled break/continue; switch как в C |
5.8 |
| Формат | Свой бинарный, колонками; секция debug вне хэша |
5.9 |
| Каталог узлов | Утверждён (с ushr, expr_stmt, local_array_decl, elem_ptr, field_ptr, local_addr, spec_const) |
5.10 |
| Инварианты | Правила IR-S/T/V/E/C/M/F/B; эффекты только на уровне стейтмента; «открытые» узлы имеют одного родителя |
5.12 |
| Язык (синтаксис) | @Kernel, @DeviceFunction, @Struct, @Global, @Constant, @WorkGroup, Gpu.getGlobalId, FloatPtr, Float2 |
3.B, OldCodeConcept |
| Размер запуска | Дефолт 1D по длине первичного массива; override — явный scope | 3.4 |
| Fallback | JVM-цикл по global id поверх <name>$jvm; ядра с barrier/local — «нужно устройство» |
3.5, 3.8 |
| Диагностика | Ошибка компиляции с кодом GPU#### и позицией; режима «тихо на JVM» нет |
3.3 |
| Float | Strict по умолчанию (FP_CONTRACT OFF), fastMath явно; допуск в ULP на builtin |
8.3 |
| Платформа | Java 25 + FFM, без LWJGL | 9.2 |
| Потоки | GpuContext потокобезопасен, запуски на устройстве сериализуются |
9.1 |
| Кэш | Память + диск (user-cache dir), ключ = hash(IR без debug) + версия кодгена + устройство + опции | 9.3 |
| Устройство | DevicePolicy: фильтры + override + детерминированный порядок |
9.4 |
| Буферы | Массивы — сахар над GpuBuffer; режимы доступа параметров считает валидатор |
9.5 |
| Тесты | IR-интерпретатор, golden, device-тесты по тегу, JMH | 13 |
- IR / IrModule — канонический бинарный образ GPU-программы: таблицы типов, узлов, функций, строк, констант + секция
debug. - kernelId —
hash(IR без debug). - Узел — строка таблицы
nodes(op,type,a,b,c); id = индекс; операнды всегда с меньшим id. - Открытый узел — читает локаль или память (
local_get,load, …); у него ровно один родитель. Закрытый — константа/параметр/чистая арифметика над закрытыми; им можно делиться. - Target —
{backend, vendor, deviceClass, features, subGroupSize, computeUnits, …}изDeviceInfo; вход кодгена и часть ключа кэша. - DeviceInfo — vendor, name, driver, features, sub-group size, compute units, memory.
- required_features — битовая маска возможностей (fp64, int64-atomics, fp16…), считает валидатор IR; проверяется до компиляции.
- uses_group_sync — функция использует
barrierили local memory (транзитивно); такие ядра не уходят в JVM-fallback. <name>$jvm— оригинальное тело@Kernel-метода (один work-item), сохранённое weaver'ом: JVM-fallback и эталон тестов.- KernelSample — генератор аргументов + опциональные ожидаемые результаты; общий для
@GPUTest(v1) и AutoTune ( позже). - KernelGroup — (зарезервировано) варианты одного ядра с одной ABI.
- golden-файлы — эталонные текстовые дампы IR и OpenCL C; будущая конформанс-сюита для Rust-версии.
-
./gradlew buildзелёный (включаяverifyModuleBoundaries), без новых предупреждений-Xlint. - Все публичные типы и методы с Javadoc: назначение, параметры, возвращаемое, инварианты; для формул/математики — * что означает каждая переменная и почему формула верна* (на русском).
- На каждый публичный метод — JUnit-тест (позитивный + негативный); на каждое правило валидатора — тест, ловящий нарушение.
- Для hot path (построение/валидация/сериализация IR, кодген, накладные расходы запуска, поиск в кэше) —
JMH-бенчмарк в отдельном source set
src/jmh(настроить в M1). - Новые golden-файлы добавлены и проверены вручную; их обновление — осознанный коммит.
- Принципы разд. 2 не нарушены; новые решения записаны в
REWORK_ARCHITECTURE.md. - Статус вехи и критерии приёмки здесь отмечены.
- Нет мёртвого кода «на будущее»: заглушки только там, где это явно предписано (зарезервированные места IR).
Соглашения: коммиты вида feat:/fix:/chore:/test:/docs:; без коммита без запроса владельца; тесты с железом —
@Tag("device"), по умолчанию пропускаются.
Стратегия: тонкий вертикальный срез (M1–M7: baseline-ядро от исходника до запуска), затем ширина (M8–M13: по одной возможности, каждая — расширение IR → интерпретатор → кодген → рантайм → тесты). Всегда есть работающая сборка.
Baseline-подмножество среза: скаляры, массивы, if/for/while/do-while/switch, арифметика/сравнения/логика/тернарный,
helper-вызовы, builtins, FloatPtr — позже (M9).
Тег legacy-alpha5; старый код удалён; скелет из 10 модулей; Gradle 9.8.1, JDK 25, JUnit 6.1.3, ASM 9.11.1;
verifyModuleBoundaries (проверено негативными тестами). Коммит 5ce86b90.
Цель: канонический IR, валидатор и сериализация — без единой зависимости. Фундамент всего остального.
Сделано (ir/src/main/java/com/sixik/gpu/ir):
- Таблица типов (
Types,AddressSpace): фиксированные id скаляров0..11(+VOID),12..15зарезервированы; динамическиеVec,Ptr,Array,Struct(сalign) с дедупликацией, struct номинальны. - SoA-таблицы (
IrModule):nodes(op,type,a,b,c), пул списков, 64-битные константы (≤32 бит иf32— прямо в колонкеa), семантические строки, таблица функций (18 колонок: kind, параметры, локали,reqd_wg,inline,opt,required,body_kind,fallback,tune_*). Каталог опкодовOp(≈55) и единая схема операндовOperands. IrBuilder: типизированные методы со своим выводом типов, детерминированная нумерация (операнды раньше узла), отладочные имена и позиции (DebugInfo).Validator: все правила 5.12 (IR-S/T/V/E/C/M/F/B) + вычислениеrequired_features,uses_group_sync, режимов доступа параметров, эффектов; возвращаетDiagnostic, не бросает исключений даже на мусорных данных.IrBinary: колоночный формат"GIR\0", секцииTYPE STRS CNST NODE LIST FUNC DBUG;hash/kernelId(SHA-256) безDBUG; чтение возвращаетResult(IR-S05версия,IR-S06повреждение).AbiLayout(O4): size/align/offset по правилам OpenCL C,float3= 16 байт.Builtins(O1, часть):builtins/builtins.defв корне репозитория упаковывается в ресурсыirи читается в рантайме; 15 builtins (индексы, математика,assumeUniform,atomicAdd); сигнатуры проверяются по классамgenf/geni/genn.tools:IrDump— текстовый дамп (с/без отладки) + golden-тесты.ir:testFixtures(Fixtures.computeSine(),Fixtures.rich()) для тестов следующих модулей. JMH:gradle/jmh.gradle,ir/src/jmh.
Критерии приёмки:
- Тест на каждое правило
IR-S/T/V/E/C/M/F/B— 107 тестов валидатора; мутационная проверка: отключение правила роняет ровно свой тест. - Round-trip
serialize → deserializeсовпадает побайтово; одинаковая последовательность builder'а → одинаковые байты и hash. - Hash не меняется при изменении только
debug; меняется при изменении константы и атрибута функции. - Golden:
computeSineизREWORK_ARCHITECTURE.md5.11 воспроизводится (15 узлов, 300 байт,t16/t17). -
irбез зависимостей и запрещённых импортов (verifyModuleBoundaries); JMH для build/validate/read/write/hash. - Фазз: 2,1 млн итераций (побайтовых и «семантических») — читатель и валидатор не падают. Фазз нашёл и помог исправить два реальных дефекта валидатора (каскад повреждённых операндов).
Измерения (JMH, 217 узлов, 3 функции): build 4,1 мкс · validate 17,7 мкс · write 4,3 мкс · read 0,8 мкс · hash 5,9 мкс · холодный путь «read → validate → kernelId» 25,5 мкс.
Решения, принятые в M1 (подробности — REWORK_ARCHITECTURE.md, 5.13): O1 — builtins читаются рантаймом из ресурса
(генератор нужен только api в M2); O4 — ABI живёт в ir; O7 — таблица «операция × тип» и коды
IR-S06/S07/T09/T10/V04
зафиксированы; правило «открытый узел имеет одного родителя» означает, что фронтенд для a[i] += 1 создаёт два
узла elem_ptr.
Не входит: images, оптимизатор, исполнение (M4), кодген (M5).
Цель: публичный язык GPU-кода.
Сделано (api/src):
- Аннотации
@Kernel(inline, optLevel, workgroup, required, fallback),@DeviceFunction,@Struct(alignment),@Global(constant),@Local,@Constant,@WorkGroup(x,y,z)(RetentionCLASS— их читает weaver) иInlinePolicy. - Генератор (
src/generator, задачаgenerateApi, вывод вbuild/generated): изbuiltins/builtins.defстроитGpu(скалярыfloat/double/int/long+ покомпонентные векторные перегрузки, Javadoc изdoc, JVM-реализации изjvm), 20 векторных типовFloat|Double|Int|Long × {2,3,4,8,16}(неизменяемые) и классы-ссылкиFloatPtr/DoublePtr/IntPtr/LongPtr. Таблица расширена директивамиdoc/jvm/vectors/pointersи флагомulp64=(irих пропускает;Builtins.ulp64). WorkItem/WorkItemContext(O6): положение work-item для JVM-реализацийgetGlobalIdи др.,ScopedValue, плоскиеint[3].- Тесты
api: 54 теста (генератор позитивно/негативно, builtins на крайних значениях, ULP-сверка с независимыми эталонами, контекст work-item, типы, аннотации,ConceptSample— образец концепта, выполняемый на JVM). JMH:ApiBenchmarks.
Критерии приёмки:
-
Gpu.javaи типы не правятся руками: генерируются в сборке (коммитить нечего, расхождение невозможно); - JVM-реализации совпадают с таблицей допусков на крайних значениях (
GpuUlpToleranceTest; мутационная проверка: порчаsin/sqrtв таблице роняет тесты f32 и f64); builtin с допуском без эталона в тесте роняет тест; - синтаксис из
OldCodeConceptкомпилируется и выполняется на JVM (без@GpuNative/@GpuFallback/@AutoTune— не v1); - ни одной внешней зависимости (
verifyModuleBoundaries; генератор и JMH не входят в jar).
Измерения (JMH, короткий прогон): один work-item JVM-fallback ≈ 14 нс против ≈ 6,4 нс прямого цикла (≈ 8 нс — цена контекста),
привязка контекста WorkItem.run ≈ 15 нс на запуск.
Решения, принятые в M2 (подробности — REWORK_ARCHITECTURE.md, 5.14): O1 закрыт (один файл — две стороны); O6 закрыт
(ScopedValue); atomicAdd без Java-представления до M9/M10; float max/min на JVM = Math.max/min — кодген (M5) обязан
дать ту же семантику (NaN, ±0), иначе OpenCL fmax/fmin разойдётся с JVM; допуски ULP сверить с первоисточником
спецификации в M5; required — имена Features IR ("SIMD" из концепта — диагностика в M3).
Не входит: операции над векторами (M8), pointer-типы Global*/Local*/Constant*Ptr (M9), barrier и atomics в Java-API (M10).
Опирается на: 3.A, 3.B, 5.7, 8.3.
Цель: @Kernel-метод → IR на этапе javac.
Сделано (frontend-java/src/main, пакет com.sixik.gpu.frontend.java):
GpuProcessor— annotation processor на javac Tree API (регистрируется черезMETA-INF/services);ProcessingEnvironments— обход обёрток окружения Gradle/IDE; ошибки и предупрежденияGPU####с точной позицией черезTrees.printMessage.SubsetChecker— проверка подмножества Java (все нарушения за один проход, 41 кодов вdiagnostics/diagnostics.def);FunctionLowerer— построение IR с нормализацией эффектов (порядок вычислений Java,i++/op=/присваивания внутри выражений, ленивые&&/||/?:, циклы с эффектным условием), числовое повышение типов, массивы (global/local/constant/private);ModuleCompiler— замыкание вызовов, порядок функций,fallback-варианты, проверка IR валидатором;KernelResources— ресурсы.- Ресурсы (O5):
META-INF/gpu/ir/<kernelId>.girи индекс ядерMETA-INF/gpu/kernels.idxдля weaver'а. - Тесты
frontend-java: 34 теста — golden-дампы IR (арифметика, управление потоком, device-функции, нормализация эффектов, атрибуты, функции из другого класса), негативный тест на каждый код, обход прокси окружения, ресурсы, определение процессораServiceLoader'ом, стресс-образец на широком наборе конструкций.
Критерии приёмки:
- компиляция образцов через
javax.tools.JavaCompilerin-process и сравнение с golden-дампом IR;computeSineиз README даёт тот жеkernelId, что модуль, собранный вручную вir(Fixtures.computeSine); golden проверены вручную построчно, мутационная проверка: порча сохранения операндов или операции роняет тесты; - для каждого кода
GPU####— негативный тест (код и строка); таблица и код согласованы в обе стороны; - результат IR проходит валидатор
ir(и при любой ошибке валидатора выдаётсяGPU0901); - обход прокси
ProcessingEnvironmentопределён и проверен (класс-обёртка,Proxy, двойная обёртка, неразворачиваемое окружение).
Решения, принятые в M3 (подробности — REWORK_ARCHITECTURE.md, 5.15): O5 закрыт; один модуль на ядро, ядро — последняя функция;
типы в телах методов доступны уже в раундах processing на JDK 25 (проверено экспериментом); вызываемые методы обязаны иметь
@DeviceFunction (GPU0113); ограничение: device-функции из библиотек без исходников (GPU0114) пока не поддерживаются — нужны
распространение их IR/исходников и связывание модулей (функции из других классов той же компиляции работают).
Не входит: векторы, @Struct, pointer-типы и FloatPtr (на тот момент GPU0190; сделаны в M8/M9); for-each (GPU0111); barrier/atomics (M10);
объявление процессора инкрементальным (M7, плагин Gradle); JMH (фронтенд работает на этапе сборки, не на hot path).
Опирается на: 3.A, 3.3, 5.4, 5.8, 5.12.
Цель: эталонная семантика IR на CPU.
Сделано (ir-interpreter/src/main, пакет com.sixik.gpu.ir.interpreter):
Interpreter.run(IrModule, NdRange, Object...)— публичная точка входа (ядро — последняя функция модуля) и перегрузка с индексом функции иOptions(maxSteps); результат —Result<Execution>(число work-item'ов и шагов); массивы хоста изменяются только при успехе.NdRange.of1D/of2D/of3D— виртуальный NDRange (с размерами группы или без).Machine— исполнитель на плоских массивах (стек значений, таблица буферов, геометрия NDRange);Alu— статические функции арифметики и преобразований;Support— проверка поддержанного подмножества до запуска;Host— соответствие массивов/скаляров хоста типам IR.- Ошибки — значениями: перед запуском работает
Validator, затем кодыIN-A00..A02,IN-L01,IN-U01, во время работыIN-R01..R04(разд. 5.16REWORK_ARCHITECTURE.md). - Тесты (70):
AluTest(18, независимый оракул наBigInteger/BigDecimal),DifferentialTest(23, образцы — настоящие@Kernel-методы, собранные фронтендом из M3),InterpreterTest(29, модули, собранные вручную: беззнаковые типы, ошибки исполнения и запуска).
Критерии приёмки:
- дифференциальные тесты: на 20 образцах-ядрах результат интерпретатора совпадает с прямым вызовом оригинального Java-метода по
work-item'ам (целые и логика — точно,
float/double— побитово либо в ULP там, где задан допуск); если JVM бросила исключение, интерпретатор обязан отказать; - крайние значения: все пары
MIN/MAX/0/±1и случайные пары дляintиlong,NaN/±Inf/±0и границы насыщения дляfloat/double, сдвиги на0, 1, ширина-1, ширина, ширина+1, отрицательные; беззнаковые типы (в Java их нет) — черезBigIntegerи ручные модули; - нет зависимостей кроме
ir(production);apiиfrontend-javaподключены только к тестам;verifyModuleBoundariesзелёный; - мутационная проверка вручную: сдвиг без маски, потеря «липкого» бита
U64→F64, знаковое деление дляU32, убранныйNaN→0, беззнаковое расширение/сдвиг/сравнение, жадныйselect,continueмимо шага обновления,switchбез проваливания, непереобнулённый приватный массив, перепутанныеmax/min, неосвобождаемые приватные массивы, перепутанныеlocal/group id, потеря нулевого расширенияU8— все роняют тесты (выжившая мутация про освобождение буферов породила тестmanyCalls).
Решения, принятые в M4 (подробности — REWORK_ARCHITECTURE.md, 5.16): значение — один long на скаляр, указатель — (буфер, индекс);
целое деление на ноль — ошибка IN-R02 (строже IR, чтобы тест не принял случайное значение); float→byte/short/char — как Java:
насыщение до int, затем сужение с оборотом — кодогенератор M5 обязан совпасть; atomicAdd исполняется последовательно; JMH не
добавлен — интерпретатор не на hot path.
Не входит: barrier, local_array_decl (M10), local_addr, field_ptr (M9), векторы и структуры (M8), spec_const, нативные тела —
все дают IN-U01; параллельное исполнение work-item'ов; сверка с реальным устройством (M6+).
Опирается на: 5.10, 8.3, 13.
Цель: emit(IrModule, Target) → Artifact (текст OpenCL C + имена entry + раскрытая сигнатура аргументов).
Сделано (codegen-opencl/src/main, пакет com.sixik.gpu.codegen.opencl):
OpenClEmitter.emit(IrModule, Target)иemit(IrModule, kernel, Target, EmitOptions)→Result<Artifact>;Artifact(текст, entry,KernelArg-сигнатура,required_features, опцииclBuildProgram),Target(шов под вендора, в v1 не влияет на текст),EmitOptions(debug, fastMath, имя файла для#line).- Внутри:
FunctionEmitter(печать функции, приоритеты операторов),Helpers(деление,float -> int,max/minс Java-семантикой - только использованные),CTypes(типы и литералы),Names(манглинг),Support(достижимость и проверка поддержанного подмножества,CG-U01). - Ошибки значениями:
IR-*валидатора,CG-A00,CG-A01,CG-U01(векторы/struct - M8, pointer - M9, barrier/local - M10). - Тесты (166 обычных + 86 на устройстве):
GoldenTest(90: 45 модулей x release/debug),EmitterTest(40),CTypesTest,NamesTest,HelpersTest,SupportTest,ApiTest,DeviceTest(./gradlew :codegen-opencl:deviceTest).
Критерии приёмки:
- golden-файлы OpenCL C для всех образцов (20 ядер из Java,
computeSine, 24 ручных модуля), отдельно release и debug; просмотрены вручную; - детерминизм: повторный
emit= те же байты; release не зависит от debug-секции; текст не зависит отTarget(v1); - ни
java.nio.file, ни FFM в production-коде (verifyModuleBoundariesзелёный, зависимость только отir); - (device) сгенерированный C компилируется реальным драйвером и даёт результат интерпретатора (NVIDIA GeForce RTX 5070); остаётся
формализовать в M6 (
DeviceApi,@Tag("device")в общей схеме) и проверить на AMD/Intel; - мутационная проверка device-теста вручную: беззнаковый вместо арифметического
>>>, убранныйNaN -> 0,max/minбезNaN/знака нуля, знаковое деление без защиты-1,%вместоfmod, усечённый литералU32- роняют тесты. Выжили две эквивалентные на OpenCL мутации (лишняя ширина маски счётчика сдвига - OpenCL маскирует сам; знаковый<<без беззнакового типа - оборот на GPU и так). Стенд сам не замечал знак нуля при допуске в ULP - исправлено.
Решения, принятые в M5 (подробности - REWORK_ARCHITECTURE.md, 5.17): Array(T) -> T* name, int name_len, порядок аргументов - Artifact.args();
release без имён и #line, в debug-секции IR нет имени файла; Java-семантика целых через беззнаковый тип, знаковое деление и float -> int через
вспомогательные функции, float -> byte/short/char через int (совпадает с ir-interpreter); select булевых -> &&/||; continue в цикле со
сложным шагом -> goto; строгий float: FP_CONTRACT OFF, fastMath -> -cl-fast-relaxed-math; образцы-ядра вынесены в testFixtures ir-interpreter.
Не входит: векторы и struct (M8), pointer-типы (M9), barrier/local-память (M10), вендорные правила (8.5, после v1), оптимизатор, JMH (кодген работает
на этапе JIT, не на hot path); -cl-fp32-correctly-rounded-divide-sqrt (решение в M6); проверка на AMD/Intel.
Опирается на: 8, 8.A.
Цель: найти устройство, скомпилировать, залить буферы, запустить, забрать результат — синхронно.
Сделано (runtime/src/main, пакеты com.sixik.gpu.runtime и .runtime.device):
DeviceApi— тонкий слой над OpenCL (≈25 методов),OpenClApi— реализация на FFM (OpenCL.dll/libOpenCL.so.1/ macOS framework; нет библиотеки или платформ = «устройств нет»),DeviceInfo(свойства +Featuresпо расширениям),DevicePolicy(фильтры,override, окружение),DeviceApiException.GpuContext(builder, потокобезопасный, одно активное устройство): компиляция с кэшем в памяти (одна сборка на ключ), проверка возможностей устройства до компиляции, разбор build log (BuildLog), синхронный запуск, массивы хоста как сахар (Marshal),GpuBuffer(device-resident),EventListener/GpuEvent,LaunchConfig,LaunchStats,CacheStats; ошибки —Resultвнутри иGpuExceptionна границе.FakeDeviceApiвtestFixtures— для тестов без железа (журнал вызовов, учёт живых объектов, сбои, отказ сборки).- Тесты: 71 обычный на фейке + 23
@Tag("device")(./gradlew :runtime:deviceTest).
Критерии приёмки:
- unit-тесты на фейковом
DeviceApi(без железа): 71 тест; -
@Tag("device")тест:computeSineна реальном OpenCL (NVIDIA GeForce RTX 5070) совпадает сMath.sinв пределах 4 ULP; кроме него — 16 образцов-ядер противir-interpreter, цепочка ядер наGpuBufferбез передач, параллельные запуски; - FFM-доступ без LWJGL (
verifyModuleBoundariesзелёный; нативных зависимостей нет); - отсутствие драйвера не роняет старт:
tryBuild()возвращаетRT-D01,OpenClApi.load()—null; - мутационная проверка вручную (17 мутаций логики контекста, политики,
Marshal,BuildLog: возврат всех массивов, потеря режима доступа при алиасинге, ключ кэша без опций, проверка делимости иreqd_work_group_size, утечки буферов/ядер, пропуск проверки возможностей, неверная совместимость буферов и др.) — все роняют тесты; две найденные слабости тестов (алиасинг с записью через первый параметр) закрыты тестом.
Решения, принятые в M6 (подробности — REWORK_ARCHITECTURE.md, 5.18): на устройство передаются все массивы, на хост возвращаются только записываемые
(уточнение 9.5: иначе частично записанный массив терял бы нетронутые элементы); один массив дважды = один буфер; неудачная компиляция тоже кэшируется;
required_features проверяются до драйвера (RT-D02); размер work-group не задан = выбирает драйвер; явный выбор устройства — свойство javatogpu.device /
переменная JAVATOGPU_DEVICE; коды RT-D01..D03, RT-C01/C02, RT-A01..A03, RT-L01, RT-X01/X02.
Не входит: JVM-fallback и хост-фасад (M7, зависят от weaver; O2); дисковый кэш (9.3) и prepared launcher — после M7; __local-аргументы (M10); async и
multi-GPU (не v1); проверка на AMD/Intel.
Опирается на: 9, 9.1, 9.2, 9.5. Legacy (идеи): OpenClGpuRuntimeBackend, OpenClRuntimeSession, OpenClArgumentMarshaller, OpenClValuePacker.
Цель: обычный вызов K.f(a, b) запускается на GPU.
Сделано:
weaver(com.sixik.gpu.weaver):Weaver.weave(byte[], KernelIndex)иweaveTree(Path)— чистая функция над ASM tree API: тело@Kernel-метода уходит в<имя>$jvm, метод становится делегатомJavaToGpu.invoke(...);KernelIndex— разборkernels.idx. Идемпотентно, замечания вместо молчаливых пропусков.gradle-plugin(io.github.deussixik.javatogpu): зависимости и annotation processor, weave-шаг послеJavaCompile,--enable-native-access=ALL-UNNAMEDдляTest/JavaExec; блокgpu { version, group, autoDependencies, weave, extraJvmArgs }.runtime: хост-фасадJavaToGpu(O2 закрыт): ленивый контекст по умолчанию + shutdown hook +configureDefault,use(ctx),launch(LaunchConfig),invoke(...); JVM-fallback поверх$jvm;GpuContext.Fallback {ALLOWED, NEVER}, событиеFALLBACK.testFixturesweaver:KernelCompiler(javac in-process с processor'ом frontend-java).- Тесты: 13 (weaver) + 16 E2E без железа (runtime) + 6 TestKit (плагин) +
WovenKernelDeviceTest(./gradlew :runtime:deviceTest).
Критерии приёмки:
- TestKit-проверка плагина на тестовом проекте: сборка, weave, запуск
runDemo, up-to-date и повторная компиляция, выключателиweaveиautoDependencies, аргументы JVM, регистрация расширения; - байткод-тест weaver'а: оригинал сохранён как
$jvm(те же сигнатура, флаги, число инструкций; без аннотаций), делегат вызывает фасад с верными константами и упаковкой,@Kernelи аннотации параметров остаются на делегате, идемпотентность, класс загружается и проходит верификацию; - E2E
@Tag("device"):computeSineзапускается обычным вызовом на реальном OpenCL (NVIDIA GeForce RTX 5070, режимNEVER) и совпадает сMath.sinи с$jvmв пределах 4 ULP; - E2E без железа: weave + IR-ресурс присутствуют, обычный вызов исполняется на
FakeDeviceApiи на JVM-fallback (устройства нет / драйвер отверг ядро); - мутационная проверка вручную (18 мутаций weaver'а, фасада, контекста и плагина: слоты
long/double, аннотации на$jvm, идемпотентность, static/void,kernelId, упаковка, дескриптор в индексе,NEVER,usesGroupSync, размер work-group в fallback, пропуск последнего work-item'а, размер по умолчанию, порядок областей, повторные попытки, повторные предупреждения, переключатель weave,--enable-native-access) — все роняют тесты. Две слабости тестов найдены и закрыты: кэш фасада поkernelId(дефект, исправлен) и проверка флага по подстроке вывода (JDK сам упоминает флаг в предупреждении).
Решения, принятые в M7 (подробности — REWORK_ARCHITECTURE.md, 5.19): имя фасада JavaToGpu (O2); делегат вызывает
JavaToGpu.invoke(Class, String, String kernelId, Object[]), kernelId берётся из kernels.idx; кэши фасада привязаны к классу-владельцу (ClassValue);
fallback только при отсутствии устройства или отказе компиляции (ошибки пользователя не маскируются), одно предупреждение на ядро; ядра с barrier/local на JVM
не уходят; weave внутри задачи компиляции (up-to-date видит подменённые файлы); размер запуска по умолчанию — длина первого массива.
Не входит: выбор @Kernel(fallback = ...)-варианта при нехватке возможностей устройства; дисковый кэш и prepared launcher; Maven-плагин и Java-агент;
публикация артефактов; @Struct и указатели в сигнатуре ядра (O3, M8/M9).
Опирается на: 3.4, 3.6, 3.7. Открыто: — (O2 закрыт).
Цель: векторы и @Struct проходят весь путь от исходника до устройства.
Сделано:
api: неизменяемыеFloat/Int/Long/DoubleNс операциями (splat,lane,with<Lane>,shuffle, арифметика, для целых - побитовые), генерируются изbuiltins.def.ir:HostObjects— соответствие агрегатов IR Java-объектам хоста (листья, смещения поAbiLayout,mismatch/flatten/rebuild) (O3 закрыт).ir-interpreter: агрегаты в кадрах и буферах, покомпонентная арифметика и builtins, массивы объектов хоста, агрегаты по значению.codegen-opencl:Layouts(типы,typedef struct, swizzle), динамические помощники, векторная арифметика, расширенный набор зарезервированных имён OpenCL.frontend-java: распознавание векторов/struct, правила value-семантики (GPU0191..0196), цепочки записи в поля, методы векторов.runtime: упаковка и возврат массивов объектов, агрегаты по значению (setArgBytes), размер запуска по массиву объектов.
Критерии приёмки:
- дифференциальные тесты векторов и struct: JVM (
$jvm) ≡ интерпретатор наVectorKernels/StructKernels; - golden C для векторных и struct-ядер и ручных модулей; каждый модуль компилируется драйвером NVIDIA;
- device-тест массивов struct и векторов: образцы с объектами сравниваются с интерпретатором на реальном OpenCL (NVIDIA GeForce RTX 5070);
- мутационная проверка вручную (15 мутаций: смещения и канонизация листьев, правила свежести, деление на ноль по компонентам, сдвиги, swizzle >4 компонент,
возврат объектов в хост,
null-элемент, смещения упаковки, размер аргумента по значению) — все роняют тесты.
Решения, принятые в M8 (подробности — REWORK_ARCHITECTURE.md, 5.20): хост-представление — массивы объектов с упаковкой по ABI (генерируемые аксессоры
отложены); struct обновляется на месте, вектор создаётся заново; значение struct должно быть свежим (new, copy(), @DeviceFunction) — иначе GPU0193;
float3 = 16 байт; все имена OpenCL builtins зарезервированы в Names; GpuBuffer для массивов агрегатов не поддержан (RT-A02).
Не входит: GpuBuffer массивов агрегатов и плоские аксессоры; convert/bitcast векторов в Java API; векторы малых элементов; локальные массивы агрегатов;
new P() без аргументов в ядре; pointer-типы и field_ptr/local_addr (M9); проверка на AMD/Intel.
Опирается на: 3.2, 5.10–5.12, 5.20. Legacy (идеи): OpenClStructLayout, OpenClVectorLayout, OpenClValueLayout, docs/OpenCL-Data-Model.md.
Цель: ссылки FloatPtr и явные указатели Global*/Local*/Constant*Ptr проходят весь путь от исходника до устройства; @Global(constant = true) целиком.
Сделано:
api: 12 классов явных указателейGlobal|Local|Constant × Float|Double|Int|Long(of/get/set/plus; уConstant*записи нет), генерируются изbuiltins.def.ir: правилаIR-M01/M04,local_addr/elem_ptr/field_ptrбыли в M1; исправлено вычисление режима доступа параметров: указатель, сохранённый в локаль или возвращённый, помечает базовый массив читаемым и записываемым (иначе записанные через указатель данные не возвращались бы на хост).ir-interpreter: адрес - номер ячейки,STACK- буфер-стек дляlocal_addr,field_ptr, арифметикаelem_ptrпо ширине элемента, проверка границ по ширине доступа.codegen-opencl: типы__space T*,&x,&lvalue.f,(*p).f, указатели в параметрах и локалях device-функций.frontend-java: видK_PTR; ссылка как локаль сlocal_addr,r.value(чтение, запись,op=,++), методы указателей, пространство массива (GPU0199);GPU0122(запись в constant-массив),GPU0197,GPU0198;GPU0190удалён.runtime:DeviceInfo.maxConstantBuffer/maxConstantArgs, проверка__constant-аргументов до загрузки данных (RT-A04).
Критерии приёмки:
- тесты семантики по ссылке (JVM ≡ GPU): дифференциальные
PointerKernels(JVM$jvmпротив интерпретатора), те же ядра на NVIDIA GeForce RTX 5070 против интерпретатора,PointerDeviceTest- обычный вызов woven-ядра на устройстве совпал с JVM-эталоном точно и вернул запись через указатель в массив хоста; - запись в
constantотклоняется:GPU0122во фронтенде,IR-M01в валидаторе (для чужих фронтендов), уConstant*Ptrметода записи нет; чтение constant-массива и превышениеCL_DEVICE_MAX_CONSTANT_BUFFER_SIZE/_ARGS(RT-A04) проверены на фейке и на реальном устройстве; - golden C для
pointersиPointerKernels.*, golden IRpointers.ir.txtпросмотрены построчно; каждый модуль компилируется драйвером NVIDIA; - мутационная проверка вручную (21 мутация интерпретатора, кодгена, валидатора, фронтенда, рантайма): все роняют тесты, одна оказалась эквивалентной (дубль проверки) - удалена.
Решения, принятые в M9 (подробности - REWORK_ARCHITECTURE.md, 5.21): ссылка - локаль, чей адрес отдаётся (владелец new FloatPtr, без переприсваивания); явный указатель -
значение «массив + смещение», переприсваивается стейтментом, не сравнивается; указатель не бывает параметром ядра; режим доступа через указатель - консервативно чтение+запись;
в интерпретаторе адрес - ячейка, стек значений - особый буфер.
Не входит: сквозная проверка Local*Ptr на устройстве (нужен local_array_decl, M10); field_ptr из исходника Java (проверен ручными модулями); atomicAdd в Java API (M10);
указатель-параметр ядра; проверка на AMD/Intel.
Опирается на: 3.B, 5.5, 5.12, 5.21.
Цель: группы work-item-ов проходят весь путь от исходника до устройства: @Local-массивы, Gpu.barrier(), атомики.
Сделано:
builtins.defиapi:Gpu.barrier(),Gpu.barrierGlobal(), атомикиatomicAdd/Sub/Min/Max/And/Or/Xor/XchgнадGlobal*/Local* Int|Long Ptr; генератор научился указателям в сигнатуре и блочным JVM-телам.ir: флаги builtinsyncиext, правилоIR-S08(точка синхронизации - только узелbarrier), возможностьINT64_EXT_ATOMICS. Узлы иIR-B01были готовы с M1.ir-interpreter: исполнение по группам, local-массивы на группу (нулями), барьер на сопрограммах (Coop: по одному work-item-у за раз, детерминированно),IN-R05(группа не вышла на один и тот же барьер), остановка группы при нарушении без зависания, семейство атомиков.codegen-opencl:__local T имя[N],barrier(CLK_*_MEM_FENCE),atomic_*/atom_*, прагма расширенных 64-битных атомиков.frontend-java:Gpu.barrier*- узелbarrier; указатель как аргумент атомика;IR-B01-GPU0130(предупреждение) иGPU0131(-Ajavatogpu.strictBarriers=true).gradle-plugin:gpu { strictBarriers = true }.runtime: проверка local-памяти ядра против устройства (RT-D04),INT64_EXT_ATOMICSпо расширению.
Критерии приёмки:
- редукция/тайлинг-примеры в интерпретаторе и на устройстве:
LocalKernels(редукция с барьером в device-функции, транспонирование 8x8 через тайл, префиксная сумма, гистограмма с local-атомиками, глобальные счётчики, 64-битные атомики) - результат совпал с посчитанным на хосте (интерпретатор), с интерпретатором (NVIDIA GeForce RTX 5070),GroupDeviceTest- обычный вызов woven-ядер на устройстве; - тесты на
IR-B01: расходящийся барьер, барьер в вызываемой функции,assumeUniform, равномерный цикл с барьером,strictBarriers(фронтенд и плагин Gradle); - golden C для
LocalKernels.*; каждое ядро компилируется драйвером NVIDIA; - мутационная проверка вручную: 20 мутаций интерпретатора, кодгена, валидатора, фронтенда, рантайма и плагина - все роняют тесты.
Решения, принятые в M10 (подробности - REWORK_ARCHITECTURE.md, 5.22): групповые ядра не сверяются с $jvm (барьер на JVM невыполним), эталон считает хост; ядро с барьером в
JVM-fallback не уходит (RT-F01); интерпретатор строже OpenCL (барьер обязан быть общим, local-память обнулена); __local-параметры ядра - вне v1.
Не входит: __local-параметры ядра с размером из launch-конфига; atomicCmpxchg, вещественные атомики; подгруппы; проверка на AMD/Intel.
Опирается на: 5.5, 5.12, 5.22.
Цель: повторные запуски одного ядра без повторной подготовки; владение памятью вместо флагов-масок.
Сделано:
PreparedLauncher(runtime) - единственная реализация:ctx.prepare(kernel, args...)иJavaToGpu.prepare(класс, имя, args...); аргументы проверяются один раз, буферы под массивы хоста и нативная память упаковки создаются один раз;launch/run(config),set(i, значение),close().- Правила владения:
GpuBuffer- данные пользователя, ничего не передаётся (static-таблицы, цепочки, пинг-понг); массив хоста - буфер принадлежит запуску, записывается целиком перед запуском, назад возвращается только записываемое ядром; скаляры и агрегаты по значению -set. - Привязка аргументов
cl_kernel:CompiledKernel.boundTo- после чужого запуска выставляются все аргументы, иначе только изменённые. - JMH (
src/jmhвruntime):FakeLaunchBenchmarks(накладные расходы библиотеки на фейке) иDeviceLaunchBenchmarks(реальное устройство).
Критерии приёмки:
- JMH накладных расходов запуска: фейк - 1552 нс (обычный запуск, массивы) против 387 нс (подготовленный),
GpuBuffer223 против 151 нс; RTX 5070 - 329 против 125 мкс (1024 элемента), 4416 против 1467 мкс (1 048 576 элементов); сGpuBufferоба по 30 мкс (время в драйвере); - тесты владения/освобождения буферов: буферы запуска освобождаются
close()и закрытием контекста, буферы пользователя не трогаются, повторное закрытие безопасно, нет утечек на фейке, алиасинг массива; - на устройстве: 20 запусков с меняющимися данными и скаляром и 25 итераций пинг-понга на
GpuBufferровно с 0 переданных байт совпали с расчётом на хосте; - мутационная проверка вручную: 13 мутаций - все роняют тесты (одна выжившая закрыла слабость теста).
Решения, принятые в M11 (подробности - REWORK_ARCHITECTURE.md, 5.23): массив хоста всегда загружается целиком (как у обычного вызова), экономия - через GpuBuffer; подготовленный запуск не уходит
на JVM; set не заменяет массивы хоста.
Не входит: async-запуск и очереди; пул буферов между запусками; GpuBuffer для массивов векторов/struct; проверка на AMD/Intel.
Опирается на: 9, 9.5, 5.18, 5.23.
Цель: повторный запуск процесса не платит за компиляцию драйвером; вариант ядра выбирается по возможностям устройства; тайминги и счётчики кэша доступны через EventListener.
Сделано:
- Дисковый кэш бинарей (
runtime): образ программы драйвера (clGetProgramInfo/clCreateProgramWithBinary, оба вDeviceApi, FFM и фейк) под кэшем в памяти. Ключ: версия кодгена +kernelId+ опции + устройство и драйвер + хэш исходника; атомарная запись (tmp +ATOMIC_MOVE), повреждённый или отвергнутый драйвером образ - промах и пересборка, LRU по размеру (512 МиБ). Каталог кэша ОС,javatogpu.cache/JAVATOGPU_CACHE,builder.diskCache/noDiskCache/diskCacheLimit; для подменённого драйвера (тесты) по умолчанию выключен. - Политика устройства:
DevicePolicyбыл готов с M6; добавленыbuilder.device(...)и тесты на разнородных фейковых устройствах. - Тайминги:
Timings-EventListener, копящий число/время/байты по видам событий и счётчики компиляции (собрано / память / диск / неудачно);GpuEvent.device- id устройства;CacheStatsс дисковыми счётчиками. - Варианты по
required: нехватка возможностей устройства (заявленных и вычисленных) ведёт кfallback-варианту, без измерений;inline/optLevel- информативные атрибуты (тест). - Горячий путь:
kernelIdзапоминается по модулю - попадание в кэш памяти 734 -> 83 нс.
Критерии приёмки:
- тесты кэша: попадание между контекстами, промах при смене устройства/опций/версии кодгена, повреждение (бит, усечение, чужой заголовок, пустой файл), отказ драйвера от образа, драйвер без образов, LRU, атомарность,
конкуренция; на реальном драйвере NVIDIA образ принят
clCreateProgramWithBinary, ядро из него считает верно, мусор в целом файле заменяется пересборкой; - политика на фейковых устройствах (NVIDIA + AMD + CPU): фильтры, явный выбор, порядок, builder против окружения;
- JMH
CompileCacheBenchmarks: попадание в кэш памяти 83 нс, чтение образа 64 КиБ с проверкой суммы порядка 0,2 мс; - мутационная проверка вручную: 14 мутаций - все роняют тесты, кроме двух эквивалентных (избыточные длина файла и опции в ключе, закрытые контрольной суммой и хэшем исходника).
Решения, принятые в M12 (подробности - REWORK_ARCHITECTURE.md, 5.24): кэшируются бинарные образы драйвера, не OpenCL C; кэш - оптимизация, любая его неудача незаметна пользователю; хэш исходника в ключе страхует от забытой версии кодгена;
required учитывается и заявленное, и вычисленное.
Не входит: ранжирование устройств по измерениям (9A); общий кэш между машинами; события вытеснения кэша; проверка на AMD/Intel. Опирается на: 9.3, 9.4, 3.B, 5.24.
Цель: одно ядро - один результат на JVM, в интерпретаторе и на устройстве, и это проверяется одним утверждением в JUnit.
Сделано:
- JVM-fallback (рантайм, с M7): последовательный цикл по global id поверх
<name>$jvm; ядра с барьером или local-памятью -RT-F01«нужно устройство»; политикаALLOWED(по умолчанию: одно предупреждениеFALLBACKна ядро с причиной и разобранным журналом сборки) /NEVER. В M13 добавлена проверка без железа, что в предупреждении есть текст ошибки драйвера. test-support:GpuAssert.sameResult(K.class, "f", args...)-<имя>$jvm(или сам метод) -> IR-интерпретатор -> устройство; целые и логика точно, вещественные в ULP (допуск устройства считается из IR: builtins таблицы 8.3 и 3 ULP на деление);Reportс выполненными и пропущенными ветвями; исключение JVM обязывает интерпретатор отказать.KernelSample(аргументы-Supplier, диапазон,expected,ulps, ветви,ignoring; JSON-загрузчик со своим мини-парсером),@GPUTest(requireDevice, параметрGpuContext),Copies,Compare.JavaToGpu.loadModule(owner, method)отдаёт IR ядра по ресурсам класса.
Критерии приёмки:
- все образцы M3–M10 проходят через
GpuAssert: 40 ядерSampleKernels, ядра группы - с результатом, посчитанным на хосте (метатест требует образец для каждого нового ядраLocalKernels); - fallback-тесты без железа (
JavaToGpuTest, фейковое устройство): отказ драйвера,NEVER,RT-F01, одно предупреждение на ядро с текстом ошибки сборки; - device-тесты по тегу:
:test-support:deviceTest- 35 ядер сверены с NVIDIA GeForce RTX 5070 в допуске из IR; - мутационная проверка вручную: 7 мутаций - все роняют тесты.
Решения, принятые в M13 (подробности - REWORK_ARCHITECTURE.md, 5.25): эталоном служит JVM, а для ядер с барьером - интерпретатор плюс expected с хоста; допуск устройства выводится из IR, а не подбирается
вручную; исключение JVM - это требование к интерпретатору, устройство в этом случае не запускается; образцы SampleKernels запускаются коротко (16 work-item-ов, группа 1), потому что пишут по несколько ячеек на work-item.
Не входит: свойство-тесты со случайными ядрами; сверка с несколькими устройствами; запись образцов в JSON. Опирается на: 9.6, 8.3, 5.25.
Одна пользовательская (быстрый старт, подмножество языка, диагностики GPU####, fallback, кэш, ограничения) и одна
архитектурная документация; публикация alpha v1 (O8: координаты); актуализация README и этого файла.
Сделано при подготовке alpha (2026-11-09):
- Пользовательское руководство
docs/USER_GUIDE.md: подключение, язык, диагностики, fallback, память, кэш, ограничения. - Самостоятельная сборка
examples/standaloneс main/test-ядрами: локальные Maven-артефакты и опубликованный plugin marker, без project-зависимостей, composite build и flatDir; явные режимы JVM и обязательного OpenCL, installDist. -
publishLocal: девять модулей и sources JAR вbuild/local-maven, без внешней публикации и изменения пользовательского Maven-кэша. -
PublishedConsumerTest: проверка потребителя через Gradle metadata и отдельно только POM, повторная сборка, processor/weaving в main/test. - Численный аудит: автодопуск учитывает тип, достижимость и выбранный вариант; максимум допусков операций явно описан как эвристика, без гарантии границы ошибки составного выражения. Регрессии и прямая device-сверка sin/cos/sqrt/fma; детали в архитектуре, 5.26.
- Строгий fallback:
Fallback.NEVERсохраняется при неудачном создании default-контекста, без исполнения$jvm; регрессии повторного вызова, scoped-контекста и reset. - README и архитектура актуализированы; требование JDK 25 для JVM Gradle-потребителя зафиксировано.
- Решить O8: итоговые координаты, версия alpha и площадка внешней публикации.
- Опубликовать alpha и проверить подключение с выбранной внешней площадки.
Все пункты — отдельные модули/вехи поверх ir. В v1 уже заложены швы (колонка 3), поэтому они не потребуют
переделки ядра.
| Что | Цель | Швы, заложенные в v1 | Примечание |
|---|---|---|---|
| Rust backend (AnyToGpu) | Rust принимает IRBinary, оптимизирует, готовит KernelHandle; языковые фронтенды остаются тонкими |
IR = единственный контракт; DeviceApi 1:1; golden-файлы как конформанс; kernelId=hash(IR) |
Сначала всё на чистой Java, без нативных зависимостей в ядре |
| Оптимизатор e-graph | egg-подобный equality saturation: e-classes, union-find, rebuild, e-matching, extraction по cost | шов OptimizerPass: IrModule→IrModule; узлы по возрастанию id; детерминизм |
Внутри — mem2reg → e-graph → обратно; чистые частичные ops не поднимать из select |
| Benchmark + ProfileStore + AutoTune | подстройка под конкретную карту по измерениям | KernelGroup, spec_const, атрибуты функции, KernelSample, режимы доступа, DeviceInfo |
Данные для тюнинга — только от пользователя; TuneSpace: work-group, @Tunable, варианты метода; verifyWithCpu; быстрый авто-benchmark + глубокий calibrate() |
| Multi-GPU + балансировщик | раздача целых запусков по разнородным картам (напр. 5070+1060+Arc B580+RX 480) | потокобезопасный GpuContext, DeviceInfo, единая точка выбора устройства, события с id устройства |
Планировщик по ожидаемому времени завершения; порог 48 % — защита от аномалий; исключение слабых карт всегда с записью в лог; разные OpenCL-платформы = отдельные контексты |
| Вендорная адаптация (AMD/NVIDIA/Intel) | автоматическая адаптация кодгена под вендора | emit(IrModule, Target), Target в ключе кэша |
Таблица правил (quirks) — данные; знания — из legacy docs/Device-Quirks.md |
| CUDA / SPIR-V (ROCm) | новые эмиттеры | интерфейс Backend, required_features |
В legacy есть заготовка CUDA (runtime/cuda) — не переносить, использовать как справку |
ASM-фронтенд [x] |
чтение байткода любых JVM-языков | IR как контракт | Сделано: frontend-asm, gpu { frontend = 'asm' } (архитектура, раздел 17, шаги A0–A6). Kotlin/Scala-специфика — позже |
| Images / samplers | Image1D/2D/3D, read/write_image |
зарезервированные type-kind'ы | Тяжёлая поверхность в типах и бэкендах |
@GpuNative |
нативные тела по backend'ам + Java-fallback | body_kind=NATIVE + таблица backend→строка у функции |
|
| Async API | submit → GpuFuture, очереди, события |
синхронный запуск изолирован за одной точкой | Нужен для multi-GPU |
| Разбиение одного запуска между картами | NDRange 80/20 | режимы доступа параметров | Требует анализа «пишет только в свой индекс» |
| Линейный байткод-транспорт IR | компактность/стриминг | колонки — единственный формат | Декодер в те же таблицы, второе представление не вводится |
| ID | Вопрос | Нужен к вехе | Предложение |
|---|---|---|---|
| O1 | Формат и место декларативного файла builtins, генератор | M1 | Закрыто (M1+M2): файл builtins/builtins.def; ir читает его в рантайме, api генерирует Gpu.java и типы |
| M7 | com.sixik.gpu.runtime.JavaToGpu (REWORK_ARCHITECTURE.md, 5.19) |
||
@Struct |
M8 | массивы Java-объектов, упаковка по AbiLayout (HostObjects); аксессоры отложены (REWORK_ARCHITECTURE.md, 5.20) |
|
| O4 | Где ABI-layout | M1 | Закрыто (M1): AbiLayout в ir |
| O5 | Имя/место IR-ресурса | M3 | Закрыто (M3): META-INF/gpu/ir/<kernelId>.gir + индекс META-INF/gpu/kernels.idx |
| O6 | JVM-реализация id-builtins | M2 | Закрыто (M2): WorkItem.run + ScopedValue, контекст WorkItemContext в api |
| O7 | Таблица «операция × тип» (T02), числовые коды IR-* |
M1 | Закрыто (M1): таблица в REWORK_ARCHITECTURE.md, 5.13; коды IR-* зафиксированы |
| O8 | Maven-координаты, группа, площадка публикации | M14 | до решения не менять io.github.deussixik |
Менее срочное: pinned/zero-copy; формат ProfileStore и инвалидация; зависимости между задачами (multi-GPU); состав
Benchmark.
Базовый путь P = processor/src/main/java/net/sixik/ga_utils/javatogpu/. Читать как справку по знаниям и крайним
случаям, не копировать структуру.
| Тема (веха) | Что посмотреть |
|---|---|
| Правила Java-подмножества (M3) | P frontend/validation/GpuSubsetValidator.java, docs/Language-Contract.md, docs/Known-Limitations.md |
| Разбор методов/struct (M3) | P frontend/parser/GpuMethodParser.java, GpuStructParser.java |
| Диагностики с позициями (M3) | P frontend/diagnostics/GpuDiagnosticRenderer.java |
| Lowering в IR (M3) | P frontend/lowering/GpuIrLowerer.java |
| Таблица intrinsics (M1/M2) | P frontend/intrinsics/GpuIntrinsicDatabase.java, GpuIntrinsicFamilyRegistry.java, P api/GPU.java (источник сигнатур и семейств) |
| Типы (M1) | P types/GpuTypeSupport.java |
| Эмиссия OpenCL C (M5) | P frontend/opencl/OpenClKernelEmitter.java |
| ABI/раскладка/упаковка (M1, M6, M8) | P runtime/opencl/OpenClStructLayout.java, OpenClVectorLayout.java, OpenClScalarLayout.java, OpenClValueLayout.java, OpenClValuePacker.java, OpenClArgumentMarshaller.java, docs/OpenCL-Data-Model.md |
| Запуск OpenCL (M6, M11) | P runtime/opencl/OpenClGpuRuntimeBackend.java, OpenClRuntimeSession.java, OpenClExecutionPlanner.java, docs/OpenCL-Runner-Contract.md |
| Подмена вызовов (M7) | P runtime/GpuMethodBodyRewriter.java (там была подмена call-site'ов; в новом дизайне подменяется тело метода) |
| Особенности устройств (вендорная адаптация, после v1) | docs/Device-Quirks.md, модуль ir-vendor-optimizer |
| Идеи оптимизаций (e-graph, после v1) | ir-optimizer/.../GpuIrConstantFoldingMaterializationProposalProvider.java и соседние provider'ы; P runtime/optimization/* |
| CUDA (после v1) | P runtime/cuda/CudaGpuRuntimeBackend.java и др. — только справка |
| ASM-фронтенд (после v1) | P frontend/asm/*, docs/ASM-Contract.md |
| Тест-кейсы | processor/src/test/java/** (323 тестовых файла в теге) — как спецификация поведения: брать сценарии, не код |
Не переносить ни в каком виде: ir-text-v1, IrGpuTypedNode с Map<String,String>, OpenClIr*Text*
-парсеры/реконструкторы, runtime/validation и runtime/diagnostics (promotion/gates/evidence/Cli),
hooks/authorization/contributors, runtime/methodtest, ir-validation (кроме идей правил), плоский пакет runtime с
256 классами, GPU.java как рукописный файл на 8000 строк, 34 *Cli классов, 73 CI-задачи processor/build.gradle.
| Риск | Смягчение |
|---|---|
javac Tree API только для javac; прокси ProcessingEnvironment в Gradle/IDE |
обход прокси проверить в M3; ECJ вне scope alpha |
| Java 25 как база отсекает пользователей на 17/21 | осознанное решение alpha (9.2) |
| Расхождения float между драйверами/вендорами | strict по умолчанию, допуски в ULP, не обещаем бит-в-бит |
| Нет железа в CI | интерпретатор + golden + фейковый DeviceApi; device-тесты по тегу на машине автора |
Реализация float→int/насыщения в OpenCL C зависит от драйвера |
проверять device-тестами на крайних значениях (M5/M6) |
| Повторный рост сложности (как в legacy) | принципы разд. 2 и verifyModuleBoundaries; не добавлять каталоги/реестры/гейты |
@Struct на хосте — объекты Java vs плоские буферы |
решено в M8: объекты + упаковка по ABI (O3 закрыт) |
- Прочитайте разд. 0–2 этого файла и разделы 5, 5.10–5.12 в
REWORK_ARCHITECTURE.md. - Продолжите текущую веху
[~](M14); если такой нет, возьмите первую[ ]. Работайте только в модулях этой вехи. - Перед кодом выпишите узлы/правила, которые затрагиваете, и где они должны появиться (валидатор + интерпретатор + кодген).
- Пишите тест раньше или вместе с кодом; golden обновляйте осознанно.
./gradlew build→ зелёный. Отметьте критерии приёмки вехи и обновите статусы здесь.- Если нужное решение не записано или противоречит принципам — не придумывайте молча: добавьте вопрос в
REWORK_ARCHITECTURE.md(разд. 15) и сообщите владельцу.