Skip to content

Latest commit

 

History

History
778 lines (604 loc) · 101 KB

ROADMAP.md

File metadata and controls

778 lines (604 loc) · 101 KB

ROADMAP

Дорожная карта новой версии проекта (com.sixik.gpu). Документ рассчитан на то, чтобы человек или нейросеть, не знавшие контекста, сразу поняли, что строится, по каким правилам и что делать дальше.

Состояние на 2026-11-09: M0–M13 выполнены, M14 в работе.


0. Как пользоваться этим файлом

Порядок чтения: 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.


1. Что строим

В одном абзаце. Пользователь пишет GPU-код на Java (строго подмножество, не произвольный код); библиотека на этапе сборки превращает его в компактный бинарный IR, а в рантайме (JIT) генерирует OpenCL C под конкретное устройство, компилирует, кэширует и запускает. Если GPU нет — тот же метод выполняется на JVM. Архитектура рассчитана на будущий перенос ядра на Rust (AnyToGpu) без переписывания дизайна.

Ключевая боль, ради которой всё затеяно: адаптация кода под разные видеокарты (AMD / NVIDIA / Intel) и распределение работы между несколькими, в т.ч. разнородными GPU. Это будущие планы (разд. 8), в v1 закладываются только швы.

Цели 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-функции

Не-цели v1 (сознательно НЕ делаем)

Оптимизатор (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, строки.


2. Нерушимые принципы (проверьте себя перед каждым коммитом)

  1. Данные плоские (DOD). IR и все таблицы ядра — SoA на примитивных массивах (int[] op, type, a, b, c + боковые таблицы). Ссылки — целочисленные id, не объекты. Строки интернируются. Никаких Object-графов, Map<String,String> как модели, reflection, иерархий узлов.
  2. Логика — статические функции над данными. Запрещены Registry / Factory / Provider / Service / Catalog / Contributor / Hook-паттерны в ядре. Разрешены ровно три точки расширения: Backend, OptimizerPass, EventListener (разд. 10 архитектуры).
  3. Нет глобального изменяемого состояния в ядре. Контекст (GpuContext) — явный объект. Единственное «ambient»-место — тонкий хост-фасад пользователя (ленивый default-контекст + scoped override).
  4. Ошибки — значения. Ядро (ir, codegen-opencl, ir-interpreter, runtime-core) возвращает Result/список Diagnostic (код + позиция + сообщение + подсказка). Исключения — только на публичной границе (GpuException с полным отчётом) и во фронтенде для javac Messager.
  5. Детерминизм. Один и тот же вход → побайтово тот же IR, хэш и OpenCL C. Нет зависимости от порядка HashMap, String.hashCode, времени, пути.
  6. Один канонический IR. Запрещены текстовый IR, обратный парсинг IR в исходник, параллельные представления. Текстовый дамп (в tools) — только для людей и golden-тестов, в IR не парсится обратно.
  7. IR vendor-neutral и backend-neutral. Вендорная/бэкендовая специализация — только на выходе, в кодгене ( emit(IrModule, Target)).
  8. Нет кастов в IR и в исходнике ради типов. Знак — метка типа; опкоды полиморфны; неявных приведений нет; convert только явный. Касты к unsigned допустимы лишь внутри сгенерированного C (чтобы дать Java-семантику).
  9. Java-семантика целых и float→int гарантирована контрактом IR (оборот знаковых, маскирование сдвигов, насыщение, NaN→0); деление на ноль — «не определено, без падения».
  10. JVM ≡ GPU по конструкции. Подмножество языка и валидатор исключают расхождения (векторы immutable; @Struct без aliasing). Float сравнивается «в ULP» из таблицы builtins, точного равенства не обещаем.
  11. Платформа: Java 25, FFM (java.lang.foreign) для OpenCL, без LWJGL и сторонних нативов. ASM — только в weaver.
  12. Границы модулей проверяются сборкой. Не обходите verifyModuleBoundaries — меняйте граф осознанно (и запись в REWORK_ARCHITECTURE.md, разд. 11).
  13. Единый источник истины. Builtins — один декларативный файл; Gpu.java, типы и таблицы генерируются, руками не правятся.
  14. Каждый новый узел IR / правило / публичный метод — с тестом, и узел IR сразу в трёх местах: валидатор, интерпретатор, кодген.

3. Архитектура кратко

[Сборка пользователя]   @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.*.


4. Шпаргалка ключевых решений (подробности — в архитектуре)

Тема Решение Где
Режим 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

5. Глоссарий

  • 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-версии.

6. Definition of Done — для любой вехи

  • ./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"), по умолчанию пропускаются.


7. Вехи v1

Стратегия: тонкий вертикальный срез (M1–M7: baseline-ядро от исходника до запуска), затем ширина (M8–M13: по одной возможности, каждая — расширение IR → интерпретатор → кодген → рантайм → тесты). Всегда есть работающая сборка.

Baseline-подмножество среза: скаляры, массивы, if/for/while/do-while/switch, арифметика/сравнения/логика/тернарный, helper-вызовы, builtins, FloatPtr — позже (M9).

M0 — Сброс [x]

Тег legacy-alpha5; старый код удалён; скелет из 10 модулей; Gradle 9.8.1, JDK 25, JUnit 6.1.3, ASM 9.11.1; verifyModuleBoundaries (проверено негативными тестами). Коммит 5ce86b90.

M1 — Модуль ir [x]

Цель: канонический 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.md 5.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).

M2 — Модуль api [x]

Цель: публичный язык GPU-кода.

Сделано (api/src):

  • Аннотации @Kernel(inline, optLevel, workgroup, required, fallback), @DeviceFunction, @Struct(alignment), @Global(constant), @Local, @Constant, @WorkGroup(x,y,z) (Retention CLASS — их читает 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.

M3 — Модуль frontend-java [x]

Цель: @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.JavaCompiler in-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.

M4 — Модуль ir-interpreter [x]

Цель: эталонная семантика 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.16 REWORK_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.

M5 — Модуль codegen-opencl [x]

Цель: 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.

M6 — Модуль runtime, ядро запуска [x]

Цель: найти устройство, скомпилировать, залить буферы, запустить, забрать результат — синхронно.

Сделано (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.

M7 — weaver + gradle-plugin + хост-фасад: первое ядро end-to-end [x]

Цель: обычный вызов 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.
  • testFixtures weaver: 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 закрыт).

M8 — Векторы + @Struct + ABI [x]

Цель: векторы и @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.

M9 — Pointer-типы и address spaces [x]

Цель: ссылки 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 IR pointers.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.

M10 — Local memory, barrier, atomics [x]

Цель: группы 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: флаги builtin sync и 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.

M11 — Prepared launcher и GpuBuffer [x]

Цель: повторные запуски одного ядра без повторной подготовки; владение памятью вместо флагов-масок.

Сделано:

  • 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 нс (подготовленный), GpuBuffer 223 против 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.

M12 — Дисковый кэш, политика устройства, Timings, варианты по required [x]

Цель: повторный запуск процесса не платит за компиляцию драйвером; вариант ядра выбирается по возможностям устройства; тайминги и счётчики кэша доступны через 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.

M13 — JVM-fallback и test-support [x]

Цель: одно ядро - один результат на 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.

M14 — Документация и alpha [~]

Одна пользовательская (быстрый старт, подмножество языка, диагностики 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 и проверить подключение с выбранной внешней площадки.

8. После v1 (backlog)

Все пункты — отдельные модули/вехи поверх 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 компактность/стриминг колонки — единственный формат Декодер в те же таблицы, второе представление не вводится

9. Открытые вопросы

ID Вопрос Нужен к вехе Предложение
O1 Формат и место декларативного файла builtins, генератор M1 Закрыто (M1+M2): файл builtins/builtins.def; ir читает его в рантайме, api генерирует Gpu.java и типы
O2 Имя хост-фасада закрыт в M7 M7 com.sixik.gpu.runtime.JavaToGpu (REWORK_ARCHITECTURE.md, 5.19)
O3 Хост-представление @Struct закрыт в M8 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.


10. Карта legacy (git show legacy-alpha5:<путь>)

Базовый путь 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.


11. Риски

Риск Смягчение
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 закрыт)

12. Быстрый старт для исполнителя (в т.ч. нейросети)

  1. Прочитайте разд. 0–2 этого файла и разделы 5, 5.10–5.12 в REWORK_ARCHITECTURE.md.
  2. Продолжите текущую веху [~] (M14); если такой нет, возьмите первую [ ]. Работайте только в модулях этой вехи.
  3. Перед кодом выпишите узлы/правила, которые затрагиваете, и где они должны появиться (валидатор + интерпретатор + кодген).
  4. Пишите тест раньше или вместе с кодом; golden обновляйте осознанно.
  5. ./gradlew build → зелёный. Отметьте критерии приёмки вехи и обновите статусы здесь.
  6. Если нужное решение не записано или противоречит принципам — не придумывайте молча: добавьте вопрос в REWORK_ARCHITECTURE.md (разд. 15) и сообщите владельцу.