VxLang SDK Tutorial — Precautions
This document explains compiler behavior and control-flow considerations when applying VxLang SDK protection markers.
Precautions — Essential Considerations Before Using the SDK
The VxLang SDK uses BEGIN and END markers to designate regions of code for protection. The actual machine code and control flow generated by a compiler may differ from the C/C++ source structure. Before defining a protected region, review the following four considerations.
1. Compiler Optimization
When compiler optimizations are enabled, the compiler may eliminate unnecessary code, merge duplicate code, or rearrange instructions. As a result, the instructions between SDK markers may not match the intended region and could cause runtime issues. We recommend disabling optimization only for functions that use SDK protection markers and verifying the compiled output. MSVC supports #pragma optimize("", off), while Clang supports #pragma clang optimize off.
2. Jump Tables and Indirect Branches
A switch-case statement may be compiled into jump-table-based control flow that uses indirect jumps, such as jmp reg or jumps through memory. If an indirect branch crosses an unexpected boundary of a protected region, problems may occur. We recommend applying separate SDK markers to the executable code in each case rather than wrapping the entire function. Inspect the actual branch structure generated by the compiler.
3. Windows SEH Exception Handling
Structured Exception Handling (SEH) can redirect control flow along exception paths rather than normal sequential execution. For code that uses SEH, the official guidance describes enclosing both the __try and __except blocks within the SDK marker pair. Verify correct behavior for your compiler, architecture, and selected protection mode.
4. Compiler-Specific Language Exception Handling
Language-level exception handling, including C++, depends on compiler-specific metadata and stack-unwinding rules. We recommend placing the actual throw statement outside SDK markers, while protecting the ordinary execution code within try and catch separately where needed. Support may depend on the compiler and the applicable VxLang plugin.
The following sections provide examples and additional details for each consideration.
1. Compiler Optimization Considerations
When optimization is enabled, a compiler may remove unnecessary instructions, merge duplicate code, or change the layout of instructions inside a function. This may affect the intended protection region defined by SDK BEGIN/END markers. We recommend disabling optimization for the protected function and checking the final compiler output.
MSVC
#pragma optimize("", off)
void Test() {
VL_OBFUSCATION_BEGIN;
// Protected code
VL_OBFUSCATION_END;
}
#pragma optimize("", on)
#pragma optimize("", off) disables optimization for subsequent function definitions. #pragma optimize("", on) re-enables the specified optimization settings for subsequent functions. In this example, the directives are positioned so that only Test() is affected. If the project uses different optimization settings, take care to restore the intended configuration.
Clang / Clang-CL
#pragma clang optimize off
void Test() {
VL_OBFUSCATION_BEGIN;
// Protected code
VL_OBFUSCATION_END;
}
#pragma clang optimize on
Clang allows optimization to be controlled around function definitions with #pragma clang optimize off/on. You can also apply the optnone attribute to an individual function:
__attribute__((optnone))
void Test() {
VL_OBFUSCATION_BEGIN;
// Protected code
VL_OBFUSCATION_END;
}
Note: Disabling optimization does not automatically control every compiler-generated branch, jump table, or function boundary. Inspect the generated assembly and test the executable after applying markers.
2. Jump Table-Based Branch Transition
The compiler may implement branching constructs such as switch-case using indirect jumps or jump tables. For example, it may generate patterns such as jmp reg or jmp [reg+reg+offset], where the destination is selected through a register or memory.
If a branch inside a protected region transfers control outside that region or to an unexpected location, the protection transformation may interfere with execution. Therefore, rather than wrapping an entire function, we recommend placing BEGIN/END markers around the actual executable code of each case.
void Test(int value) {
switch (value) {
case 1:
VL_VIRTUALIZATION_BEGIN;
DoCaseOne();
VL_VIRTUALIZATION_END;
break;
case 2:
VL_VIRTUALIZATION_BEGIN;
DoCaseTwo();
VL_VIRTUALIZATION_END;
break;
default:
VL_VIRTUALIZATION_BEGIN;
DoDefault();
VL_VIRTUALIZATION_END;
break;
}
}
DoCaseOne, DoCaseTwo, and DoDefault are illustrative user-defined functions. Ensure that each control-flow path has matching BEGIN/END markers, and avoid jumping directly from a protected region into a different case. Verify compatibility and performance in the final executable.
3. Exception Handling — SEH
Windows Structured Exception Handling (SEH) transfers control along exception paths that differ from normal sequential execution. The official guidance illustrates a protected SEH region by enclosing the entire exception-handling construct within SDK markers.
#pragma optimize("", off)
void Test() {
VL_OBFUSCATION_BEGIN;
__try {
// Protected operation
}
__except (EXCEPTION_EXECUTE_HANDLER) {
// Handle the exception
}
VL_OBFUSCATION_END;
}
#pragma optimize("", on)
This example assumes Windows SEH and a compiler environment that supports it. Verify the supported behavior for your target architecture and VxLang version.
4. Compiler-Specific Exception Handling — C++ / Rust / Other Languages
Language-level exception handling, including C++, depends on compiler-generated exception metadata and unwinding code. Unlike ordinary branching, this may affect the boundaries of protected regions.
The official guidance recommends placing the statement that actually throws an exception outside the SDK markers. The following example protects ordinary code within try and catch separately while keeping the throw outside the protected region.
#include <stdexcept>
void Test() {
try {
VL_OBFUSCATION_BEGIN;
// Protected operation
VL_OBFUSCATION_END;
throw std::runtime_error("Example exception");
}
catch (...) {
VL_OBFUSCATION_BEGIN;
// Protected exception-handling code
VL_OBFUSCATION_END;
}
}
Note: This example demonstrates the intended marker boundaries; it does not guarantee compatibility with every compiler or exception type. Exception-handling support may vary depending on the compiler implementation and the corresponding VxLang plugin.
5. SDK Integration Checklist
- Confirm that every normal execution path contains properly matched
BEGIN/ENDmarkers. - Disable optimization only for functions that require it.
- Verify that jump tables and indirect jumps do not cross unexpected protection boundaries.
- Review the boundaries of exception-throwing code and exception-handling blocks.
- Test actual behavior in both Debug and Release builds.
- Verify functionality and performance in the protected executable.
This tutorial covers precautions to review before using the SDK. For specific API declarations, refer to vxlib.h and the separate Protection Features documentation.
