Intel® X86 Encoder Decoder (Intel® XED)

Intel XED decoder and encoder fully support the Intel APX architecture.

ENC2 module details:

• Supports Intel APX architecture with minor limitations.
• EGPRs (Expanded General Purpose Registers) are only supported in EVEX.
• REX2 is only emitted when necessary for specific legacy instructions.

There are two ways to build the included examples:

Option 1: Build alongside the library

You can build the examples directly from the main xed directory while building the library. The compiled examples will be located in obj/examples.

Option 2: Build from an installed kit

If you have already performed an install build, you can build the examples from within the generated kit directory.

Example workflow for Option 2:

1. Run ./mfile.py install in the main directory.
2. Navigate to the kits directory.
3. Enter the specific kit directory.
4. Enter the examples directory.
5. Run ./mfile.py.

# Option 1
./mfile.py examples

# Option 2
./mfile.py install
cd kits
cd <whatever the kit is called>
cd examples
./mfile.py

You can convert the prepared obj/dgen directory into a single JSON instruction database using the xed_to_db.py utility.

Steps:

1. Prepare the dgen directory: python mfile.py just-prep
2. Run the conversion script:

python pysrc/xed_to_db.py --xed-dgen=obj/dgen --out=xed_db.json

Options:

• --xed-dgen=<path>: Path to the prepared obj/dgen directory.
• --out=<path>: Output path for the resulting JSON file.
• --validate: Performs additional consistency checks during generation.

To use Intel XED within Python, you must build the XED shared library with specific flags that export C functions with a _py suffix. This allows Python to interact with the library via dynamic loading.

Run the following command from the root directory of the repository:

python mfile.py --shared --py-export

This command performs two critical actions:

1. --shared: Builds XED as a dynamically loadable shared object.
2. --py-export: Wraps and exports necessary C functions with a _py suffix (e.g., xed_tables_init() becomes xed_tables_init_py()) to make them accessible to Python integration tools like ctypes or cffi.

When building with a shared XED library on Linux, the builder defaults to looking for libxed.so in $ORIGIN/../lib or $ORIGIN/../../lib.

If your shared library is located in a non-standard directory, use the --example-rpath flag to specify the path. You can provide multiple paths by repeating the flag.

Note: This option is only applicable to Linux. On Windows, ensure xed.dll is in your PATH or the same directory as the executable.

# Example: libxed.so is in /opt/xed/lib
./mfile.py --shared --example-rpath /opt/xed/lib

# Multiple paths
./mfile.py --shared \
  --example-rpath /opt/xed/lib \
  --example-rpath /usr/local/xed/lib

To encode a request for a promoted No-Flags instruction, you must use the NF operand. This can be done via the C Library API or the XED command-line tool.

void xed3_operand_set_nf(xed_decoded_inst_t* d, 1)

$ xed.exe -set NF 1 ....

The examples in this directory can be built using the mfile.py script. The build process requires Python 3.9 or later and a pre-installed XED library (either static or shared) in a standard location.

Depending on how your XED library is provided, use one of the following commands:

• Static Library (.a on Linux, .lib on Windows): Run python mfile.py.
• Shared Library (.so on Linux, .dll on Windows): You must include the --shared flag: python mfile.py --shared.

To build Intel XED, you need to clone both the xed repository and the mbuild repository. Use the ./mfile.py script to manage the build process.

Build Options:

• Shared Library: Add --shared to the build command to generate a shared object.
• Install Kit: Add install to the build command to place headers and libraries into a kit within the kits directory.
• Windows Users: Prepend your Python path (e.g., C:/python3/python ) to the ./mfile.py command.

After building, the resulting libraries (libxed.a/libxed.so on Linux or xed.lib on Windows) can be found in the obj directory.

git clone https://github.com/intelxed/xed.git xed
git clone https://github.com/intelxed/mbuild.git mbuild
cd xed
./mfile.py

Windows does not support symlinks, so you must physically copy the XED kit (specifically the include and lib directories) into a directory named xedkit in your build folder. If using a modern MSVS compiler (like MSVS14) instead of MSVS2008, you may need to set VS90COMNTOOLS to the appropriate path.

After installation, you must copy xed.dll from the kit to your current working directory and set PYTHONPATH.