Split memory research into separate doc and expand
lethosor
parent
aff2944f28
commit
85003a40c2
@ -0,0 +1,149 @@
|
|||||||
|
.. _memory-research:
|
||||||
|
|
||||||
|
###############
|
||||||
|
Memory research
|
||||||
|
###############
|
||||||
|
|
||||||
|
There are a variety of tools that can be used to analyze DF memory - some are
|
||||||
|
listed here. Note that some of these may be old and unmaintained. If you aren't
|
||||||
|
sure what tool would be best for your purposes, feel free to ask for advice (on
|
||||||
|
IRC, Bay12, etc.).
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
:local:
|
||||||
|
|
||||||
|
|
||||||
|
Cross-platform tools
|
||||||
|
====================
|
||||||
|
|
||||||
|
Ghidra
|
||||||
|
------
|
||||||
|
|
||||||
|
Ghidra is a cross-platform reverse-engineering framework (written in Java)
|
||||||
|
available at https://ghidra-sre.org. It supports analyzing both 32-bit and
|
||||||
|
64-bit executables for all supported DF platforms. There are some custom DFHack
|
||||||
|
Ghidra scripts available in the `df_misc`_ repo (look for ``.java`` files).
|
||||||
|
|
||||||
|
|
||||||
|
IDA Freeware 7.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Available from `Hex-Rays <https://www.hex-rays.com/products/ida/support/download_freeware/>`_.
|
||||||
|
Supports analyzing both 32-bit and 64-bit executables for all supported DF platforms.
|
||||||
|
Some ``.idc`` scripts for IDA are available in the `df_misc`_ repo.
|
||||||
|
|
||||||
|
.. _df_misc: https://github.com/DFHack/df_misc
|
||||||
|
|
||||||
|
|
||||||
|
Hopper
|
||||||
|
------
|
||||||
|
|
||||||
|
Runs on macOS and some Linux distributions; available from https://www.hopperapp.com/.
|
||||||
|
`TWBT <https://github.com/mifki/df-twbt/blob/master/PATCHES.md>`_ uses this to produce some patches.
|
||||||
|
|
||||||
|
|
||||||
|
DFHack tools
|
||||||
|
------------
|
||||||
|
|
||||||
|
Plugins
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
There are a few development plugins useful for low-level memory research. They
|
||||||
|
are not built by default, but can be built by setting the ``BUILD_DEVEL``
|
||||||
|
`CMake option <compile-build-options>`. These include:
|
||||||
|
|
||||||
|
- ``check-structures-sanity``, which performs sanity checks on the given DF
|
||||||
|
object. Note that this will crash in several cases, some intentional, so using
|
||||||
|
this with `GDB <linux-gdb>` is recommended.
|
||||||
|
- ``memview``, which produces a hex dump of a given memory range. It also
|
||||||
|
highlights valid pointers, and can be configured to work with `sizecheck`
|
||||||
|
to auto-detect object sizes.
|
||||||
|
- ``vectors``, which can identify instances of ``std::vector`` in a given memory range.
|
||||||
|
|
||||||
|
Scripts
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
Several `development scripts <scripts-devel>` can be useful for memory research.
|
||||||
|
These include (but are not limited to):
|
||||||
|
|
||||||
|
- `devel/dump-offsets`
|
||||||
|
- `devel/find-offsets`
|
||||||
|
- `devel/lsmem`
|
||||||
|
- `devel/sc` (requires `sizecheck`)
|
||||||
|
- `devel/visualize-structure`
|
||||||
|
- Generally, any script starting with ``devel/find``
|
||||||
|
|
||||||
|
.. _sizecheck:
|
||||||
|
|
||||||
|
Sizecheck
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
Sizecheck is a custom tool that hooks into the memory allocator and inserts a
|
||||||
|
header indicating the size of every object. The corresponding logic to check for
|
||||||
|
this header when freeing memory usually works, but is inherently not foolproof.
|
||||||
|
You should not count on DF being stable when using this.
|
||||||
|
|
||||||
|
DFHack's implementation of sizecheck is currently only tested on Linux, although
|
||||||
|
it probably also works on macOS. It can be built with the ``BUILD_SIZECHECK``
|
||||||
|
`CMake option <compile-build-options>`, which produces a ``libsizecheck``
|
||||||
|
library installed in the ``hack`` folder. You will need to preload this library
|
||||||
|
manually, by setting ``PRELOAD_LIB`` on Linux (or ``LD_PRELOAD`` if editing
|
||||||
|
the ``dfhack`` launcher script directly), or by editing the ``dfhack``
|
||||||
|
launcher script and adding the library to ``DYLD_INSERT_LIBRARIES`` on macOS.
|
||||||
|
|
||||||
|
There is also an older sizecheck implementation by Mifki available on
|
||||||
|
`GitHub <https://github.com/mifki/df-sizecheck>`__ (``b.cpp`` is the main
|
||||||
|
sizecheck library, and ``win_patch.cpp`` is used for Windows support). To use
|
||||||
|
this with other DFHack tools, you will likely need to edit the header's
|
||||||
|
magic number to match what is used in `devel/sc` (search for a hexadecimal
|
||||||
|
constant starting with ``0x``).
|
||||||
|
|
||||||
|
Legacy tools
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Some very old DFHack tools are available in the `legacy branch on GitHub <https://github.com/dfhack/dfhack/tree/legacy/tools>`_.
|
||||||
|
No attempt is made to support these.
|
||||||
|
|
||||||
|
|
||||||
|
Linux-specific tools
|
||||||
|
====================
|
||||||
|
|
||||||
|
.. _linux-gdb:
|
||||||
|
|
||||||
|
GDB
|
||||||
|
---
|
||||||
|
|
||||||
|
`GDB <https://www.gnu.org/software/gdb/>`_ is technically cross-platform, but
|
||||||
|
tends to work best on Linux, and DFHack currently only offers support for using
|
||||||
|
GDB on 64-bit Linux. To start with GDB, pass ``-g`` to the DFHack launcher
|
||||||
|
script::
|
||||||
|
|
||||||
|
./dfhack -g
|
||||||
|
|
||||||
|
Some basic GDB commands:
|
||||||
|
|
||||||
|
- ``run``: starts DF from the GDB prompt. Any arguments will be passed as
|
||||||
|
command-line arguments to DF (e.g. `load-save` may be useful).
|
||||||
|
- ``bt`` will produce a backtrace if DF crashes.
|
||||||
|
|
||||||
|
See the `official GDB documentation <https://www.gnu.org/software/gdb/documentation/>`_
|
||||||
|
for more details.
|
||||||
|
|
||||||
|
|
||||||
|
df-structures GUI
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
This is a tool written by Angavrilov and available on `GitHub <https://github.com/angavrilov/cl-linux-debug>`__.
|
||||||
|
It only supports 32-bit DF. Some assistance may be available on IRC.
|
||||||
|
|
||||||
|
|
||||||
|
EDB (Evan's debugger)
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Available on `GitHub <https://github.com/eteran/edb-debugger>`__.
|
||||||
|
|
||||||
|
|
||||||
|
Windows-specific tools
|
||||||
|
======================
|
||||||
|
|
||||||
|
Some people have used `Cheat Engine <https://www.cheatengine.org/>`__ for research in the past.
|
||||||
Loading…
Reference in New Issue