Skip to content

Commit 4a853fb

Browse files
Bind measured Gigabyte probe and validate kernel module metadata
1 parent c12cabe commit 4a853fb

19 files changed

Lines changed: 702 additions & 51 deletions

‎.github/workflows/ci.yml‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,16 @@ jobs:
2727
run: ./scripts/verify_locked_sources.sh
2828

2929
tahoe-x86-64:
30-
name: Tahoe x86_64 kext and universal userspace
30+
name: Tahoe x86_64 (${{ matrix.profile }})
3131
runs-on: macos-26-intel
32+
strategy:
33+
fail-fast: false
34+
matrix:
35+
include:
36+
- profile: placeholder
37+
hardware_config: ''
38+
- profile: gigabyte-2487-40e2
39+
hardware_config: config/hardware.gigabyte-2487-40e2.json
3240
steps:
3341
- name: Check out source
3442
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
@@ -39,4 +47,6 @@ jobs:
3947
test -d "$(xcrun --sdk macosx --show-sdk-path)/System/Library/Frameworks/Kernel.framework/Headers"
4048
test "$(basename "$(xcrun --sdk macosx --show-sdk-path)")" = "MacOSX26.5.sdk"
4149
- name: Build, test, and inspect
50+
env:
51+
HARDWARE_CONFIG: ${{ matrix.hardware_config }}
4252
run: make check

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ evidence/private/
55

66
# Build products
77
build/
8+
work/
9+
outputs/
810
DerivedData/
911
*.dSYM/
1012

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ policy:
2525
$(PYTHON) tools/check_spdx.py
2626
$(PYTHON) -m json.tool DEPENDENCIES.lock.json >/dev/null
2727
$(PYTHON) -m json.tool config/hardware.example.json >/dev/null
28+
$(PYTHON) -m json.tool config/hardware.gigabyte-2487-40e2.json >/dev/null
2829

2930
macos-build:
3031
@if [ "$$(uname -s)" != Darwin ]; then echo "macos-build requires macOS" >&2; exit 1; fi

‎README.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ RTXDarwin is an independent, open research project attempting to bring one
1212
specific Gigabyte GeForce RTX 3060 12 GB to one frozen Hackintosh target:
1313

1414
- Ryzen 7 5700X;
15-
- the exact ASUS motherboard and BIOS still to be measured;
15+
- ASUS TUF GAMING B450M-PRO II, BIOS 4002 (reported by the Linux baseline);
1616
- macOS Tahoe **26.6.2 build 25G83**;
1717
- SMBIOS **MacPro7,1**;
18-
- one exact NVIDIA PCI device/subsystem identity, still to be measured.
18+
- NVIDIA `10de:2487`, Gigabyte subsystem `1458:40e2`, VGA function 0.
1919

2020
The long-term order of proof is PCI probe → GSP/VRAM/channels → native GPU
2121
compute → NVK Vulkan Compute → one 60 Hz framebuffer → Metal compute.
@@ -29,7 +29,7 @@ under macOS yet.
2929
| Capability | Status | Evidence required to advance |
3030
|---|---|---|
3131
| Reproducible x86_64 kext build | Implemented and locally verified on Xcode 26.6 | CI must stay green |
32-
| Exact PCI/subsystem/build/SMBIOS gates | Implemented | Linux baseline supplies the real subsystem ID |
32+
| Exact PCI/subsystem/build/SMBIOS gates | Implemented; measured identity configured | Physical match/refusal tests still required |
3333
| Read-only PCI identity and BAR-length probe | Implemented in source | 20 physical Tahoe boots, IDs matched to Linux, no panic |
3434
| Root-only ABI v1 and `rtxctl probe/faults` | Implemented | Hardware output archive |
3535
| GSP, interrupts, VRAM | Not implemented | `v0.0.2-gsp` gate |
@@ -80,12 +80,29 @@ build/bin/librtxdarwin.a universal userspace client library
8080
Do not install the placeholder kext. To build for the measured test card:
8181

8282
```sh
83-
HARDWARE_CONFIG=.local/evidence/linux-baseline.json ./scripts/build_macos.sh
83+
HARDWARE_CONFIG=.local/evidence/linux-baseline.json make check
8484
```
8585

8686
The generator rejects a non-NVIDIA device, a non-Gigabyte subsystem, an
8787
unknown OpenRM 570.144 RTX 3060 ID, function other than zero, placeholders,
8888
another macOS build, or another SMBIOS.
89+
It also rejects contradictory PCI identity fields in a full baseline.
90+
Do not run a subsequent bare `make check` and install its result: that rebuilds
91+
the intentionally unmatchable placeholder. Pass `HARDWARE_CONFIG` every time.
92+
93+
The public identity-only profile `config/hardware.gigabyte-2487-40e2.json` is
94+
also built in CI, so the configured driver cannot be optimized out of every
95+
software check. Neither CI profile is hardware evidence or a release.
96+
97+
From a clean committed checkout, prepare a local ZIP with a fresh configured
98+
`make check`, module inspection, source/input hashes, and the Russian runbook:
99+
100+
```sh
101+
python3 tools/package_probe.py --config .local/evidence/linux-baseline.json
102+
```
103+
104+
Output goes under ignored `outputs/`. The packager never installs/loads code,
105+
modifies EFI, signs a kext, or includes the original hardware report/firmware.
89106

90107
## First hardware handoff
91108

‎README.ru.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,23 @@ make check
4646
placeholder ID и ни к одной карте не подключится. После получения отчёта:
4747

4848
```sh
49-
HARDWARE_CONFIG=.local/evidence/linux-baseline.json \
50-
./scripts/build_macos.sh
49+
HARDWARE_CONFIG=.local/evidence/linux-baseline.json make check
5150
```
5251

5352
Генератор разрешит только NVIDIA + известный RTX 3060 ID + Gigabyte subsystem
5453
vendor + точный subsystem device + function 0 + build 25G83 + MacPro7,1.
54+
Также проверяется, что повторяющиеся PCI ID внутри отчёта не противоречат друг
55+
другу. Для полученной карты зафиксирован профиль `10de:2487 / 1458:40e2`.
56+
57+
Важно: последующий `make check` без `HARDWARE_CONFIG` снова соберёт placeholder.
58+
Для ZIP из чистого закоммиченного checkout с повторным прогоном проверок:
59+
60+
```sh
61+
python3 tools/package_probe.py --config .local/evidence/linux-baseline.json
62+
```
63+
64+
Архив появится в `outputs/`, не содержит исходного Linux-отчёта, firmware или
65+
EFI и ничего сам не устанавливает. Kext не подписан и аппаратно не проверен.
5566

5667
## Что умеет probe-kext
5768

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"schema_version": 1,
3+
"gpu": {
4+
"vendor_id": "0x10de",
5+
"device_id": "0x2487",
6+
"subsystem_vendor_id": "0x1458",
7+
"subsystem_device_id": "0x40e2",
8+
"function": 0
9+
},
10+
"target": {
11+
"macos_version": "26.6.2",
12+
"macos_build": "25G83",
13+
"smbios": "MacPro7,1"
14+
}
15+
}

‎docs/ARCHITECTURE.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,27 @@ The probe release performs these device accesses:
7474
1. read configuration dword 0x00 for vendor/device;
7575
2. read configuration dword 0x08 for revision/class;
7676
3. read configuration dword 0x2c for subsystem vendor/device;
77-
4. ask IOPCIFamily for each BAR's existing `IODeviceMemory` descriptor;
78-
5. read each present BAR's low flag nibble.
77+
4. retain the existing `IODeviceMemory` registry array and read each matching
78+
`IOMemoryDescriptor`'s length/tag (the tag's low byte is the BAR register);
79+
5. read each present memory BAR's low flag nibble, or the low two bits for I/O.
80+
81+
The PCI `getDeviceMemoryWithRegister`/`getDeviceMemoryWithIndex` accessors are
82+
not used: Apple's [IOPCIDevice implementation](https://github.com/apple-oss-distributions/IOPCIFamily/blob/main/IOPCIDevice.cpp)
83+
may change tunnel link-power policy in those accessors. Descriptor types are
84+
checked as `IOMemoryDescriptor`, consistent with the objects created by
85+
[`IOPCIBridge::constructRange`](https://github.com/apple-oss-distributions/IOPCIFamily/blob/main/IOPCIBridge.cpp).
86+
Missing descriptors report length/flags zero, not a measured zero-size BAR.
87+
Linux resource flags are `IORESOURCE_*`, not the Darwin raw BAR flag bits, and
88+
must not be compared directly. A 64-bit BAR's upper register is not another BAR.
89+
90+
Module metadata follows the [Swift Build/Xcode generator](https://github.com/swiftlang/swift-build/blob/990525f9dd8a29f17448b92bef69ece0a9579f2d/Sources/SWBTaskConstruction/TaskProducers/BuildPhaseTaskProducers/SourcesTaskProducer.swift#L2212):
91+
`kmod_info.start/stop` point to libkmod's `_start/_stop` wrappers; the optional
92+
custom callbacks remain null. `tools/inspect_kext.py` checks these pointers in
93+
the linked Mach-O, as well as the plist and configured identity. This is not a
94+
kernel dependency-resolution, signing, loadability, or hardware test.
95+
96+
`RTXDarwinMMIOWrites=0` is a declaration of this code's policy, not an
97+
instrumented hardware counter or independent evidence of bus traffic.
7998

8099
It deliberately does not call PCI config-write methods, map methods, memory or
81100
bus-master enable methods, I/O port writes, DMA APIs, interrupts, or reset.

‎docs/BRINGUP.ru.md‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,14 @@ path/to/ocvalidate path/to/EFI/OC/config.plist
8989
После compute IOMMU тестируется отдельной матрицей. Не смешивать изменение IOMMU
9090
с первой загрузкой нового kext.
9191

92+
Если рабочий Linux сейчас использует ReBAR/IOMMU, не менять его настройки ради
93+
сборки kext на MacBook. До физического эксперимента сохранить локально исходный
94+
BIOS-профиль и отдельно подготовить указанный выше тестовый профиль. После
95+
изменения ReBAR/Above 4G заново собрать Linux baseline в **новый файл**: размеры
96+
BAR могут измениться. Сравнивать Darwin нужно с отчётом того же BIOS-профиля,
97+
а не с исходной конфигурацией. Сам read-only probe не включает и не отключает
98+
ReBAR/IOMMU.
99+
92100
## 4. Установка Tahoe
93101

94102
Устанавливать только на выделенный SATA SSD. При выборе диска физически
@@ -126,9 +134,7 @@ OpenCore `MinKernel`/`MaxKernel` для kext зафиксировать на Dar
126134
gitignored `.local/evidence`:
127135

128136
```sh
129-
HARDWARE_CONFIG=.local/evidence/linux-baseline.json \
130-
./scripts/build_macos.sh
131-
make check
137+
HARDWARE_CONFIG=.local/evidence/linux-baseline.json make check
132138
```
133139

134140
Проверить generated match:
@@ -141,6 +147,18 @@ file build/RTXDarwin.kext/Contents/MacOS/RTXDarwin
141147
В `IOPCIPrimaryMatch` и `IOPCISubsystemMatch` должны стоять ID именно из Linux.
142148
Не ставить placeholder build.
143149

150+
Каждая сборка без `HARDWARE_CONFIG` снова создаёт placeholder. Чтобы случайно
151+
не взять его после тестов, можно собрать проверяемый ZIP одной командой из
152+
чистого закоммиченного checkout:
153+
154+
```sh
155+
python3 tools/package_probe.py --config .local/evidence/linux-baseline.json
156+
```
157+
158+
Kext в архиве **не подписан**. Проверка сборки на ARM MacBook не доказывает
159+
разрешение Intel kernel dependencies или принятие kext загрузчиком Tahoe.
160+
Никакой автоматической установки или изменения политики защиты нет.
161+
144162
Копировать kext только в `EFI/OC/Kexts` тестового Tahoe SSD и добавить его в
145163
`Kernel/Add`; SSV и `/System/Library/Extensions` не изменять. Сначала загрузить
146164
`Tahoe Safe` и проверить, что система по-прежнему восстанавливается.
@@ -166,6 +184,12 @@ log show --last boot --predicate 'eventMessage CONTAINS "RTXDarwin"'
166184
5. проверка отказа при `rtxd=off`, неверном subsystem ID и non-root client;
167185
6. подписанный sanitized evidence manifest с commit SHA.
168186

187+
Сравнивать длины memory BAR 0/1/3 с Linux при одинаковом BIOS-профиле. Linux
188+
resource flags и raw BAR flags Darwin — разные представления. BAR 2/4 могут
189+
быть старшими половинами 64-bit BAR, а BAR 5 — I/O port range. Если IOPCIFamily
190+
не публикует дескриптор диапазона, probe вернёт нули: это **не** доказательство
191+
отсутствия BAR. Такое расхождение требует разбора и не считается приёмкой.
192+
169193
Если есть panic, зависание, исчезновение Linux-диска или нестабильность PCIe,
170194
сразу прекратить серию, загрузить `Tahoe Safe`/Linux и сохранить текстовые логи.
171195
Не повторять Active-режим автоматически.

‎docs/PROBE-PACKAGE.ru.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# RTXDarwin: экспериментальный probe-пакет
2+
3+
**EXPERIMENTAL — MAY PANIC OR HANG THE GPU.** Kext не подписан. На физической
4+
RTX этот пакет ещё не проверен. Это не релиз `v0.0.1-probe` и не готовый драйвер.
5+
6+
## Что внутри
7+
8+
- `RTXDarwin.kext`: x86_64, только read-only probe, точные ID в `hardware.json`;
9+
- `rtxctl`: универсальная CLI arm64/x86_64; на MacBook kext не загружать;
10+
- `manifest.json`: commit исходников, SHA-256 входного JSON, toolchain,
11+
результат программных проверок и hashes файлов;
12+
- `software-checks.txt`: вывод свежего `make check`, локальные пути заменены;
13+
- `SHA256SUMS`: контрольные суммы содержимого архива;
14+
- `BRINGUP.ru.md`: полный runbook. Firmware, VBIOS, исходного отчёта и EFI нет.
15+
16+
После распаковки в каталоге пакета:
17+
18+
```sh
19+
shasum -a 256 -c SHA256SUMS
20+
./rtxctl --version
21+
```
22+
23+
Суммы обнаруживают повреждение файлов, но не заменяют доверенную цифровую
24+
подпись. Программные тесты не доказывают, что kernel loader примет kext.
25+
26+
## Стоп перед установкой
27+
28+
Нужны отдельный тестовый SATA SSD, физическое присутствие, работающий
29+
`Tahoe Safe`/Linux и проверенный SSH. Linux-диск и его EFI не изменять.
30+
Цель строго Tahoe 26.6.2 / 25G83 / MacPro7,1. Поле `target` в Linux-отчёте
31+
обозначает желаемую конфигурацию и **не подтверждает** установленную macOS.
32+
33+
Пакет не содержит готовой EFI или автоматической команды установки. Если
34+
базовая Tahoe ещё не загружается стабильно, остановиться на подготовке стенда.
35+
Не менять SIP/SSV, не прошивать VBIOS, не обновлять BIOS и не менять Linux-драйвер
36+
ради этого пакета. Зафиксированные NVIDIA 570.144 firmware будут нужны только
37+
на будущем GSP-этапе; probe их вообще не использует.
38+
39+
После подготовки/проверки тестовой EFI по `BRINGUP.ru.md` сначала проверить
40+
восстановительную загрузку `rtxd=off`; затем физический probe с `rtxd=probe`.
41+
`gsp`, `compute`, `fb`, `metal` в этой версии не захватывают карту.
42+
43+
В Tahoe Probe получить **новые** результаты и передать их отдельно:
44+
45+
```sh
46+
sudo ./rtxctl probe --json
47+
sudo ./rtxctl faults --json
48+
ioreg -l -w0 -r -c RTXDarwin
49+
```
50+
51+
Ожидаются только `mode=probe`, `state=probed`, capability `probe` и
52+
`vramBytes=0`. Ноль VRAM здесь намеренный: этот этап ещё не инициализирует VRAM.
53+
Никаких успешных GSP/compute/Metal результатов пакет не генерирует.
54+
55+
Сравнивать memory BAR с Linux при том же BIOS-профиле; 16-ГиБ aperture не равен
56+
16 ГиБ физической VRAM. Неполный/несовпадающий BAR-отчёт требует разбора, а не
57+
автоматического признания успеха. Linux I/O resource flags и Darwin BAR flags
58+
нельзя сравнивать как одинаковые числа.
59+
60+
При panic, зависании или потере изображения прекратить эксперимент, выбрать
61+
`Tahoe Safe`/Linux и сохранить очищенный лог. Не повторять запуск автоматически.
62+
До `v0.0.1-probe` остаются 20 аппаратных загрузок и отрицательные проверки.

‎driver/Module.cpp‎

Lines changed: 9 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,15 @@
33

44
extern "C" {
55

6-
// libkmod's entry points consult these slots. The kernel's kext loader uses
7-
// them for generated C++ constructor/destructor dispatch when required.
8-
kmod_start_func_t *_realmain = nullptr;
9-
kmod_stop_func_t *_antimain = nullptr;
6+
extern kern_return_t _start(kmod_info_t *info, void *data);
7+
extern kern_return_t _stop(kmod_info_t *info, void *data);
108

11-
kmod_info_t kmod_info = {
12-
nullptr,
13-
KMOD_INFO_VERSION,
14-
UINT32_MAX,
15-
"dev.onedeadmachine.RTXDarwin",
16-
"0.0.0",
17-
-1,
18-
nullptr,
19-
0,
20-
0,
21-
0,
22-
nullptr,
23-
nullptr,
24-
};
9+
// Match Xcode's generated module info: the kmod entry points are libkmod's
10+
// wrappers, even when this IOKit driver has no custom start/stop callbacks.
11+
__attribute__((visibility("default")))
12+
KMOD_EXPLICIT_DECL(dev.onedeadmachine.RTXDarwin, "0.0.0", _start, _stop)
13+
__attribute__((visibility("hidden"))) kmod_start_func_t *_realmain = nullptr;
14+
__attribute__((visibility("hidden"))) kmod_stop_func_t *_antimain = nullptr;
15+
__attribute__((visibility("hidden"))) int _kext_apple_cc = __APPLE_CC__;
2516

2617
} // extern "C"

0 commit comments

Comments
 (0)