Руководство

Если что-то пошло не так

Каждый запуск оставляет лог. Начинайте с него: logs/last.log после запуска на телефоне, logs/qemu-open.log или logs/qemu.log после QEMU. Каждый шаг железа при сбое пишет одну строку с названием шага и регистра, так что лог почти всегда говорит, что случилось.

Прежде всего

make doctor          # чего не хватает этой машине и подключённому телефону; только чтение
make config          # что не так с .config и почему
./xl state           # где сейчас телефон: android, fastboot, loader или absent
./xl log             # последний лог загрузчика с телефона

Сборка

Вы видите Что делать
make doctor пишет, что чего-то нет установите, как сказано в строке, откройте новый терминал и запустите снова
make kernel останавливается на шагах kext symbol-set так и должно быть: эти ошибки допускаются. Любая другая ошибка останавливает сборку и настоящая
make loader просит ваш образ восстановления для QEMU соберите открытый загрузчик (make loader-open) или распакуйте свой образ (make unpack IPSW=...)
sysimage/unpack.sh не принимает файл это должен быть ровно iPhone10,3,iPhone10,6_16.5_20F66_Restore.ipsw, 6 165 698 198 байт
кончилось место сборке пользовательского пространства нужно около 12 ГБ свободного места

QEMU

Вы видите Что делать
run.sh: no UEFI firmware found задайте QEMU_EFI и QEMU_VARS (в macOS — edk2-aarch64-code.fd и edk2-arm-vars.fd из Homebrew)
timeout: command not found в macOS brew install coreutils
чёрное окно больше двух минут с полным пользовательским пространством дайте QEMU не меньше 7 ГБ памяти и подождите: логотип Apple — примерно через минуту, рабочий стол — примерно через пять
run-darwin.sh не принимает готовый загрузчик полному пользовательскому пространству нужен ваш make loader; готовый не содержит данных Apple и грузит только открытое ядро
тест Metal не запускается сессия слишком короткая: дайте 480 секунд или больше

Телефон

Вы видите Что делать
./xl enter ждёт бесконечно включена ли отладка по USB и подтвердили ли вы компьютер на телефоне? adb devices должен его показывать
fastboot boot отказывает загрузчик не разблокирован
mkxnuimg.py останавливается и отсылает к README UEFI у вас нет образа Silicium для телефона; используйте U-Boot: XL_FIRMWARE=u-boot ./xl enter (после make u-boot)
после баннера загрузчика ничего прошивка не дала загрузчику framebuffer: попробуйте другую (XL_FIRMWARE=u-boot или silicium)
второй запуск в сессии сразу падает известно: один запуск на сессию загрузчика. Между запусками — ./xl reload
gpu=1, а экран рисуется программно GPU не стартовал; в логе сказано, на каком шаге. Чаще всего нет fw-gpu/: make firmware, когда телефон в Android
Wi-Fi, звук или модем молчат каждому нужна своя папка fw-*/ и свой аргумент; make config отказывает им при CONFIG_FIRMWARE="none"
телефон нагрелся или сел за долгую сессию добавьте thermal_stop=95 battery_stop=20: сессия завершится сама и вернёт телефон
телефон будто завис подождите: xl ждёт сторожевой таймер и подскажет, какие кнопки нажать. Удержание питания около 15 секунд перезагружает в Android

Metal

Вы видите Что делать
probe: no GPU: … ядро запущено без gpu=1, или GPU не стартовал (см. выше)
MTLCreateSystemDefaultDevice() возвращает nil устройство скрыто, пока не задан metal=1 (только metal_test), 2 или 3
оконный сервер перезапускается по кругу metal=3 показывает оконному серверу устройство, которое пока не умеет рисовать; используйте 1 или 2
у плагина нет командных буферов он собран без библиотеки: см. Связать плагин с GPU
HakiosMetal: asked and not implemented: -… это не ваша ошибка: приложению нужна часть Metal, которой пока нет. Строка называет её

Как попросить помощи

В Telegram-канале напишите:

  1. команду, которую запускали, дословно;
  2. ваш компьютер (Linux / macOS / Windows) и телефон;
  3. вывод make doctor;
  4. logs/last.log файлом.

Исходник этой страницы