diff --git a/README.md b/README.md index de2f5eb..fcf9ba4 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ # udbserver - Unicorn Emulator Debug Server -When you do emulation with [Unicorn Engine](https://www.unicorn-engine.org/), do you want to inspect the inner state during every step? +`udbserver` is a debugging plugin for [Unicorn Engine](https://www.unicorn-engine.org/) that implements the [GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html). -`udbserver` is a plugin for Unicorn, provides a debug server which implements [GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html). 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! +It enables GDB-compatible debugging capabilities for Unicorn-based emulation projects, allowing you to inspect and control the emulation state through a GDB client. ## Features @@ -15,7 +13,7 @@ When you do emulation with [Unicorn Engine](https://www.unicorn-engine.org/), do * [x] Watchpoint * [ ] Ctrl-C interrupt -## Architectures support +## Architectures Support * i386 * x86\_64 @@ -26,54 +24,32 @@ When you do emulation with [Unicorn Engine](https://www.unicorn-engine.org/), do * PowerPC * RISC-V -# Usage - -## API - -`udbserver` only provides one API: - -```c -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. +## Installation & Usage -## Used in Rust +### Python -You can use `udbserver` as a crate in `Rust`. +The easiest way to get started is via pip: -You can check the [example](examples/server.rs) on how to use it. +`` +pip install udbserver +`` -And you can try it by: +Check out the [Python binding](bindings/python) for examples and documentation. -```sh -$ cargo run --example server -``` +### Rust -Then you can connect it with `gdb-multiarch`. +As a native Rust project, you can use `udbserver` directly as a crate. Check out the [example](examples/server.rs): -## Installation +`` +cargo run --example server +`` -`udbserver` provides a C-compatible set of library, header and pkg-config files, which help you to use it with other languages. +### Other Languages -To build and install it you need to use [cargo-c](https://crates.io/crates/cargo-c): +`udbserver` provides bindings for several languages: -```sh -$ cargo install cargo-c -$ mkdir build -$ cargo cinstall --release --prefix=/usr --destdir build -$ sudo cp -dr 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: - -* [C](bindings/c) +* [C](bindings/c) (also provides C-compatible API for developing new bindings) * [Go](bindings/go) * [Java](bindings/java) -* [Python](bindings/python) + +Please check the corresponding directories for language-specific installation and usage instructions. diff --git a/bindings/c/README.md b/bindings/c/README.md index 949bd3c..c3814ab 100644 --- a/bindings/c/README.md +++ b/bindings/c/README.md @@ -1,6 +1,34 @@ -# Use udbserver in C +# C bindings for udbserver -Check the [example](example.c) on how to use it. +## API + +`udbserver` provides a simple API: + +```c +void udbserver(void* handle, uint16_t port, uint64_t start_addr); +``` + +Parameters: +- `handle`: The raw handle of a Unicorn instance +- `port`: The port number to listen on +- `start_addr`: The address at which the debug server will start and wait for connection. If set to `0`, the debug server starts immediately + +You can call this API inside a Unicorn hook to integrate `udbserver` within other Unicorn-based projects. + +## Installation + +`udbserver` provides a C-compatible set of library, header and pkg-config files. To build and install it you need to use [cargo-c](https://crates.io/crates/cargo-c): + +```sh +cargo install cargo-c +mkdir build +cargo cinstall --release --prefix=/usr --destdir build +sudo cp -dr build/* / +``` + +## Usage + +Check the [example](example.c) on how to use it: ```sh $ gcc example.c -lunicorn -ludbserver -o example diff --git a/bindings/go/README.md b/bindings/go/README.md index 1d4b01c..2032d7c 100644 --- a/bindings/go/README.md +++ b/bindings/go/README.md @@ -1,6 +1,16 @@ -# Use udbserver in Go +# Go bindings for udbserver -Check the [example](example/main.go) on how to use it. +This package provides Go bindings for udbserver, allowing you to inspect and control the emulation state through a GDB client. + +## Installation + +```sh +$ go get github.com/bet4it/udbserver/bindings/go/udbserver +``` + +## Usage + +Please refer to this [example](example/main.go) to learn how to use this package: ```sh $ go run ./example diff --git a/bindings/java/README.md b/bindings/java/README.md index 45ce599..ba366c9 100644 --- a/bindings/java/README.md +++ b/bindings/java/README.md @@ -1,10 +1,19 @@ -# Use udbserver in Java +# Java bindings for udbserver -Remember to [install Unicorn java bindings](https://github.com/unicorn-engine/unicorn/tree/master/bindings/java) before use it. +## Installation -Check the [example](Example.java) on how to use it. +Remember to [install Unicorn java bindings](https://github.com/unicorn-engine/unicorn/tree/master/bindings/java) before installation. + +Then you can install this package with: ```sh $ sudo make install +``` + +## Usage + +Please refer to this [example](Example.java) to learn how to use this package: + +```sh $ make example ```