lldb/test/API/functionalities/postmortem/FreeBSDKernel/tools/README.rst

   1 How to create vmcores for tests
   2 ===============================
   3
   4 1. Boot a FreeBSD VM with as little memory as possible and create a core dump
   5    per `FreeBSD Handbook Kernel Debugging Chapter`_.  Note that you may need to
   6    reboot with more memory after the kernel panic as otherwise savecore(8) may
   7    fail.
   8
   9    For instance, I was able to boot FreeBSD and qemu-system-x86_64 with 128 MiB
  10    RAM but had to increase it to 256 MiB for the boot after kernel panic.
  11
  12 2. Transfer the kernel image (``/boot/kernel/kernel``) and vmcore
  13    (``/var/crash/vmcore.latest``) from the VM.
  14
  15 3. Patch libfbsdvmcore using ``libfbsdvmcore-hacks.patch`` and build LLDB
  16    against the patched library.
  17
  18 4. Patch LLDB using ``lldb-minimize-processes.patch`` and build it.
  19
  20    WARNING: LLDB will now modify core files in order to make the resulting
  21    test vmcores smaller.  Make a backup if necessary.
  22
  23 5. Do a test run of ``test.script`` in LLDB against the kernel + vmcore::
  24
  25     lldb -b -s test.script --core /path/to/core /path/to/kernel
  26
  27    If everything works fine, the LLDB output should be interspersed with
  28    ``%RD`` lines.  The vmcore will also be modified to shorten the process
  29    list in ``allproc``.
  30
  31 6. Open the vmcore in the patched LLDB again and choose interesting threads
  32    for testing.  Update thread numbers in ``test.script`` if necessary.
  33
  34 7. Use the ``copy-sparse.py`` tool to create a sparse version of the vmcore::
  35
  36        lldb -b -s test.script --core /path/to/core /path/to/kernel |
  37            grep '^% RD' | python copy-sparse.py /path/to/core vmcore.sparse
  38
  39 8. Compress the sparse vmcore file using ``bzip2``::
  40
  41        bzip2 -9 vmcore.sparse
  42
  43
  44 .. _FreeBSD Handbook Kernel Debugging Chapter:
  45    https://docs.freebsd.org/en/books/developers-handbook/kerneldebug/