basalt

Это не скромность. Модель задержек, общая для проверяющего и планировщика, — это именно то место,
где прячется ошибочное число, поэтому вторая карта — самое полезное, что кто-либо может внести.

</details>

## Как это работает

Всё опирается на два оракула, оба из которых — штатные бинарники NVIDIA, запускаемые как внешние процессы. Никакие исходники, заголовки или библиотеки NVIDIA не используются и не распространяются.

| Оракул | Вызов | Что даёт |
| :--- | :--- | :--- |
| **Эталон** | `ptxas` → cubin → `nvdisasm -c -hex` | Кодировки, которые компилятор вендора реально выдаёт. Семантика вне сомнений. |
| **Зонд** | `nvdisasm -b SM120a` по сырым байтам | Декодирует слова, которые `ptxas` никогда не выдаст, превращая пространство кодировок в нечто, что можно искать, а не угадывать. |

Именно зонд-оракул имеет значение. Инструмент, ограниченный выводом компилятора, может лишь заново открыть то, что компилятор уже делает. Подача синтезированных 128-битных слов напрямую в декодер означает, что набор инструкций можно *измерить*.

Ни одному из оракулов не нужен GPU, поэтому вся база данных инструкций пересобирается в CI на любой машине.

### Выведение кодировки путём её изменения

basalt не читает таблицу опкодов ни из какого источника. Он берёт кодировку, которая собралась, переворачивает один бит, декодирует результат и записывает, что изменилось. Бит, который меняет регистр назначения, — это бит назначения; бит, который меняет мнемонику, — селектор; бит, который не меняет ничего наблюдаемого, инертен.

При запуске с `IADD R5, R5, 0x2a` измерение выглядит так:```
operand[0]  bits 16:23     flip 16 -> R4,  flip 17 -> R7      destination register
operand[1]  bits 24:31     plus bit 72, which negates it      source register
operand[2]  bits 32:63     flip 32 -> 0x2b, flip 33 -> 0x28   32-bit immediate
opcode      bits 2, 4, 12:15
inert       36 bits        no observable effect
invalid     11 bits        the decoder rejects the mutation

<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">Использование</h3>
<!-- /wp:heading -->

**Интеграция со службами с ключами**

Библиотека включает интеграцию с функцией служб с ключами .NET. Это полезно в мультитенантных сценариях, когда один и тот же тип службы регистрируется несколько раз с разными ключами (например, для каждого тенанта). Когда служба зарегистрирована с ключом, контекст тенанта не будет использоваться для её разрешения. Вместо этого вы можете использовать ключ для разрешения конкретной регистрации.

- `WithKeyedServiceLifetimeScope` — метод расширения, который позволяет создать область службы на основе типа службы, зарегистрированного с ключом.
- `WithKeyedServiceResolution` — метод расширения, который позволяет разрешить службу с ключом, используя её ключ.

```csharp
services.AddSingleton<IService>(factory => ...);
// ...
using var scope = services.CreateScope();
var service = scope.ServiceProvider.GetRequiredService<IService>(); // resolved from the tenant context

services.AddKeyedSingleton<IService>("key", factory => ...);
// ...
using var scope = services.WithKeyedServiceLifetimeScope(typeof(IService), "key");
var service = scope.ServiceProvider.GetRequiredService<IService>();

using TenantCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMultiTenant<Tenant>()
    .WithIdentityResolver<CustomTenantResolver>()
    .WithDatabaseResolver<DatabaseResolver>();

var app = builder.Build();

public class CustomTenantResolver : ITenantResolver
{
    public ValueTask<string> ResolveAsync(object? context)
    {
        if (context is HttpContext httpContext)
        {
            var tenant = httpContext.Request.Headers["X-Tenant-ID"].ToString();
            return ValueTask.FromResult(tenant);
        }

        return ValueTask.FromResult(string.Empty);
    }
}

### Или как пакет

`pip install basalt-sass` устанавливает CLI, библиотеку и все три таблицы измерений,
без зависимостей времени выполнения. Используйте это, если на машине уже есть CUDA; описанный выше checkout
подойдёт, если её нет, или если вы хотите воспроизвести измерения.```bash
pip install basalt-sass
basalt doctor
basalt verify kernel.cubin

Пересоздайте базу данных инструкций с нуля или выполните запрос к закоммиченной:```bash
python -m basalt.cli build-isa          # harvest, probe, write src/basalt/data/isa/sm_120a.json
python -m basalt.cli isa --stats
python -m basalt.cli isa IMAD.WIDE.U32  # one form, with its measured field layout
python -m basalt.cli isa --opcode QMMA  # every form of one opcode

[No input text provided to translate.]```console
$ python -m basalt.cli verify nvjpeg.sm_120.cubin
  25 kernels, 0 with an error
  7984 instructions in 789 blocks, 11580 dependencies checked across blocks: 0 errors, 3 warnings
  pair data: 3957 pairings from 25634 kernels, 427 producers with enough observations to use
  latency model: measured on NVIDIA GeForce RTX 5070 Ti

<details>
<summary><b>Каждая команда и для каких нужна карта</b></summary>

<br/>

| Команда | Что делает | Нужна GPU |
| :--- | :--- | :--- |
| `doctor` | Проверяет оба оракула по полному циклу | нет |
| `build-isa` | Собирает данные и зондирует, записывает базу инструкций | нет |
| `isa` | Запрашивает форму, опкод или покрытие | нет |
| `validate-isa` | Доказывает, что измеренные поля можно записывать насквозь | нет |
| `mine-stalls` | Изучает требования для каждой пары на основе того, что планирует компилятор | нет |
| `verify` | Проверяет управляющие биты cubin на наличие конфликтов данных | нет |
| `schedule` | Назначает управляющие биты cubin с нуля и проверяет результат | нет |
| `assemble` | Кодирует текст SASS или целый cubin и читает его обратно для проверки | нет |
| `measure` | Замеряет задержку инструкций на реальном кремнии | **да** |
| `probe-stalls` | Находит требуемый stall, намеренно ломая программы | **да** |

</details>

Всё, что умеет CLI, доступно для импорта, а библиотечный интерфейс с запускаемыми примерами
находится в [`docs/API.md`](https://github.com/sunnypatell/basalt/blob/main/docs/API.md).

И два элемента контроля, которые не дают остальному врать. Первому нужна карта; второму нужны
поставляемые библиотеки и вообще никакого оборудования:```bash
python scripts/roundtrip_corpus.py    # reschedule all 441 corpus kernels, run both on the GPU

python scripts/fetch_toolchain.py --libs                  # ~1.2 GB, no admin, nothing on PATH
python scripts/audit_shipped.py --libs third_party/cuda/13.3.1/libs

## Измерено, а не предположено

Числа здесь выводятся инструментарием и пересоздаются из чистого checkout. Команды выше — источник истины; эти таблицы — снимки.

**База данных инструкций.** Каждая запись содержит кодировку, которая действительно ассемблировалась, и сборку компилятора, которая её произвела.

| База данных инструкций | Количество |
| :--- | ---: |
| Формы инструкций | 345 |
| Различные опкоды | 90 |
| Формы с полной картой операндов | 339 |
| Формы тензорных ядер | 46 |
| Собрано с помощью | `ptxas` V13.3.73 |

Покрытие тензорных инструкций — там, где живёт низкоточное железо: `HMMA` и `IMMA`, `QMMA` для типов FP8, FP6 и FP4, включая асимметричные пары операндов, формы с масштабным коэффициентом `QMMA.SF` и `OMMA.SF`, несущие экспоненту на блок, разрежённые `IMMA.SP`, а также инструкции перемещения матриц `LDSM`, `STSM` и `MOVM` во всех формах, включая транспонирующие варианты.

**Задержка на RTX 5070 Ti.** 70 SM, каждая аппроксимация R² ≥ 0.9998. Измерено путём замера времени зависимых цепочек и вычисления наклона; длина цепочки считывается из скомпилированного SASS, а не предполагается.

| Инструкции | Циклы |
| :--- | ---: |
| `IMAD` `IADD3` `FFMA` `FADD` `FMUL` `LOP3` `SHF` | 4 |
| `POPC` | 18 |
| `I2FP` + `F2I` вместе | 24 |
| `MUFU` | 44 |
| `DADD` `DFMA` | 64 |

Три из них противоречат предполагаемой модели, поставлявшейся с basalt: `DADD` предполагался равным 48, `POPC` — 4, а каждая конверсия — 6, тогда как для полного цикла измерено 24.

<img src="https://raw.githubusercontent.com/sunnypatell/basalt/main/docs/assets/chart-latency.svg" alt="Три задержки, которые basalt предполагал до измерения их против того, что сообщил кремний: сложение fp64 предполагалось 48, а измерено 64, POPC предполагался 4, а измерен 18, и полный цикл конверсии I2FP плюс F2I предполагался 12, а измерен 24.">

Предполагаемая модель задержек — это не малое приближение измеренной; в этом весь аргумент в пользу измерения.

**И stall со значением ноль — это не ноль циклов.** Это отдельная безопасная кодировка, которая ожидает незавершённые результаты, и обходится примерно в 37 циклов там, где запланированная инструкция стоит 4. Вот почему `ptxas -O0` генерирует полностью обнулённое управляющее слово, и код при этом по-прежнему вычисляет корректно — примерно в девять раз медленнее.

| `stall` | циклов/инструкция | результат |
| ---: | ---: | :--- |
| **0** | **36.85** | **корректно** |
| 1 | 4.88 | неверно |
| 2 | 4.88 | неверно |
| 3 | 5.88 | неверно |
| 4 | 6.88 | корректно |

**Он согласуется с компилятором производителя по каждому ядру в корпусе.** Каждое ядро, которое `ptxas` собирает из корпуса, проверяется против его собственного планирования на каждом уровне оптимизации, который выполняет планирование: 30 421 зависимость, ноль ошибок. Этот прогон выполняется в CI при каждом пуше, и каждая ошибка моделирования, которую допустил этот проект, была поймана именно им, а не рассуждениями.

**Вердикты совпадают с кремнием.** Для каждого кодируемого stall на зависимом производителе статический ответ basalt и то, что реально вычисляет железо, согласуются, включая случай нуля. Это закреплено тестом, а не утверждается здесь. Полные доказательства, включая три независимых метода для требуемого stall и исправления, сделанные по ходу, — в [findings](https://github.com/sunnypatell/basalt/blob/main/docs/FINDINGS.md).

**И когда он говорит, что расписание небезопасно, кремний соглашается.** Возьмите собственное рабочее расписание производителя для 233 ядер, укоротите в каждом по одной реальной зависимости и сравните вердикт basalt с тем, что вычисляет GPU: 79, которые он назвал сломанными, действительно были сломаны, и **ничего из того, что он назвал безопасным, не вычислило неверный ответ**. Это число начиналось с 34 пропущенных, а не с нуля, и в [findings](https://github.com/sunnypatell/basalt/blob/main/docs/FINDINGS.md) сказано, в чём была причина и во что обошлось её исправление в ложных срабатываниях, потому что прогон, сообщающий только итоговую цифру, стоит меньше, чем тот, который сообщает свою первую.

## Он тоже умеет назначать управляющие биты

Верификатор отвечает на вопрос, безопасно ли расписание. Планировщик отвечает на вопрос, каким было бы безопасное расписание, исходя из тех же измерений: он отбрасывает каждый управляющий бит, созданный `ptxas`, вычисляет свои, возвращает результат верификатору, а затем запускает его на GPU рядом с версией того же ядра от производителя.

При прогоне по всему корпусу на карте, на каждом уровне оптимизации, который создаёт расписание, все 439 сопоставимых ядер дают побайтово идентичные результаты расписанию производителя, причём управляющие биты basalt вычислил сам. Те 2, что исключены, читают часы и идентификатор сетки, так что не согласуются даже сами с собой, и в [findings](https://github.com/sunnypatell/basalt/blob/main/docs/FINDINGS.md) об этом сказано прямо, а не вписано в проценты.

Этот контроль — причина, по которой можно доверять всему остальному. Проверяющий и планировщик читают одну и ту же модель задержек, поэтому ошибочная запись в ней удовлетворяет обоих одновременно, и они согласуются друг с другом, оставаясь оба неправыми. Только у кремния нет интереса в этом споре. Долгое время прогон планировщика по семи написанным вручную ядрам проходил семь из семи; прогон по трёмстам нашёл сорок одно неправильное ядро, и каждое последующее исправление модели родилось из наблюдения за тем, как движется это число.

Именно из этого цикла и появились настоящие баги. Stall, проведённый вне окна между производителем и его потребителем, ничего не стоит, и трата его там завершает поиск программой, которая всё ещё слишком коротка. Stall, привязанный к безопасной кодировке, перезаписывался более поздним проходом, подменяя гарантию маленьким числом. Операнды fp64 занимают пары регистров, и в мнемонике ничто об этом не говорит, поэтому половина каждой зависимости fp64 была невидима и для проверяющего, и для планировщика. Предикат, используемый как guard инструкции, требует тринадцать циклов там, где тот же предикат, читаемый как данные, требует пять, потому что guard должен быть разрешён до того, как инструкция вообще будет выдана. А ожидание на scoreboard не улаживает зависимость полностью: производитель всё ещё должен небольшой собственный stall — два цикла для сложения fp64, — и на один цикл меньше — это тихая ошибка. Ни одна из этих проблем не была найдена рассуждениями; каждая была найдена запуском вывода и получением неверного числа.

> [!NOTE]
> **1.0, и конкретно о том, что это значит.** Что сделано: оба оракула, база данных инструкций с доказанно записываемыми полями, проверяющий опасности поверх реального графа потока управления, задержка, измеренная на одном SKU тремя независимыми методами, планировщик, который прогоняет каждое сопоставимое ядро корпуса через железо туда и обратно с побайтовым совпадением, и аудит 2 762 поставляемых ядер, исключённых из всех таблиц, которые читает проверяющий. Что не сделано: 12 ядер корпуса, невыполнимых по построению, и 2, чей вывод производителя не детерминирован, — все перечислены в findings; десять опкодов по-прежнему несут предполагаемую задержку вместо измеренной, и ни один из них никогда не был производителем ни в одном из двух корпусов кода; и измерен только один GPU, а [finding 28](https://github.com/sunnypatell/basalt/blob/main/docs/FINDINGS.md) показывает, что это значит меньше, чем звучит. Где что-то выведено, а не измерено, инструментарий говорит об этом, а не округляет до факта. См. [roadmap](https://github.com/sunnypatell/basalt/blob/main/docs/ROADMAP.md) и [method](https://github.com/sunnypatell/basalt/blob/main/docs/METHOD.md).

## Структура репозитория

<details>
<summary><b>Где что находится</b></summary>

<br/>```
src/basalt/
  toolchain.py     Locating and driving ptxas / nvdisasm
  encoding.py      The 128-bit instruction word and its control fields
  disasm.py        Both oracles: cubin ground truth and raw-word probe
  harvest/         PTX corpus generation and encoding extraction
  probe/           Differential bit probing and field inference
  isa/             The generated instruction database and its builder
  asm/             The assembler, and the ELF reader that rewrites words in place
  sched/           Assigning the control bits, and costing the result
  verify/          Register def-use analysis, hazard model, latency checking
  gpu/             Driver-API bindings and the latency measurement harness
src/basalt/data/   The measured tables, inside the package so an installed copy
                   has them: the ISA database, the latency model and the mined
                   stall requirement
docs/              Findings, method, the Python API, roadmap, artwork sources
scripts/           Toolchain fetch, asset rendering, drift check, and the two
                   hardware controls: the corpus round trip and the agreement sweep
tests/             Unit tests, plus toolchain- and GPU-marked suites