Unicorn Emulator Debug Server - Written in Rust, with bindings of C, Go, Java and Python


udbserver - Unicorn Emulator Debug Server

When you do emulation with Unicorn Engine, do you want to inspect the inner state during every step?

udbserver is a plugin for Unicorn, provides a debug server which implements GDB Remote Serial Protocol. You can connect it by a GDB client and do debugging as what you do on real program.

udbserver can be used as a crate by Rust program, but it also provides a C library and bindings for other languages. You can use it inside most Unicorn based projects!


  • Registers
  • Memory
  • Single Step
  • Breakpoint
  • Watchpoint
  • Ctrl-C interrupt

Architectures support

  • i386
  • x86_64
  • ARM
  • AArch64
  • MIPS
  • PowerPC



udbserver only provides one API:

void udbserver(void* handle, uint16_t port, uint64_t start_addr);

The handle should be the raw handle of a Unicorn instance, port is the port to be listened, start_addr is the address which when Unicorn runs at the debug server will start and wait to be connected. if start_addr is provided with 0, the debug server will start instantly.

You can call this API inside a Unicorn hook, so you can integrate udbserver inside other Unicorn based project easily.

Used in Rust

You can use udbserver as a crate in Rust.

You can check the example on how to use it.

And you can try it by:

$ cargo run --example server

Then you can connect it with a GDB client.


udbserver provides a C-compatible set of library, header and pkg-config files, which help you to use it with other languages.

To build and install it you need to use cargo-c:

$ cargo install cargo-c
$ mkdir build
$ cargo cinstall --release --prefix=/usr --destdir build
$ sudo cp -a build/* /

Language bindings

After install the udbserver library, you can use udbserver in other languages.

You could check the examples on how to use udbserver by different languages:

  • [help] Please provide instructions to install on Windows

    [help] Please provide instructions to install on Windows


    I've been trying to install this server following the instructions.

    But while installing I'm getting:

    --- stderr
      thread 'main' panicked at 'Could not find system unicorn2: Could not run `"pkg-config" "--libs" "--cflags" "unicorn" "unicorn >= 2"`
      The pkg-config command could not be found.
      Most likely, you need to install a pkg-config package for your OS.
      If you've already installed it, ensure the pkg-config command is one of the
      directories in the PATH environment variable.
      If you did not expect this build to link to a pre-installed system library,
      then check documentation of the unicorn-engine crate for an option to
      build the library from source, or disable features or dependencies
      that require pkg-config.', C:\Users\runneradmin\.cargo\registry\src\github.com-1ecc6299db9ec823\unicorn-engine-2.0.0-rc7\bindings/rust/build.rs:115:14
      note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
    warning: build failed, waiting for other jobs to finish...
    Error: CliError { error: Some(1 job failed), exit_code: 101 }

    How do I install unicorn engine for pkg-config?

    opened by CypherpunkSamurai 22
  • Example panicking due to UnexpectedEof error

    Example panicking due to UnexpectedEof error


    Thank you very much for open sourcing this project, which I believe has the potential to radically improve the emulation experience with Unicorn. I followed all the provided steps to compile it (with the exception of removing "use_system_unicorn" from Cargo.toml, because I wanted a fresh installation). Unfortunately, when trying to connect to the example, it crashes as you can see below.

    Steps to reproduce:

    • install udbserver without using the local installation of Unicorn
    • RUST_BACKTRACE=1 cargo run --example server
    • on another terminal, run gdb and then target remote :1234

    On the first terminal, I see the following:

    $ RUST_BACKTRACE=1 cargo run --example server
        Finished dev [unoptimized + debuginfo] target(s) in 0.01s
         Running `target/debug/examples/server`
    Waiting for a GDB connection on ""...
    Debugger connected from
    thread 'main' panicked at 'Failed to start udbserver: Error { kind: UnexpectedEof, message: "failed to fill whole buffer" }', src/lib.rs:46:60
    stack backtrace:
       0: rust_begin_unwind
                 at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/std/src/panicking.rs:584:5
       1: core::panicking::panic_fmt
                 at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/core/src/panicking.rs:142:14
       2: core::result::unwrap_failed
                 at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/core/src/result.rs:1785:5
       3: core::result::Result<T,E>::expect
                 at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/core/src/result.rs:1035:23
       4: udbserver::udbserver::{{closure}}
                 at ./src/lib.rs:46:13
       5: unicorn_engine::ffi::code_hook_proxy
                 at /home/damiano/.cargo/registry/src/github.com-1ecc6299db9ec823/unicorn-engine-2.0.0-rc7/bindings/rust/src/ffi.rs:137:5
       6: helper_uc_tracecode
                 at /home/damiano/.cargo/registry/src/github.com-1ecc6299db9ec823/unicorn-engine-2.0.0-rc7/uc.c:1718:14
       7: <unknown>
    note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
    fatal runtime error: failed to initiate panic, error 5
    [1]    929611 abort (core dumped)  RUST_BACKTRACE=1 cargo run --example server

    In gdb instead I get this:

    $ target remote :1234
    Remote debugging using :1234
    warning: while parsing target description (at line 3): Target description specified unknown architecture "arm"
    warning: Could not load XML target description; ignoring
    warning: No executable has been specified and target does not support
    determining executable automatically.  Try using the "file" command.
    Truncated register 16 in remote 'g' packet

    Am I doing anything wrong? I successfully reproduced the same issue following these steps in a VM with a fresh Linux installation, but let me know if I can provide anything further to help you debug this.


    opened by dmell 5
  • Unable to build, error[E0658]

    Unable to build, error[E0658]

    Trying to build a GDB server for use with Unicorn yields (on Ubuntu 22.04 x86_64): error[E0658]: use of unstable library feature 'scoped_threads'

    $ rustc --explain E0658

    If you're using a stable or a beta version of rustc, you won't be able to use
    any unstable features. In order to do so, please switch to a nightly version of
    rustc (by using [rustup]).

    done. (I think)

    If you're using a nightly version of rustc, just add the corresponding feature
    to be able to use it:
    #[repr(u128)] // ok!
    enum Foo {

    That's very nice but in what file does one do that, Cargo.toml? I gather I paste something, but not sure what. ...and yes, I'm trying to do this w/o becoming a Rust expert (at least not now).

    Tried pasting this in to Cargo.toml (in the udbserver dir) but that didn't work (or I didn't paste it right).

    Full result of "cargo install cargo-c" bellow:

    tallen@timmy:~/Projects/udbserver$ cargo install cargo-c
        Updating crates.io index
      Installing cargo-c v0.9.14+cargo-0.66
       Compiling libc v0.2.137
       Compiling pkg-config v0.3.26
       Compiling proc-macro2 v1.0.47
       Compiling quote v1.0.21
       Compiling unicode-ident v1.0.5
       Compiling autocfg v1.1.0
       Compiling syn v1.0.103
       Compiling cfg-if v1.0.0
       Compiling serde_derive v1.0.147
       Compiling version_check v0.9.4
       Compiling serde v1.0.147
       Compiling log v0.4.17
       Compiling memchr v2.5.0
       Compiling crc32fast v1.3.2
       Compiling once_cell v1.16.0
       Compiling tinyvec_macros v0.1.0
       Compiling bitflags v1.3.2
       Compiling percent-encoding v2.2.0
       Compiling serde_json v1.0.87
       Compiling anyhow v1.0.66
       Compiling typenum v1.15.0
       Compiling unicode-bidi v0.3.8
       Compiling openssl-probe v0.1.5
       Compiling curl v0.4.44
       Compiling lazy_static v1.4.0
       Compiling hashbrown v0.12.3
       Compiling ryu v1.0.11
       Compiling openssl v0.10.42
       Compiling itoa v1.0.4
       Compiling regex-syntax v0.6.28
       Compiling regex-automata v0.1.10
       Compiling foreign-types-shared v0.1.1
       Compiling crossbeam-utils v0.8.12
       Compiling termcolor v1.1.3
       Compiling remove_dir_all v0.5.3
       Compiling heck v0.4.0
       Compiling fastrand v1.8.0
       Compiling os_str_bytes v6.4.0
       Compiling same-file v1.0.6
       Compiling fnv v1.0.7
       Compiling utf8parse v0.2.0
       Compiling semver v1.0.14
       Compiling rand_core v0.6.4
       Compiling static_assertions v1.1.0
       Compiling bytes v1.2.1
       Compiling strsim v0.10.0
       Compiling hex v0.3.2
       Compiling either v1.8.0
       Compiling textwrap v0.16.0
       Compiling arrayvec v0.5.2
       Compiling cbindgen v0.24.3
       Compiling shell-escape v0.1.5
       Compiling humantime v2.1.0
       Compiling hex v0.4.3
       Compiling pathdiff v0.2.1
       Compiling glob v0.3.0
       Compiling unicode-xid v0.2.4
       Compiling home v0.5.4
       Compiling rustc-workspace-hack v1.0.0
       Compiling bytesize v1.1.0
       Compiling unicode-width v0.1.10
       Compiling lazycell v1.3.0
       Compiling cc v1.0.76
       Compiling indexmap v1.9.1
       Compiling tinyvec v1.6.0
       Compiling proc-macro-error-attr v1.0.4
       Compiling proc-macro-error v1.0.4
       Compiling im-rc v15.1.0
       Compiling thread_local v1.1.4
       Compiling form_urlencoded v1.1.0
       Compiling foreign-types v0.3.2
       Compiling walkdir v2.3.2
       Compiling clap_lex v0.2.4
       Compiling kstring v2.0.0
       Compiling rand_xoshiro v0.6.0
       Compiling itertools v0.10.5
       Compiling unicode-normalization v0.1.22
       Compiling jobserver v0.1.25
       Compiling filetime v0.2.18
       Compiling socket2 v0.4.7
       Compiling atty v0.2.14
       Compiling tempfile v3.3.0
       Compiling aho-corasick v0.7.19
       Compiling bstr v0.2.17
       Compiling combine v4.6.6
       Compiling idna v0.3.0
       Compiling bitmaps v2.1.0
       Compiling tar v0.4.38
       Compiling vte_generate_state_changes v0.1.1
       Compiling regex v1.7.0
       Compiling opener v0.5.0
       Compiling url v2.3.1
       Compiling openssl-sys v0.9.77
       Compiling libz-sys v1.1.8
       Compiling libnghttp2-sys v0.1.7+1.45.0
       Compiling curl-sys v0.4.59+curl-7.86.0
       Compiling libssh2-sys v0.2.23
       Compiling libgit2-sys v0.14.0+1.5.0
       Compiling sized-chunks v0.6.5
       Compiling vte v0.10.1
       Compiling globset v0.4.9
       Compiling env_logger v0.9.3
       Compiling ignore v0.4.18
       Compiling strip-ansi-escapes v0.1.1
       Compiling flate2 v1.0.24
       Compiling openssl-macros v0.1.0
       Compiling clap_derive v3.2.18
       Compiling cargo v0.66.0
       Compiling clap v3.2.23
       Compiling crypto-hash v0.3.4
       Compiling cargo-util v0.2.2
       Compiling cargo-platform v0.1.2
       Compiling toml_edit v0.14.4
       Compiling toml v0.5.9
       Compiling os_info v3.5.1
       Compiling serde_ignored v0.1.5
       Compiling rustfix v0.6.1
       Compiling crates-io v0.34.0
       Compiling git2 v0.15.0
       Compiling git2-curl v0.16.0
    error[E0658]: use of unstable library feature 'scoped_threads'
      --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:58:25
    58 | use std::thread::{self, Scope};
       |                         ^^^^^
       = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information
    error[E0658]: use of unstable library feature 'scoped_threads'
       --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:559:9
    559 |         thread::scope(
        |         ^^^^^^^^^^^^^
        = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information
    error[E0658]: use of unstable library feature 'scoped_threads'
       --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:573:20
    573 |         scope: &'s Scope<'s, '_>,
        |                    ^^^^^^^^^^^^^
        = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information
    error[E0658]: use of unstable library feature 'scoped_threads'
       --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:824:20
    824 |         scope: &'s Scope<'s, '_>,
        |                    ^^^^^^^^^^^^^
        = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information
    error[E0658]: use of unstable library feature 'scoped_threads'
        --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:1010:83
    1010 |     fn run<'s>(&mut self, unit: &Unit, job: Job, cx: &Context<'_, '_>, scope: &'s Scope<'s, '_>) {
         |                                                                                   ^^^^^^^^^^^^^
         = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information
    error[E0658]: use of unstable library feature 'scoped_threads'
        --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:1085:23
    1085 |                 scope.spawn(move || {
         |                       ^^^^^
         = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information
    For more information about this error, try `rustc --explain E0658`.
    error: could not compile `cargo` due to 6 previous errors
    warning: build failed, waiting for other jobs to finish...
    error: failed to compile `cargo-c v0.9.14+cargo-0.66`, intermediate artifacts can be found at `/tmp/cargo-installMVsUot`
    opened by tallenintegsys 2
  • Python binding: Segfault on Windows due to type mismatch

    Python binding: Segfault on Windows due to type mismatch

    I compiled this library with mingw64 and it's segfaulting. unsigned long is 4 bytes on Windows, causing libpython to overwrite adjacent bytes on the stack when specifying K. I recommend using inttypes and uint64_t.

    opened by Hendi48 1
  • java调用时提示错误


    Exception in thread "main" java.lang.UnsatisfiedLinkError: udbserver.Udbserver.udbserver(JSJ)V at udbserver.Udbserver.udbserver(Native Method) at udbserver.Udbserver.Udbserver(Udbserver.java:12) at com.github.udbserver.Example.main(Example.java:19)

    opened by heckerstone 0
  • [bug] Python Crashes when attaching udb to AndroidNativeEmu

    [bug] Python Crashes when attaching udb to AndroidNativeEmu

    So, I'm trying to use udbserver with AndroidNativeEmu (androidemu) on Windows, with Python 3.7.

    I have the following code:

    import logging
    import posixpath
    import sys
    from unicorn.arm_const import *
    import sys
    sys.path.append("emulator") # Adds higher directory to python modules path.
    # for loading changed module
    from androidemu.emulator import Emulator
    from androidemu.java.java_class_def import JavaClassDef
    from androidemu.java.java_method_def import java_method_def
    from udbserver import udbserver
    # .............................. Code here ..................................
    emulator.uc.hook_add(UC_HOOK_MEM_UNMAPPED, debug_utils.hook_unmapped)
    # Register Java class.
    # Load all libraries.
    lib_module = emulator.load_library("emulator/libEncryptor.so")
    # ......................... Code Here ........................
    udbserver(emulator.uc, 1337, 0xcbbd2dec)

    and Python crashes and stops working as soon as line udbserver(emulator.uc, 1337, 0xcbbd2dec) is run.

    Is there any reason for this? also, what is 0xcbbd2dec here, am i supposed to use it according to my library?

    opened by CypherpunkSamurai 9
  • mac m1下使用有问题

    mac m1下使用有问题

    编译完成后执行sudo cp -a build/* / 失败,因为mac的新版本系统没有那个权限。 然后我复制到了/usr/local/include 和 /usr/local/lib中。 最后测试的时候报下面的错误 ImportError: dlopen(/Users/king/Library/Python/3.8/lib/python/site-packages/udbserver.cpython-38-darwin.so, 0x0002): symbol not found in flat namespace '_udbserver'

    bug help wanted 
    opened by dqzg12300 3
A server emulator for Digimon Online v1.5.

RustyDO A server emulator for Digimon Online v1.5. Credits Digimon Online v1.5 was created by CCR. The rights of the game and its IP belong to CCR and

JungHyun Kim 28 Jan 7, 2023
A Game Boy research project and emulator written in Rust

Mooneye GB Mooneye GB is a Game Boy research project and emulator written in Rust. The main goals of this project are accuracy and documentation. Some

Joonas Javanainen 802 Dec 28, 2022
RustBoyAdvance-NG is a Nintendo™ Game Boy Advance emulator and debugger, written in the rust programming language.

RustBoyAdvance-NG Nintendo GameBoy Advance ™ emulator and debugger, written in rust. WebAssembly Demo: https://michelhe.github.io/rustboyadvance-ng/ P

MishMish 510 Dec 30, 2022
A NES emulator written in Rust, with a focus on expandability and accuracy

A NES emulator written in Rust, with a focus on expandability and accuracy

Benjamin Mordaunt 4 Sep 19, 2022
NES emulator written in Rust to learn Rust

OxideNES A NES emulator in Rust. CPU should be accurate, PPU is mostly accurate, timing between the 2 is off for some corner cases and hardware qui

null 37 Nov 7, 2022
Chip8 emulator written in pure rust, using rust-sdl2 for graphics

Rust-8 chip8 emulator written in rust, using rust-sdl2 for graphics. Features Fully implemented all 35 original chip8 opcodes. This emulator does NOT

Chris Hinson 7 Dec 28, 2022
Commodore 64 emulator written in Rust

Rust64 - a C64 emulator written in Rust This is my attempt to study the Rust programming language and have fun at the same time. The goal is to presen

Krzysztof Kondrak 214 Dec 27, 2022
A Flash Player emulator written in Rust

website | demo | nightly builds | wiki Ruffle Ruffle is an Adobe Flash Player emulator written in the Rust programming language. Ruffle targets both t

Ruffle 11.2k Jan 8, 2023
An NES emulator written in Rust

Pinky Pinky is an NES emulator written in Rust completely from scratch based only on publicly available documentation. You can run it in your Web brow

Koute 709 Dec 23, 2022
NES emulator written in Rust

sprocketnes is an emulator for the Nintendo Entertainment System written in the Rust programming language. Its purpose is to serve as a technology dem

Patrick Walton 725 Dec 27, 2022
ZX Spectrum emulator written in Rust

rustzx ZX Spectrum emulator which I writing in rust. I develop this project just for fun and for learning the basics of computer architecture. License

Vladislav Nikonov 162 Dec 27, 2022
CHIP-8 emulator written in Rust

CHIP-8 emulator written in Rust. This is intended to be a project for gaining experience writing emulators and practice Rust.

Pedro Rodrigues 4 May 21, 2021
A 6502 emulator written in Rust.

v6502 This package contains an emulator for the 6502 microprocessor. It doesn't support binary decimal (BCD) mode yet. To run the debug version: cargo

Andrew Young 4 Nov 14, 2021
Spaghetti Chip8 Emulator Written In Rust

How to run? Command is simple: cargo run FILENAME. files are stored in the /c8games folder, use one of them. Example: cargo run INVADERS Keymap use 1

Can 5 Apr 15, 2022
Non cycle-accurate emulator of the 6502 cpu, written in pure rust

CPU 6502 A non cycle-accurate emulator implementing all legal 6502 opcodes. What does non cycle-accurate mean? Every instruction on the 6502 takes a n

Pietro 10 Jul 15, 2022
Experimental Nintendo Switch Emulator written in Rust

Kaminari Experimental Nintendo Switch Emulator written in Rust Usage You'll need to install Rust. rusc >= 1.55.0 rustup >= 1.24.3 Disclaimer Kaminari

SSebigo 4 Dec 7, 2021
A barely functional terminal emulator written in Rust. For nothing but fun.

Nothing much to say now. The basic architecture (kind of) so far is: ┌────────┐ ┌──────────────────┐ │ ptm │◀──────▶│ device::Shell │ └─┬

Huy 4 Apr 29, 2022
A Chip8 Emulator written in Rust

Chipper: Chipper is a Chip8 Emulator written in Rust. It currently supports a few known quirks of the Chip8 varieties. I intend on making it support t

Elijah Hartvigsen 4 Aug 20, 2022
A CHIP-8 emulator written in Rust

damn8 A CHIP-8 emulator written in Rust To run, pass a path to a rom in the command line. TODO: Use function pointers to handle opcodes instead of a l

null 1 Jan 11, 2022