Bugs

• Fix broken coprocessor register access on ARM (#47).
• Fix broken coprocessor register access on ARM64 (#48).
• Fix broken MSR register write on x86 (#51).
• Correct MSR register reading on x86. It only worked before because the register ID was the first member of the struct used for reading/writing.
• Crash deterministically when attempting to access an X86 MSR with reg_read_batch(), reg_read_batch_as(), and reg_write_batch().
• Fix wrong hook function being called for CPUID. It wasn't being special-cased, meaning the normal instruction hook function was called. This returns void when Unicorn was expecting a boolean, so whether Unicorn fell back to using the default behavior was undefined.
• Crash with a better error message when attempting to hook CPUID on a version of Unicorn that doesn't support it.

The library has been completely rewritten in a mixture of C and Lua, rather than entirely in C++. This has allowed some drastic simplifications, such as removing the need to maintain a table in C that maps callbacks to hooks via weak references to engines.

Yes, my decisions were that brilliant. Debugging was a nightmare.

New Features

• Official support for Unicorn 2.1.x.

• Documentation for the Lua API is now available.

• The memory regions returned from Engine:mem_regions() now have several methods that simplify permissions checking. These all return a boolean indicating if the condition is true.

  • can_read()
  • can_write()
  • can_readwrite()
  • can_exec()
  • can_all()

• When a reg_read_as or reg_write_as fail, the type attempted to cast to is now shown in the error message (e.g. "int32 array, count 8"). This simplifies tracking down the exact read or write that failed.

Bugs

• Update documentation to indicate Unicorn 1.x never claimed support for Apple silicon.
• Macros with a line continuation that contained parentheses weren't detected, so some constants like UC_HOOK_MEM_READ_INVALID were unavailable.

Other Changes

• Internal functions are now marked as such, and API functions are now explicitly exported. This is in preparation for adding Windows support.
• Most hook functions are now templatized to reduce redundant code.

For Custom Builds

• Use the USER_CFLAGS environment variable to pass in custom compiler flags, instead of USER_CXX_FLAGS.
• The Makefile no longer overrides LD_LIBRARY_PATH or DYLD_FALLBACK_LIBRARY_PATH environment variables, as the user may have installed Unicorn in a different location than the default. The user is now responsible for setting these. This shouldn't affect anyone, as those need to be set anyway to find Unicorn.

Bugfixes

Integer Sizes

Integer widths for the Unicorn 2.x control functions were broken on Lua 5.1 and 5.2 on certain combinations of architecture and OS. Depending on these factors, return values from the control could result in integer overflows or truncation where there didn't need to be. This has now been fixed.

The only place it will not work is for Lua 5.1 or 5.2 where lua_Integer was manually changed from ptrdiff_t to a narrower type when Lua itself was being compiled. It's likely that such a change would fundamentally break Lua, so that's a risk I'm willing to take.

Others

Fixed #40 where compilation broke on GCC 12+.

Miscellaneous Changes

• Minor code cleanup, removed unused imports.
• (Development) Code formatting target has been renamed from autoformat to format.
• (Development) Switch to cross-platform fallthrough and noreturn directives that will "just work" when MSVC support is added.

• Add support for Unicorn 2.0
• Add support for LuaJIT 2.1
• Several bugfixes

See CHANGELOG.rst for full details.

The header parser used at build time has been completely rewritten in Lua, removing Python as a build dependency. All you need now is Make, a C++ compiler, and LuaRocks.

The build system has moved from CMake to LuaRocks in preparation for publishing this there. It won't go up until I've removed the Python dependency.

Bugfixes

• Now (theoretically) works on platforms where CHAR_BIT is not 8.
• Automatic detection of installed headers allows adding or removal of architectures without changing any code.
• Linking to LuaJIT on MacOS now works properly; turns out it was a linking issue. CI now passes on all platforms. Fixes #22
• Trying to use an array of 32 16-bit integers would sometimes crash because of an accidental omission of its handler.
• Fixed buffer overflow when reading 64-bit registers on 32-bit Lua.
• Fixed outdated documentation.

Other Changes

Writing a value that is too large to fit into a register will now throw an exception instead of triggering compiler-specific behavior. Before, trying to write 256 to an 8-bit register could set it to 0 instead, or might do something else depending on the compiler.

Required License Change

Due to an oversight on my part, this never should've been licensed under the New BSD license, because:

1. QEMU is licensed under GPL v2.
2. Unicorn is based on QEMU and thus is also (mostly) GPL v2.
3. GPL is viral even when dynamically linking

Thus, this library must be licensed under GPL v2. As much as I would like to keep the original BSD-3 license, this is a legal requirement and there's nothing I can do about it so long as Unicorn uses GPL.

New Features

Python is no longer needed for configuration. I wrote a Lua script that infers the location of the header files, libraries, etc. If you need a virtual environment you now have to pass the path to the Lua executable on the command line. You can also pass in the path to LuaRocks as well, like so:

./configure -l .venv/bin/lua -r .venv/bin/luarocks
make

If you want to use your system's installation of Lua, you don't need to pass anything in and can just run ./configure && make to build the library.

To build the library in debug mode, pass -d to the configure script.

Breaking Changes

Fixing issue #31_ (reading MSRs on x86 is silently broken) required two breaking changes:

• When reading from or writing to UC_X86_REG_MSR, you're now required to pass an additional argument with the ID of the register you want to read. Failing to do so will trigger an exception.
• Only reg_read() and reg_write() support accessing model-specific registers. The reg_*_as() and reg_*_batch() functions now throw exceptions if you try to access a model-specific register. I may add support for this in the future if I can figure out a way to not make it hideous.

I also dropped support for CMake 3.12. You need 3.13 or higher now.

Bugfixes

• Fixed a test that never should've passed (verifies an exception is thrown if an engine is given an invalid query).
• Fixed wrong variable names in Makefile
• Corrected behavior of install target -- it was putting the library in the wrong place.
• Fixed wrong version number in CMake configuration, forgot to change it from 0.1.0.

Other Changes

Lua is now statically linked so it doesn't need to be recompiled as a relocatable library.

Released 2021-11-22

Bugfixes

Crashes with the correct error message if you try double-freeing a context. Before, the engine handle was checked first and the error message said this was a bug in the library -- which was not true. Now, it checks the context handle first, and correctly determines if you've double-freed the context.

Other Changes

• Randomized the order of C++ tests on each run.
• Stricter checks on the stack when testing.
• If the stack is dirty when a test exits, this now shows the size of the stack and the types of the elements on it.
• Bumped default version of LuaRocks from 3.7 to 3.8.
• Fixed dependency specifications in the Makefile which were hella broken.
• Fixed environment variables in CI to allow use on Windows without modification.

Released 2021-11-21

Fixes broken compilation on Microsoft Visual C++, but otherwise functionally identical to 1.2.0. Special thanks to Metaworm for finding this.

Released 2021-09-19

New Features

There are two sets of new features:

Lua Improvements

• Added a new (non-standard) method to engines, reg_read_batch_as(), which is like reg_read_as() but allows you to efficiently read multiple registers at the same time. See docs/api.rst for details.
• Added __close metamethod to engines and contexts, so they can now be used with Lua 5.4's <close> local attribute.

Building and Development Chages

• Unified installation process for all platforms; configure now generates all CMake stuff for you.
• The appropriate Lua installation directory is now automatically determined. Before, it used to install in the normal system directories which is not where Lua looks.
• Added --install-prefix to the configure script to override where the library is installed.

Bugfixes

• Potentially Breaking: Signaling NaNs in a CPU are now passed back to Lua as signaling NaNs. Before, all NaNs were converted to quiet NaNs. This brings it in line with other bindings. Unless you do significant amounts of floating-point operations, this won't affect you.
• Added REG_TYPE_INT16_ARRAY_32, a 32-element array of 16-bit integers. I'd left it out by mistake.
• Fixed a crash when if a context or engine object was explicitly freed, if it got garbage-collected the object may think it's a double free and throw an exception. This eliminates a long-standing bug in LuaJIT on Mac OS and an edge case on other platforms.
• Fixed crash resulting from a race condition, where if Lua schedules an engine to be freed before a dependent context, the context would try to release its resources using an invalid engine. Now the engine cleans up all contexts created from it and signals all remaining Lua context objects to do nothing.
• reg_read_as() truncated floats in arrays to integers due to a copy-paste error.
• All the examples were broken by the unicorn_const change in 1.0b8.
• Setting floating-point registers now (theoretically) works on a big-endian host machine.
• Fixed bug where the engine pointer/engine object pair wasn't removed from the C registry upon closing. This is because the Engine pointer gets nulled out upon closing, and then after closing we tried removing the pointer. It never matched because it was null.

Other Changes

• [C++] All register buffers are now zeroed out upon initialization.
• [C++] read_float80 and write_float80 now operate on lua_Number
  rather than the platform-dependent 64-, 80-, or 128-bit floats.
• [C++] Removed definition of lua_Unsigned for Lua 5.1 since it was both wrong and unused anyway.
• [C++] The engine handle and Lua state are now private variables for UCLuaEngine.
• [C++] Overhauled implementation of contexts to avoid a race condition where the engine was garbage-collected before a context derived from it.
• Switched to Github Actions for CI instead of Travis.
• The Makefile now generates the build directory if you're on CMake 3.13+.
• make install now builds the library if it hasn't been built already.
• make clean now removes the virtualenv directory as well.
• configure defaults to a release build; debug builds are opt-in.
• Removed a lot of C-isms from when this library was written in C.