Merge remote-tracking branch 'remotes/origin/ud0-compat' into apx

.github/workflows/doc.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Clone Doxygen theme
         run: >-
           git clone 
-          --depth=1 --branch=v2.1.0 
+          --depth=1 --branch=v2.3.1
           https://github.com/jothepro/doxygen-awesome-css.git 
           /tmp/doxy-theme
       - name: Generate documentation

CMakeLists.txt

@@ -10,6 +10,12 @@ project(Zydis VERSION 4.0.0.0 LANGUAGES C)
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
+# Set ZYDIS_ROOT_PROJECT to ON if this is the top-level project otherwise OFF by default.
+set(ZYDIS_ROOT_PROJECT OFF)
+if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+    set(ZYDIS_ROOT_PROJECT ON)
+endif()
+
 # =============================================================================================== #
 # Overridable options                                                                             #
 # =============================================================================================== #
@@ -43,19 +49,19 @@ option(ZYDIS_BUILD_SHARED_LIB
     OFF)
 option(ZYDIS_BUILD_EXAMPLES
     "Build examples"
-    ON)
+    ${ZYDIS_ROOT_PROJECT})
 option(ZYDIS_BUILD_TOOLS
     "Build tools"
-    ON)
+    ${ZYDIS_ROOT_PROJECT})
 option(ZYDIS_BUILD_MAN
     "Build manpages for the tools (requires Ronn-NG)"
     OFF)
 option(ZYDIS_BUILD_DOXYGEN
     "Build doxygen documentation (requires Doxygen)"
-    ON)
+    ${ZYDIS_ROOT_PROJECT})
 option(ZYDIS_BUILD_TESTS
     "Build tests"
-    OFF)
+    ${ZYDIS_ROOT_PROJECT})
 option(ZYDIS_FUZZ_AFL_FAST
     "Enables AFL persistent mode and reduces prints in ZydisFuzzIn"
     OFF)
@@ -65,7 +71,7 @@ option(ZYDIS_LIBFUZZER
 
 # Dependencies
 option(ZYAN_SYSTEM_ZYCORE
-    "Use system Zycore library"
+    "Force using system installed Zycore library"
     OFF)
 set(ZYAN_ZYCORE_PATH
     "${CMAKE_CURRENT_LIST_DIR}/dependencies/zycore"
@@ -77,35 +83,62 @@ set(ZYAN_ZYCORE_PATH
 # Dependencies                                                                                    #
 # =============================================================================================== #
 
-if (ZYAN_SYSTEM_ZYCORE)
-    find_package(Zycore)
-else ()
-    # Try to initialize the Zycore submodule using Git
-    if (NOT EXISTS "${ZYAN_ZYCORE_PATH}/CMakeLists.txt" AND 
-        "${ZYAN_ZYCORE_PATH}" STREQUAL "${CMAKE_CURRENT_LIST_DIR}/dependencies/zycore")
-        find_package(Git QUIET)
-        if(GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
-            execute_process(
-                COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive 
-                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 
-            )
-        endif()
+# Tries to make Zycore available.
+#
+# Priorities:
+#
+# - ZYAN_ZYCORE_PATH specified path always takes maximum precedence if it exists.
+#   - Default value is the sub-module path. So if the sub-module is present, we pick that.
+#     Allows hacking on Zydis/Zycore even if a Zydis OS package is installed.
+# - Look for a system-installed Zycore package (via find_package).
+# - If git is installed & this is a git repository, try cloning the sub-module.
+# - Give up.
+#
+# This is in a function so we can elegantly early-exit once the library is found.
+function (locate_zycore)
+    if (NOT ${ZYAN_SYSTEM_ZYCORE} AND EXISTS "${ZYAN_ZYCORE_PATH}/CMakeLists.txt")
+        message(VERBOSE "Using ZYAN_ZYCORE_PATH specified Zycore")
+        add_subdirectory(${ZYAN_ZYCORE_PATH} "zycore" EXCLUDE_FROM_ALL)
+        return ()
     endif ()
 
-    if (NOT EXISTS "${ZYAN_ZYCORE_PATH}/CMakeLists.txt")
-        message(
-            FATAL_ERROR
-            "Can't find zycore submodule. Please make sure to clone the repo recursively.\n"
-            "You can fix this by running\n"
-            "    git submodule update --init\n"
-            "or by cloning using\n"
-            "    git clone --recursive <url>\n"
-            "Alternatively, you can manually clone zycore to some path and set ZYDIS_ZYCORE_PATH."
-        )
+    if (NOT "${ZYAN_ZYCORE_PATH}" STREQUAL "${CMAKE_CURRENT_LIST_DIR}/dependencies/zycore")
+        message(FATAL_ERROR "No CMake project found at explicitly set ZYAN_ZYCORE_PATH")
     endif ()
 
-    add_subdirectory(${ZYAN_ZYCORE_PATH} "zycore" EXCLUDE_FROM_ALL)
-endif ()
+    find_package(Zycore QUIET)
+    if (Zycore_FOUND)
+        message(VERBOSE "Using system Zycore")
+        return ()
+    endif ()
+
+    if (ZYAN_SYSTEM_ZYCORE)
+        message(FATAL_ERROR "ZYAN_SYSTEM_ZYCORE set but no system-installed Zycore found")
+    endif ()
+
+    find_package(Git QUIET)
+    if(GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
+        message(VERBOSE "Pulling Zycore submodule with git.")
+        execute_process(
+                COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        )
+        add_subdirectory(${ZYAN_ZYCORE_PATH} "zycore" EXCLUDE_FROM_ALL)
+        return ()
+    endif()
+
+    message(
+        FATAL_ERROR
+        "Can't find Zycore. Please make sure to clone the repo recursively.\n"
+        "You can fix this by running\n"
+        "    git submodule update --init\n"
+        "or by cloning using\n"
+        "    git clone --recursive <url>\n"
+        "Alternatively, you can manually clone zycore to some path and set ZYDIS_ZYCORE_PATH."
+    )
+endfunction ()
+
+locate_zycore()
 
 # =============================================================================================== #
 # Library configuration                                                                           #

Doxyfile

@@ -17,3 +17,4 @@ GENERATE_LATEX = NO
 GENERATE_TREEVIEW = YES
 DISABLE_INDEX = NO
 FULL_SIDEBAR = NO
+EXTRACT_ALL = YES

LICENSE

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2021 Florian Bernd
-Copyright (c) 2014-2021 Joel Höner
+Copyright (c) 2014-2024 Florian Bernd
+Copyright (c) 2014-2024 Joel Höner
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

assets/porting-guide-v4-v5.md

@@ -0,0 +1,7 @@
+# Porting Guide v4 -> v5
+
+# Encoder
+
+- `ZydisEncoderDecodedInstructionToEncoderRequest` now expects exactly `instruction->operand_count_visible` to be
+  passed, not `operand_count_visible` at maximum. Passing a lower value was previously allowed but didn't really
+  make much sense at all.

include/Zydis/Decoder.h

@@ -149,13 +149,22 @@ typedef enum ZydisDecoderMode_
      * This mode is enabled by default.
      */
     ZYDIS_DECODER_MODE_IPREFETCH,
+    /**
+     * Enables the `UD0` compatibility mode.
+     *
+     * Some processors decode the `UD0` instruction without a ModR/M byte. Enable this decoder mode
+     * to mimic this behavior.
+     *
+     * This mode is disabled by default.
+     */
+    ZYDIS_DECODER_MODE_UD0_COMPAT,
 
     // TODO: APX mode
 
     /**
      * Maximum value of this enum.
      */
-    ZYDIS_DECODER_MODE_MAX_VALUE = ZYDIS_DECODER_MODE_IPREFETCH,
+    ZYDIS_DECODER_MODE_MAX_VALUE = ZYDIS_DECODER_MODE_UD0_COMPAT,
     /**
      * The minimum number of bits required to represent all values of this enum.
      */

include/Zydis/Encoder.h

@@ -312,7 +312,9 @@ typedef struct ZydisEncoderRequest_
      */
     ZydisOperandSizeHint operand_size_hint;
     /**
-     * The number of instruction-operands.
+     * The number of visible (explicit) instruction operands.
+     *
+     * The encoder does not care about hidden (implicit) operands.
      */
     ZyanU8 operand_count;
     /**
@@ -422,11 +424,11 @@ ZYDIS_EXPORT ZyanStatus ZydisEncoderEncodeInstructionAbsolute(ZydisEncoderReques
  * Converts decoded instruction to encoder request that can be passed to
  * `ZydisEncoderEncodeInstruction`.
  *
- * @param   instruction     A pointer to the `ZydisDecodedInstruction` struct.
- * @param   operands        A pointer to the decoded operands.
- * @param   operand_count   The operand count.
- * @param   request         A pointer to the `ZydisEncoderRequest` struct, that receives
- *                          information necessary for encoder to re-encode the instruction.
+ * @param   instruction             A pointer to the `ZydisDecodedInstruction` struct.
+ * @param   operands                A pointer to the decoded operands.
+ * @param   operand_count_visible   The number of visible instruction operands.
+ * @param   request                 A pointer to the `ZydisEncoderRequest` struct, that receives
+ *                                  information necessary for encoder to re-encode the instruction.
  *
  * This function performs simple structure conversion and does minimal sanity checks on the 
  * input. There's no guarantee that produced request will be accepted by
@@ -437,7 +439,7 @@ ZYDIS_EXPORT ZyanStatus ZydisEncoderEncodeInstructionAbsolute(ZydisEncoderReques
  */
 ZYDIS_EXPORT ZyanStatus ZydisEncoderDecodedInstructionToEncoderRequest(
     const ZydisDecodedInstruction* instruction, const ZydisDecodedOperand* operands,
-    ZyanU8 operand_count, ZydisEncoderRequest* request);
+    ZyanU8 operand_count_visible, ZydisEncoderRequest* request);
 
 /**
  * Fills provided buffer with `NOP` instructions using longest possible multi-byte instructions.

include/Zydis/Formatter.h

@@ -176,16 +176,16 @@ typedef enum ZydisFormatterProperty_
     /**
      * Controls the padding of absolute address values.
      *
-     * Pass `ZYDIS_PADDING_DISABLED` to disable padding, `ZYDIS_PADDING_AUTO` to padd all
-     * addresses to the current stack width (hexadecimal only), or any other integer value for
+     * Pass `ZYDIS_PADDING_DISABLED` to disable padding, `ZYDIS_PADDING_AUTO` to pad all
+     * addresses to the current address width (hexadecimal only), or any other integer value for
      * custom padding.
      */
     ZYDIS_FORMATTER_PROP_ADDR_PADDING_ABSOLUTE,
     /**
      * Controls the padding of relative address values.
      *
-     * Pass `ZYDIS_PADDING_DISABLED` to disable padding, `ZYDIS_PADDING_AUTO` to padd all
-     * addresses to the current stack width (hexadecimal only), or any other integer value for
+     * Pass `ZYDIS_PADDING_DISABLED` to disable padding, `ZYDIS_PADDING_AUTO` to pad all
+     * addresses to the current address width (hexadecimal only), or any other integer value for
      * custom padding.
      */
     ZYDIS_FORMATTER_PROP_ADDR_PADDING_RELATIVE,
@@ -262,6 +262,8 @@ typedef enum ZydisFormatterProperty_
      * Controls the letter-case for decorators.
      *
      * Pass `ZYAN_TRUE` as value to format in uppercase or `ZYAN_FALSE` to format in lowercase.
+     *
+     * WARNING: this is currently not implemented (ignored).
      */
     ZYDIS_FORMATTER_PROP_UPPERCASE_DECORATORS,
 
@@ -798,75 +800,75 @@ struct ZydisFormatter_
      */
     ZyanBool print_branch_size;
     /**
-     * The `ZYDIS_FORMATTER_DETAILED_PREFIXES` property.
+     * The `ZYDIS_FORMATTER_PROP_DETAILED_PREFIXES` property.
      */
     ZyanBool detailed_prefixes;
     /**
-     * The `ZYDIS_FORMATTER_ADDR_BASE` property.
+     * The `ZYDIS_FORMATTER_PROP_ADDR_BASE` property.
      */
     ZydisNumericBase addr_base;
     /**
-     * The `ZYDIS_FORMATTER_ADDR_SIGNEDNESS` property.
+     * The `ZYDIS_FORMATTER_PROP_ADDR_SIGNEDNESS` property.
      */
     ZydisSignedness addr_signedness;
     /**
-     * The `ZYDIS_FORMATTER_ADDR_PADDING_ABSOLUTE` property.
+     * The `ZYDIS_FORMATTER_PROP_ADDR_PADDING_ABSOLUTE` property.
      */
     ZydisPadding addr_padding_absolute;
     /**
-     * The `ZYDIS_FORMATTER_ADDR_PADDING_RELATIVE` property.
+     * The `ZYDIS_FORMATTER_PROP_ADDR_PADDING_RELATIVE` property.
      */
     ZydisPadding addr_padding_relative;
     /**
-     * The `ZYDIS_FORMATTER_DISP_BASE` property.
+     * The `ZYDIS_FORMATTER_PROP_DISP_BASE` property.
      */
     ZydisNumericBase disp_base;
     /**
-     * The `ZYDIS_FORMATTER_DISP_SIGNEDNESS` property.
+     * The `ZYDIS_FORMATTER_PROP_DISP_SIGNEDNESS` property.
      */
     ZydisSignedness disp_signedness;
     /**
-     * The `ZYDIS_FORMATTER_DISP_PADDING` property.
+     * The `ZYDIS_FORMATTER_PROP_DISP_PADDING` property.
      */
     ZydisPadding disp_padding;
     /**
-     * The `ZYDIS_FORMATTER_IMM_BASE` property.
+     * The `ZYDIS_FORMATTER_PROP_IMM_BASE` property.
      */
     ZydisNumericBase imm_base;
     /**
-     * The `ZYDIS_FORMATTER_IMM_SIGNEDNESS` property.
+     * The `ZYDIS_FORMATTER_PROP_IMM_SIGNEDNESS` property.
      */
     ZydisSignedness imm_signedness;
     /**
-     * The `ZYDIS_FORMATTER_IMM_PADDING` property.
+     * The `ZYDIS_FORMATTER_PROP_IMM_PADDING` property.
      */
     ZydisPadding imm_padding;
     /**
-     * The `ZYDIS_FORMATTER_UPPERCASE_PREFIXES` property.
+     * The `ZYDIS_FORMATTER_PROP_UPPERCASE_PREFIXES` property.
      */
     ZyanI32 case_prefixes;
     /**
-     * The `ZYDIS_FORMATTER_UPPERCASE_MNEMONIC` property.
+     * The `ZYDIS_FORMATTER_PROP_UPPERCASE_MNEMONIC` property.
      */
     ZyanI32 case_mnemonic;
     /**
-     * The `ZYDIS_FORMATTER_UPPERCASE_REGISTERS` property.
+     * The `ZYDIS_FORMATTER_PROP_UPPERCASE_REGISTERS` property.
      */
     ZyanI32 case_registers;
     /**
-     * The `ZYDIS_FORMATTER_UPPERCASE_TYPECASTS` property.
+     * The `ZYDIS_FORMATTER_PROP_UPPERCASE_TYPECASTS` property.
      */
     ZyanI32 case_typecasts;
     /**
-     * The `ZYDIS_FORMATTER_UPPERCASE_DECORATORS` property.
+     * The `ZYDIS_FORMATTER_PROP_UPPERCASE_DECORATORS` property.
      */
     ZyanI32 case_decorators;
     /**
-     * The `ZYDIS_FORMATTER_HEX_UPPERCASE` property.
+     * The `ZYDIS_FORMATTER_PROP_HEX_UPPERCASE` property.
      */
     ZyanBool hex_uppercase;
     /**
-     * The `ZYDIS_FORMATTER_HEX_FORCE_LEADING_NUMBER` property.
+     * The `ZYDIS_FORMATTER_PROP_HEX_FORCE_LEADING_NUMBER` property.
      */
     ZyanBool hex_force_leading_number;
     /**

include/Zydis/Internal/DecoderData.h

@@ -182,22 +182,26 @@ enum ZydisDecoderTreeNodeTypes
      * Reference to a IPREFETCH-mode filter.
      */
     ZYDIS_NODETYPE_FILTER_MODE_IPREFETCH    = 0x1D,
+    /**
+     * Reference to a UD0_COMPAT-mode filter.
+     */
+    ZYDIS_NODETYPE_FILTER_MODE_UD0_COMPAT   = 0x1E,
     /**
      * Reference to an EVEX.nd filter.
      */
-    ZYDIS_NODETYPE_FILTER_EVEX_ND           = 0x1E,
+    ZYDIS_NODETYPE_FILTER_EVEX_ND           = 0x1F,
     /**
      * Reference to an EVEX.nf filter.
      */
-    ZYDIS_NODETYPE_FILTER_EVEX_NF           = 0x1F,
+    ZYDIS_NODETYPE_FILTER_EVEX_NF           = 0x20,
     /**
      * Reference to an EVEX.scc filter.
      */
-    ZYDIS_NODETYPE_FILTER_EVEX_SCC          = 0x20,
+    ZYDIS_NODETYPE_FILTER_EVEX_SCC          = 0x21,
     /**
      * Reference to a REX2-prefix filter.
      */
-    ZYDIS_NODETYPE_FILTER_REX2_PREFIX       = 0x21
+    ZYDIS_NODETYPE_FILTER_REX2_PREFIX       = 0x22
 };
 
 /* ---------------------------------------------------------------------------------------------- */

include/Zydis/Internal/EncoderData.h

@@ -221,6 +221,10 @@ typedef struct ZydisEncoderRelInfo_
      * True if instruction accepts branch hint prefixes.
      */
     ZyanBool accepts_branch_hints;
+    /**
+     * True if instruction accepts bound (`BND`) prefix.
+     */
+    ZyanBool accepts_bound;
 } ZydisEncoderRelInfo;
 
 /**