A low-overhead dynamic binary instrumentation and modification tool for ARM (now with both AArch32 and AArch64 support)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
api Implement emit_safe_fcall_static_args() May 23, 2018
elf_loader Set brk after the executable's data segment, not the interpreter's Aug 2, 2017
pie @ 82f3fb6 T32: Rename the mislabelled stmfd16 instruction to stmea16 Apr 27, 2017
plugins cachesim: use native pointer size for addr_t Nov 7, 2017
test test/load_store: add A64 prefetch instructions Nov 7, 2017
.gitignore Initial public commit May 5, 2016
.gitmodules Switch the pie submodule to HTTPS access instead of SSH Jan 11, 2018
LICENSE Initial public commit May 5, 2016
README.md clone with https instead of git/ssh Jul 24, 2018
common.c Update the copyright headers May 18, 2017
common.h Update the copyright headers May 18, 2017
dbm.c brk emulation: remove MAP_FIXED for the initial allocation Jan 16, 2018
dbm.h Redesign SYS_exit handling not to use pthread_exit(). Fixes #22 Aug 14, 2018
dispatcher.S Update the copyright headers May 18, 2017
dispatcher.c A32: record dispatcher linking for uncond_imm_arm Aug 2, 2017
kernel_sigaction.h Rewrite signal handling. Delays async signals to allow TPC-SPC transl… Apr 4, 2017
makefile Add a simple cache simulation plugin May 10, 2017
plugins.h Add the decoder and field decoder headers to plugin.h Nov 7, 2017
scanner_a64.c API: A64: set the condition code for conditional branches May 23, 2018
scanner_arm.c ARM: Support pre-ARMv7 data memory barrier MCR operation Dec 28, 2017
scanner_common.h API: add CB(N)Z generation helpers Nov 7, 2017
scanner_public.h Define register masks for working with bitwise reglists Jan 19, 2018
scanner_thumb.c T32: decode the condition for conditional branches outside IT blocks May 23, 2018
signals.c Fix the active trace check when unlinking trace fragments for signal … Aug 13, 2018
syscalls.c AArch32: only print the cache flushing message when debugging is enabled Aug 15, 2018
syscalls.h AArch64: clone: fix the SP offset and frame size calculations Jul 17, 2017
traces.c Traces: initialise the branch_cache_status variable Aug 7, 2018
util.S Replace the LR register alias with X30. Aug 14, 2018
util.h Redesign SYS_exit handling not to use pthread_exit(). Fixes #22 Aug 14, 2018


MAMBO: A Low-Overhead Dynamic Binary Modification Tool for ARM


  • 2018-04-11: We've presented our ICPE paper. The slides are available here.
  • 2018-01-23: We've ran a tutorial on using MAMBO's API at HiPEAC 2018. The slides are available here.
  • 2017-04-24: An address decoder for load and store instructions was added to the API: mambo_calc_ld_st_addr(). It allows plugin developers to automatically obtain the base address of all data memory accesses. This API function is available for all supported instruction sets: A32, T32, A64. Its usage is demonstrated in the plugins/mtrace.c plugin.
  • 2017-04-04: Significantly improved support for Linux signals was implemented.
  • 2017-04-03: The AArch64 port of MAMBO is officially released. The initial AArch64 porting was done by Guillermo Callaghan .
  • We have presented the TACO paper at HiPEAC 2017, on 25th of January. The slides are available here.


MAMBO was created as part of Cosmin's EPSRC-funded PhD in the School of Computer Science at the University of Manchester. MAMBO is currently being developed as part of the PAMELA EP/K008730/1 and DOME EP/J016330/1 EPSRC projects.


MAMBO's compatibility with applications is continuously being improved as needed. We are using it on ARMv7 and ARMv8 systems. Our systems run the armhf / arm64 builds of Debian, Ubuntu and Arch Linux ARM. Most GNU/Linux applications work correctly. The following more complex applications and benchmark suites are working correctly under MAMBO on our systems (this is not an exhaustive list):

Also read the Known issues section below.


Prerequisites: an ARM system (physical or virtual) to build and run MAMBO on; dependencies: gcc toolchain, libelf(-dev), ruby (>=1.9.1).

git clone --recurse-submodules https://github.com/beehive-lab/mambo.git
cd mambo


To launch an application under MAMBO, run:

./dbm <path_to_executable> [application's command line arguments]

For example to run ls -a under MAMBO, execute:

./dbm /bin/ls -a

Tip: When an application running under MAMBO exits, the string We're done; exiting with status: <APPLICATION'S EXIT CODE> will be printed to stderr.

Plugin API

The plugin API is event-driven. Plugins should use a init function with __attribute__((constructor)) to register themselves using mambo_register_plugin(). Once a plugin is registered, it can install callbacks for various events using the mambo_register_*_cb() functions. Callback-related functions are listed in api/plugin_support.h. Code generation functions are listed in api/emit_<INST SET>.h and code generation helpers are listed in api/helpers.h. You can also inspect the sample plugin in the plugins/ directory.

To build MAMBO with plugin support, uncomment the -DPLUGINS_NEW CFLAG in the makefile. Then, the source code or object file(s) of the plugin you're trying to build must be added to the PLUGINS= line in the makefile. Note that multiple plugins can be enabled at the same time (and will work correctly if properly designed). For performance reasons, it is recommended to remove unused plugins from the PLUGINS= list.

Known issues

  • There are two limitations related to signal handling: the data in the siginfo_t structure passed to SA_SIGINFO signal handlers is incorrect: most signals will appear to have been sent via kill() from the application itself; and synchronous signal (SIGSEGV, SIGBUS, SIGFPE, SIGTRAP, SIGILL, SIGSYS) handlers cannot sigreturn(), but can (sig)longjmp().
  • At the moment, code cache invalidation in response to the munmap and __cache_flush system calls are only done in the thread in which the system call is executed. This can potentially lead to execution of stale cached code in other threads.

Reporting bugs

If you think you have found a bug which is not in the list of Known issues, please report it here, on Github. However, note that we have limited time available to investigate and fix bugs which are not affecting the workloads we are using. Therefore, if you can't pinpoint the cause of the bug yourself, we ask that you provide as many details on how to reproduce it, and preferably provide a statically linked executable which triggers it.


We welcome contributions. Use pull requests on Github. However, note that we are doing most development in a private git tree and we are working on a number of features which are not quite ready for public release. Therefore, we would strongly encourage you to get in touch before starting to work on anything large, to avoid duplication of effort. We can probably expedite our release of any WIP features you might be interested in, if you do that.


Note that similarly to most other DBM / DBI frameworks and to optimise performance / development effort, MAMBO is not designed to secure itself against malicious activity from the application it is translating. This means that without hardening MAMBO itself, it would not be possible to use it to implement a secure sandbox.