ayozetr
1eadf67c8c
The repository's documentation is the fork's: README.md, BBPORT.md (the original project's README, for its technical details), mkdocs.yml and docs/ with the players' guide, the developers' pages and the design notes from upstream the fork keeps in English. Upstream's own docs (release notes, roadmap, session logs, its other notes, most of them in Russian) and README.ru.md are not part of it; docs/README.md links to them in upstream's repository, as on the fork's main branch. Pages that describe 0.51's code are brought up to date as each part is brought onto 0.7. docs/ENVIRONMENT.md stays the fork's guide, written by hand. scripts/env_vars.py no longer writes over it: --doc prints the whole list of gpu/shim/bb_env_vars.def as Markdown, and tests/test_env_vars.py checks that list against the code, and that the printed list has every variable.
1.6 KiB
Catching a crash with a debugger
By default a fatal fault or a GPU-library assertion ends the process at once: the log keeps
one line (Host fault, Guest fault, STOP: GPU library assertion failed) and nothing else.
BB_FAULT_WAIT=1 keeps the process alive at that point, stopped inside its handler, so a
debugger can look at the faulting thread with its registers, stack and memory still there.
- Launcher → Advanced → Developer → Extra variables:
BB_FAULT_WAIT=1(or export it beforerun.sh). Nothing changes while the game runs; it costs nothing. - When it crashes, the game freezes, a desktop notification says so, and the log ends with
bbport: ... the process stays alive for a debugger: bash tools/debug_attach.sh <pid>. - Run that line. gdb attaches, writes
logs/crash-<time>-<pid>.txtand kills the process. With--keepit detaches instead, sogdb -p <pid>can be used by hand afterwards.
The report has every thread's stack, and for the faulting thread its registers, the
instructions around pc and the top of its stack; for a GPU-library assertion the locals of
the asserting thread (bt full). bbport's own frames carry file and line (the build is
RelWithDebInfo); libc's come from debuginfod when it is reachable. Game code shows as a
guest offset (pc minus the image base, as in the log's Guest fault line); the report gives
an objdump command that disassembles out/boot-linked.bin around it.
GPU hangs are different: the device is lost and the GPU breadcrumbs in the log name the stuck draw or dispatch; the assertion that follows is caught the same way, but the state of interest is on the GPU.