keystone/bindings/masm

Keystone bindings for assembler

This documentation explains how to install & use assembler x86/x64 bindings for Keystone.

The Keystone_x86.inc file and the Keystone_x64.inc files contain the exports, constants and structures required for using Keystone with assembly language.

These files are a conversion of the original files: keystone.h, & x86.h to a format that will work with x86 assemblers (MASM) and x64 assemblers (UASM)

Keystone DLLs

• Compile the relevant version (x86/x64) of keystone.dll
• (Optional) Rename the x86 version of keystone.dll to keystone_x86.dll, and the x64 version of keystone.dll to keystone_x64.dll - depending on which versions you might be linking with in your projects.
• Copy the keystone.dll (or keystone_x86.dll / keystone_x64.dll) to your assembly projects folder or a %PATH% folder.

Alternatively, static libraries and pre-compiled DLL’s can be obtained from the Keystone homepage at http://keystone-engine.org/download. Select the appropriate package to download under the Windows Core engine section: Win-32 and/or Win-64

Keystone Stub Libraries for DLLs

To create the stub libraries for use with Keystone use the following commands (may differ depending on your installation of visual studio):

To create the keystone stub library file (keystone_x86.lib) for MASM x86 Assembler:

• Open the VS2013 x86 Native Tools Command Prompt
• Navigate to the Keystone\bindings\masm folder
• Run the following command lib /DEF:keystone.def /OUT:keystone_x86.lib /MACHINE:X86

To create the keystone stub library file (keystone_x64.lib) for UASM x64 Assembler:

• Open the VS2013 x64 Native Tools Command Prompt
• Navigate to the Keystone\bindings\masm folder
• Run the following command lib /DEF:keystone.def /OUT:keystone_x64.lib /MACHINE:X64

The usage sections below assume you created the keystone stub libraries for the appropriate x86/x64 DLL

MASM32 x86 Assembler Usage

• Copy the Keystone_x86.inc file from the Keystone\bindings\masm folder to your masm32\include folder
• Copy the keystone_x86.lib file from the Keystone\bindings\masm folder to your masm32\lib folder
• Copy the keystone_x86.dll file (or x86 version of keystone.dll) to your assembly projects folder.
• Add the following lines to your source code:

    include Keystone_x86.inc
    includelib keystone_x86.lib

UASM x64 Assembler Usage

• Copy the Keystone_x64.inc file from the Keystone\bindings\masm folder to your UASM\include folder
• Copy the Keystone_x64.lib file from the Keystone\bindings\masm folder to your UASM\lib folder
• Copy the keystone_x64.dll file (or x64 version of keystone.dll) to your assembly projects folder.
• Add the following lines to your source code:

    include Keystone_x64.inc
    includelib Keystone_x64.lib

RadASM Auto-complete files for MASM & UASM (Optional)

Additional files are included for use with RadASM's auto-complete / intelliSense feature. These text files incorporate the keystone api calls and defined constants for api call parameters - for ease of use.

• masmApiCall.api.txt - RadASM code completion file for api calls (for MASM x86)
• masmApiConst.api.txt - RadASM code completion file for constants (for MASM x86)

Basic installation instructions:

• Open each .txt file listed above (for the assembler you will be using with RadASM)
• Copy the contents of the .txt file, and paste into the matching .api file

Instructions are included in the text files themselves as to which file it is related to and the typical location of those .api files.

Examples

Included are two keystone example RadASM projects, for MASM x86 and UASM x64 assemblers:

• KSExample_x86
• KSExample_x64

Resources

• MASM32
• UASM