alexaltea / unicorn.js

Unicorn CPU emulator framework port for JavaScript

Unicorn.js

Port of the Unicorn CPU emulator framework for JavaScript. Powered by Emscripten.

Notes: Unicorn is a lightweight multi-architecture CPU emulator framework originally developed by Nguyen Anh Quynh, Dang Hoang Vu et al. and released under GPLv2 license. More information about contributors and license terms can be found in the files AUTHORS.TXT, CREDITS.TXT and COPYING inside the unicorn submodule of this repository.

Installation

To add Unicorn.js to your web application, include it with:

<script src="unicorn.min.js"></script>

or install it with the Bower command:

bower install unicornjs

Usage

var addr = 0x10000;
var code = [
  0x37, 0x00, 0xA0, 0xE3,  // mov r0, #0x37
  0x03, 0x10, 0x42, 0xE0,  // sub r1, r2, r3
];

// Initialize engine
var e = new uc.Unicorn(uc.ARCH_ARM, uc.MODE_ARM);

// Write registers and memory
e.reg_write_i32(uc.ARM_REG_R2, 0x456);
e.reg_write_i32(uc.ARM_REG_R3, 0x123);
e.mem_map(addr, 4*1024, uc.PROT_ALL);
e.mem_write(addr, code)

// Start emulator
var begin = addr;
var until = addr + code.length;
e.emu_start(begin, until, 0, 0);

// Read registers
var r0 = e.reg_read_i32(uc.ARM_REG_R0);  // 0x37
var r1 = e.reg_read_i32(uc.ARM_REG_R1);  // 0x333

Building

To build the Unicorn.js library, clone the master branch of this repository on a Linux machine, and do the following:

1. Initialize the original Unicorn submodule: git submodule update --init.

2. Install latest Emscripten SDK 2.0.21+. Follow the respective instructions and make sure all environment variables are configured correctly.

3. Install the latest Python 3.8+. Make sure both python3 and python are callable. You can either setup alias or apt install python-is-python3

4. Install the development dependencies with: npm install --also=dev.

5. Install grunt with: npm install -g grunt

6. Finally, build the source with: grunt build.

unicorn.js's Issues

HOOK_CODE causing uncaught exception: abort()

Hi,

So I have the following code that is trying to do a HOOK_CODE on every instruction. If you run it, you will see that it causes an uncaught exception to be thrown and the script aborts. If you remove the push eax instruction from the code, it works as expected. If you put the push eax back and remove any code after it, it also works. The issue is having an instruction after the push instruction.

Any idea on what might be causing this?

Here is the whole error message I am getting:

uncaught exception: abort() at jsStackTrace@file:///tmp/unicorn.js/unicorn-x86.min.js:5:18821
stackTrace@file:///tmp/unicorn.js/unicorn-x86.min.js:5:18992
abort@file:///tmp/unicorn.js/unicorn-x86.min.js:26:7283
_abort@file:///tmp/unicorn.js/unicorn-x86.min.js:5:216266
cg@file:///tmp/unicorn.js/unicorn-x86.min.js:15:128565
Uc@file:///tmp/unicorn.js/unicorn-x86.min.js:13:112318
GQ@file:///tmp/unicorn.js/unicorn-x86.min.js:11:172100
invoke_iiiiiiii@file:///tmp/unicorn.js/unicorn-x86.min.js:5:296738
sI@file:///tmp/unicorn.js/unicorn-x86.min.js:17:112375
mg@file:///tmp/unicorn.js/unicorn-x86.min.js:16:34727
lg@file:///tmp/unicorn.js/unicorn-x86.min.js:16:34213
dO@file:///tmp/unicorn.js/unicorn-x86.min.js:11:79104
ccallFunc@file:///tmp/unicorn.js/unicorn-x86.min.js:5:9901
uc.Unicorn/this.emu_start@file:///tmp/unicorn.js/unicorn-x86.min.js:310:23
load_code@file:///tmp/unicorn.js/error.html:44:5
@file:///tmp/unicorn.js/error.html:71:1

If this abort() is unexpected, build with -s ASSERTIONS=1 which can give more information.

And the code to reproduce it:

<textarea id="asm_code">
    mov eax,100
    mov eax,102
    push eax
    mov ebx,103
</textarea>

<script src='unicorn-x86.min.js'></script>
<script src='keystone-x86.min.js'></script>

<script>
var MEMORY_SIZE = 4096;
var INITIAL_MEMORY = 0xa0000000 >>> 0;

// Engines
var my_uc;
var my_ks;
var log;

function load_code() {
    my_uc = new uc.Unicorn(uc.ARCH_X86, uc.MODE_32);
    my_ks = new ks.Keystone(ks.ARCH_X86, ks.MODE_32);

    var addr = INITIAL_MEMORY;
    var asm_code = document.getElementById("asm_code").value;

    my_ks.option(ks.OPT_SYNTAX, ks.OPT_SYNTAX_INTEL);
    code = my_ks.asm(asm_code);

    // Write registers and memory
    // 4k of memory for now
    my_uc.mem_map(addr, MEMORY_SIZE, uc.PROT_ALL);
    my_uc.mem_write(addr, code);

    // Setup stack
    my_uc.reg_write_i32(uc.X86_REG_ESP, addr + MEMORY_SIZE);

    // Setup hooks
    my_uc.hook_add(uc.HOOK_CODE, hook_code_2, "some data", 1, 0);

    // Start emulator
    var begin = addr;
    var until = addr + code.length;
    my_uc.emu_start(begin, until, 0, 0);

}

function hook_code_2(my_uc, addr_lo, addr_hi, size, used_data) {
    var address = addr_hi << 16 | addr_lo;

    var bytes = my_uc.mem_read(address, size);
    var binary = Array.from(bytes).map(toHex);

    var current_instruction = {
        "address": address,
        "size": size,
        "bytes": bytes,
        "binary_str": binary,
        "asm": 'return asmcode here... need capstone for that',
    }


    console.log("inside hook_code_2");
    console.log(current_instruction);
}

function toHex(n) {
    return n.toString(16).padStart(2, '0');
}

load_code();

</script>

Thanks!

Instruction execution gets incorrect results

Hi, I hope you had a good weekend.

I have run into some issues in emulation and I have come up with a minimal example that can reproduce the bug.
The x86 emulation of following code is not correct, when using either the browser inspect console on https://alexaltea.github.io/unicorn.js/demo.html?arch=x86 or latest library compiled by myself using Emscripten 2.0.9

I have tried official unicorn c and python bindings on version 1.0.1 dating back to 2017 and the results are correct. So I suspect there is something wrong in the unicorn.js, maybe tiny code interpreter or some memory corruption? Would you get a chance to take a look? Thanks!

var addr = 0x10000;
var code = [
0x31, 0xC0, // xor eax, eax
0x89, 0xCB, // mov ebx, ecx
];

// Initialize engine
var e = new uc.Unicorn(uc.ARCH_X86, uc.MODE_32);

// Write registers and memory
e.reg_write_i32(uc.X86_REG_EAX, 0x456);
e.mem_map(addr, 4*1024, uc.PROT_ALL);
e.mem_write(addr, code)

// Start emulator
var begin = addr;
var until = addr + code.length;
e.emu_start(begin, until, 0, 1); // Single stepping

// Read registers
var r0 = e.reg_read_i32(uc.X86_REG_EAX); // Should be 0x0, but is 0x44, why?

Unaligned memory access

There is an unaligned memory access within the file unicorn/qemu/include/exec/exec-all.h at line 218.

static inline void tb_set_jmp_target1(uintptr_t jmp_addr, uintptr_t addr)
{
    /* patch the branch destination */
    *(uint32_t *)jmp_addr = addr - (jmp_addr + 4);
    /* no need to flush icache explicitly */
}

License under the GPL

Since Unicorn is licensed under the GPL, Unicorn.js should be too.

Missing support for hooks

The methods uc_hook_add and uc_hook_del should allow callbacks to JavaScript functions.

Got matchExpr[type].exec is not a function when using with jQuery

Hey can this be fixed so I can use this with jQuery.

Add usage and examples to README

Unicorn v1.0 breaks `tcg_gen_callN` again

The adapter_helper_* functions are defined in qemu/include/exec/helper-gen.h, and may be included in different source files causing pointers to the same adapter to differ. In particular, tcg.c records the pointers in the s->helpers map, while the helper generation commands issued from qemu/target-* are pointing to different adapters, whose pointers are not registered in s->helpers.

This causes a null-pointer dereference which Emscripten ignores. Incorrect flags value are returned for queried functions causing the cpu_exit wrappers to be optimized away and Unicorn.js gets stuck in an endless loop.

Stick to v1.0-rc3 until I fix this. Probably earlier versions weren't affected out of sheer luck.

unicorn.mem_map truncated 48 bit address

Hello again,

When I tried to map the stack for 64 bit binary, for example 0x7fff ffff df20, and try to access the memory at that address later, I always get Invalid memory write for (UC_ERR_MEMORY_UNMAPPED) issue.

I believe the higher bits are truncated and it is actually mapped to 0xffffdf20 because I verified at that region we will not have memory read/write/fetch issue.

The root cause of the issue seems to be MUnicorn.ccall function address argument is always followed by 0, which wiped off the higher bits. Maybe we can try to divide address that are larger than 32 bits to two parts and pass the higher bits instead of 0.

PS: I will test the hooking issue soon.

script compile error

./configure --cc="/run/media/netpipe/df7f53ef-2a98-4562-a498-7da578dab660/Dev/libs/Scripting/emsdk/upstream/emscripten/emcc" --extra-cflags="-DUNICORN_HAS_X86 -DUNICORN_HAS_ARM -DUNICORN_HAS_ARMEB -DUNICORN_HAS_M68K -DUNICORN_HAS_ARM64 -DUNICORN_HAS_ARM64EB -DUNICORN_HAS_MIPS -DUNICORN_HAS_MIPSEL -DUNICORN_HAS_MIPS64 -DUNICORN_HAS_MIPS64EL -DUNICORN_HAS_SPARC -fPIC -fvisibility=hidden" --target-list="x86_64-softmmu, arm-softmmu, armeb-softmmu, m68k-softmmu, aarch64-softmmu, aarch64eb-softmmu, mips-softmmu, mipsel-softmmu, mips64-softmmu, mips64el-softmmu, sparc-softmmu,sparc64-softmmu," --disable-debug-info --python=/usr/bin/python

ERROR: "/run/media/netpipe/df7f53ef-2a98-4562-a498-7da578dab660/Dev/libs/Scripting/emsdk/upstream/emscripten/emcc" either does not exist or does not work

have not tried moving the sdk around to /opt yet. emcc command works and the path is correct

Program counter skips every thousand bytes

Hey,
We're working on a MicroPython emulator in the browser using unicorn.js with the ARM Thumb instruction set. The binaries run well using Unicorn in C, but porting to javascript yielded strange bugs. On a BL instruction (f000 fd27) the PC goes to 0x9fa2 rather than a proper address (0x800ed54).
In the document below we've recreated a similar bug. Every 16-bit Thumb instruction increments R0 and the first emu_start() call works correctly. So also does the second call. However the third instruction which reaches the 1024th byte sets the PC to the magical 9fa2.

Run the below example uncommenting the three lines to see the different behaviour.

<!DOCTYPE html>
  <body>
    <script src="unicorn-arm.min.js"></script>
    <script>
    var addr = 0x0;
    var size = 0x1000;
    var code = new Uint8Array(0x800);
    for (var i = 0; i < code.length; i += 2) {
      code[i] = 0x40;
      code[i + 1] = 0x1c;
    }

    var e = new uc.Unicorn(uc.ARCH_ARM, uc.MODE_THUMB);
    e.reg_write_i32(uc.ARM_REG_R0, 0x0);
    e.mem_map(addr, size, uc.PROT_ALL);
    e.mem_write(addr, code);

    try {
      //e.emu_start(addr | 1, addr + code.length, 0, 0); // works fine
      //e.emu_start(addr | 1, addr + code.length, 0, 0x1ff); // works fine
      e.emu_start(addr | 1, addr + code.length, 0, 0x200); // jumps to 0x9fa2
    }
    catch(e) {
      console.log(e);
    }

    var r0 = e.reg_read_i32(uc.ARM_REG_R0);
    var pc = e.reg_read_i32(uc.ARM_REG_PC);
    console.log("PC = 0x" + pc.toString(16) + ", R0 = 0x" + r0.toString(16));
    </script>
  </body>
</html>

Let us know if you need more information in order to debug it. We did see other strange behaviour but this was the most reproducable.

Invalid memory fetch error

Hi!

I am playing around with Unicorn.js and it seems pretty cool. For some reason, the example from the demo website does not work for me. Whenever I try the example below, I am getting the following error:

unicorn-x86.min.js:316 Uncaught Unicorn.js: Function uc_emu_start failed with code 8:
Invalid memory fetch (UC_ERR_FETCH_UNMAPPED)

I tried on both latest Chrome and Firefox, same error. (just making sure it was not erroring because of the browser).

Anyways, here is the code to reproduce the issue:

<script src='unicorn-x86.min.js'></script>
<!-- <script src='libs/keystone-x86.min.js'></script> -->

<script>
function run() {

    var addr = 0x10000;
    var asm_code = ` mov eax,0 
                     mov edx,1 
                     mov ecx,30 
                     xadd eax,edx 
                     loop -3 
                     hlt`;

    //var my_ks = new ks.Keystone(ks.ARCH_X86, ks.MODE_32);
    var my_uc = new uc.Unicorn(uc.ARCH_X86, uc.MODE_32);
    //my_ks.option(ks.OPT_SYNTAX, ks.OPT_SYNTAX_INTEL);

    //var code = my_ks.asm(asm_code);
    // This array is the same as if I compiled the code above. Just removing
    // keystone to make sure it is not interfering with the results
    code = [184, 0, 0, 0, 0, 186, 1, 0, 0, 0, 185, 30, 0, 0, 0, 15, 193, 208, 226, 233, 244];

    console.log("------CODE----------");
    console.log(code);
    console.log("--------------------");

    // Write registers and memory
    // 4k of memory for now
    my_uc.mem_map(addr, 4*1024, uc.PROT_ALL);
    my_uc.mem_write(addr, code);

    //my_uc.hook_add(uc.HOOK_CODE, hook_code_2, "some data", 1, 0);

    // Start emulator
    var begin = addr;
    var until = addr + code.length;
    console.log("begin = 0x" + begin.toString(16) + "; until = 0x" + until.toString(16));

    my_uc.emu_start(begin, until, 0, 0);

    // Read registers
    //console.log(read_regs_x86(my_uc));
}

run();
</script>

Any ideas what could be causing this issue? I am using the latest release from here: https://github.com/AlexAltea/unicorn.js/releases/download/v1.0/unicorn-x86.min.js. It has a sha256sum equal to db98db852c14b2337315c4a4409819116bcc52817bdec34ccb06c52ba8fb2c12.

Broken timeout/count limits during emulation

When passing non-zero value in the timeout or count arguments of the uc_emu_start function, the execution will sometimes ignore the limit, and sometimes prematurely halt returning an error.

feature request: Make TCG create Webassembly instead of using TCI

As @atrosinenko has achieved with https://github.com/atrosinenko/qemujs, it would be great to have just in time compilation to webassembly instead of using the TCI interpreter.

Update Unicorn to v1.0.2

Unicorn has released version 1.0.2, do you have any plans to upgrade this project?

Add AARCH64 demo

It would be pretty neat if there was an AARCH64 demo as well.

Is it possible to put all release files into dist folder?

Hi @AlexAltea! I'm Peter from @cdnjs, as unicorn.js is awesome, we are hosting it here: https://cdnjs.com/libraries/unicorn.js, I just have a small question about the release file, I saw 4 released files in the dist here: https://github.com/AlexAltea/unicorn.js/tree/v1.0/dist, but there seems to be more in the release page: https://github.com/AlexAltea/unicorn.js/releases/tag/v1.0, uploaded manually, is it possible to add all of them in the future releases? (Just in the tagged commit) So that we can automatically pick up all the future releases, thank you!

Feature Request: Hook

Hook into the Godbolt API to allow compilation of C/C++ to assembly and the execution of that assembly in the Unicorn.js library.

This feature request is inspired by
https://github.com/vasyop/miniC-hosting, an in-browser C interpreter and assumbler to MSIL that visualizes machine state for educational putposes.

Replace Split.js with GoldenLayout in demos

GoldenLayout seems to be exactly what we need to make a decent IDE.

ARM64 registers are repeated in unicorn_constants.js

A little background: Currently, I'm trying to write (at least some of) the documentation for the constants. From reading unicorn_constants.js before, I know that there are three parts to it: register constants, X86 instruction constants, and Unicorn engine constants. So, I decide to use Control-F to find each register and create a placeholder. I find that at the very end, the list of ARM64 registers (the list at the very beginning of the file) is repeated at the end. I realize that it's auto-generated and that it says explicitly not to edit it, but it should be edited to remove this redundancy.

Add documentation

So, this seems really promising. However, like Unicorn, it has absolutely no documentation (at least in English, but it has documentation in Chinese), so you have to dig through the project's source code to find information. So, I suggest that some documentation be added. There's already a wiki, so why not use it (currently, it just redirects to the repo's main page)? I'd love to help.

Hooking instruction has missing parameter

It seems when I try to perform the hooking of a single instruction, I have no where to pass which instruction (for example syscall) that is being hooked in the hook_add function.

unicorn.js/src/unicorn-wrapper.js

Line 185 in dedbfca

case uc.HOOK_INSN:

Thanks