Skip to content

Commit d948013

Browse files
vlutasvlutas
committed
BDDISASM v3.0.0 - multiple improvements
* Implemented support for minimal decoding: integrators can choose to use the new API which returns a smaller structure (64-bytes); instruction metadata can be retrieved using new API functions * Improved decoding performance by performing instruction validity checks during decode tree lookup * Multiple improvements & fixes around APX & REX2 instructions * Re-worked the ISA generator library
1 parent c1047bb commit d948013

File tree

120 files changed

+121727
-57481
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

120 files changed

+121727
-57481
lines changed

‎CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,24 @@ All notable (user-facing) changes to this project will be documented in this fil
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
66

77

8+
## [3.0.0] - 2025-07-14
9+
10+
### Added
11+
- Support for minimal decoding - the new minimal decode APIs `NdDecodeMini`, `NdDecodeWithContextMini` decode an instruction and provide only the core information in a new `INSTRUX_MINI` structure, which is only 64-bytes in size.
12+
- Operands are not provided by default in an `INSTRUX_MINI` - in order to decode an operand, the integrator must use `NdGetOperandMini`, which will output a `ND_OPERAND`, which is identical to the legacy format.
13+
- Metadata is not provided by default in an `INSTRUX_MINI` - in order to access metadata such as instruction set, valid prefixes, CPUID info, etc., new API is provided in `bdx86_api_mini.h`.
14+
- All the fields from the legacy `INSTRUX` are either already present inside `INSTRUX_MINI`, or accessible via the API.
15+
- The legacy API continues to function without any change needed.
16+
17+
### Fixed
18+
- Allow `REX2` prefix with `MPX` instruction, and ignore `R4` and `B4` fields.
19+
- Fixed `EVEX.U` handling.
20+
21+
### Changed
22+
- The following instructions are no longer supported: `JMPE Ev`, `JMPE Jz`.
23+
- Improved decoding performance by moving validty checks during the decode tree walk - this way, checks are only performed for those instructions that need them.
24+
25+
826
## [2.3.0] - 2024-11-07
927

1028
### Added

‎CMakeLists.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ cmake_minimum_required(VERSION 3.16)
22

33
option(BDD_INCLUDE_TOOL "Include the disasmtool executable" ON)
44
option(BDD_INCLUDE_ISAGENERATOR_X86 "Include the x86 isagenerator target (if a python interpreter is found)" ON)
5+
option(BDD_INCLUDE_TESTS "Include decoder & emulator tests" OFF)
56
option(BDD_INCLUDE_FUZZERS "Include the bdshemu fuzzer" OFF)
67
option(BDD_USE_EXTERNAL_VSNPRINTF "Expect nd_vsnprintf_s implementation from the integrator" OFF)
78
option(BDD_USE_EXTERNAL_MEMSET "Expect nd_memset implementation from the integrator" OFF)
@@ -113,12 +114,17 @@ add_library(
113114
bddisasm/bdx86_decoder.c
114115
bddisasm/bdx86_formatter.c
115116
bddisasm/bdx86_helpers.c
117+
bddisasm/bdx86_idbe.c
118+
bddisasm/bdx86_operand.c
116119
# Add the headers so they will show up in IDEs.
117120
bddisasm/include/bddisasm_crt.h
118121
bddisasm/include/bdx86_instructions.h
119122
bddisasm/include/bdx86_mnemonics.h
123+
bddisasm/include/bdx86_modrm.h
120124
bddisasm/include/bdx86_prefixes.h
125+
bddisasm/include/bdx86_rex2.h
121126
bddisasm/include/bdx86_tabledefs.h
127+
bddisasm/include/bdx86_operand.h
122128
bddisasm/include/bdx86_table_evex.h
123129
bddisasm/include/bdx86_table_root.h
124130
bddisasm/include/bdx86_table_vex.h

‎README.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,19 @@ Note that by default, the default vendor `ND_VEND_ANY` is used for decoding (whi
191191

192192
Converting decoded instructions to textual disassembly must be done using the `NdToText` API. bddisasm only supports Intel, masm-style syntax.
193193

194+
### Minimal Decoding API
195+
196+
The default (legacy) decoding API provides a large `INSTRUX` structure (around 480-bytes long) which contains all the possible information about the instruction, including all of the operands. When faster decoder performance and/or smaller `INSTRUX` is needed, the minimal decode API can be used:
197+
198+
- `NDSTATUS NdDecodeMini(INSTRUX_MINI *Instrux, const uint8_t *Code, size_t Size, uint8_t DefCode)`
199+
- `NDSTATUS NdDecodeWithContextMini(INSTRUX_MINI *Instrux, const uint8_t *Code, size_t Size, ND_CONTEXT *Context);`
200+
201+
The `INSTRUX_MINI` is only 64-bytes long, and provides all the core instruction information, except for the operands and metadata. If needed, operands can be accessed via the following new API:
202+
203+
- `NDSTATUS NdGetOperandMini(const INSTRUX_MINI *Instrux, ND_UINT8 Index, ND_OPERAND *Operand);` - decodes instruction operand at index `Index`
204+
205+
Each type of metadata can also be retrieved from an `INSTRUX_MINI` using API. For example, in order to retrieve the stack access type, `NdGetStackAccessMini` API can be used; to retrieve the valid modes, `NdGetValidModesMini` can be used, etc. Consult `bdx86_api_mini.h` for a list of all available APIs.
206+
194207
### Example
195208

196209
Working with bddisasm is very easy. Decoding and printing the disassembly of an instruction is quick & simple:
@@ -307,6 +320,34 @@ Working with the extended API is also trivial:
307320
...
308321
```
309322

323+
Working with the minimal decoder is equally simple:
324+
325+
```c
326+
INSTRUX_MINI ix;
327+
ND_CONTEXT ctx;
328+
ND_OPERAND op;
329+
char text[ND_MIN_BUF_SIZE];
330+
uint8_t code[] = { 0x48, 0x8B, 0x48, 0x28 };
331+
332+
// This has to be done only once. The same context can be used by both the legacy and mini API!
333+
NdInitContext(&ctx);
334+
335+
ctx.DefCode = ND_CODE_64;
336+
ctx.DefData = ND_DATA_64;
337+
ctx.DefStack = ND_STACK_64;
338+
ctx.VendMode = ND_VEND_ANY;
339+
ctx.FeatMode = ND_FEAT_ALL; // Use ND_FEAT_NONE, if you wish to see NOPs instead of MPX/CET/CLDEMOTE instructions.
340+
341+
// From here one, the ctx can be reused for any number of NdDecodeWithContextMini calls.
342+
NDSTATUS status = NdDecodeWithContextMini(&ix, code, sizeof(code), &ctx);
343+
...
344+
// Getting the first operand.
345+
status = NdGetOperandMini(&ix, 0, &op);
346+
...
347+
// Formatting the instruction.
348+
status = NdToTextMini(&ix, 0, sizeof(text), text);
349+
...
350+
```
310351
## Credits
311352
312-
The entire Bitdefender HVI team.
353+
The entire Bitdefender HVI team.

‎bddisasm/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.PHONY: clean
22

3-
SRC_FILES := bddisasm_crt.c bdx86_decoder.c bdx86_formatter.c bdx86_helpers.c
3+
SRC_FILES := bddisasm_crt.c bdx86_decoder.c bdx86_formatter.c bdx86_helpers.c bdx86_operand.c bdx86_idbe.c
44

55
OBJECTS := $(SRC_FILES:.c=.o)
66

‎bddisasm/bddisasm.vcxproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -513,6 +513,7 @@
513513
<DebugInformationFormat>ProgramDatabase</DebugInformationFormat>
514514
<ProgramDataBaseFileName>$(SolutionDir)bin\$(Platform)\$(Configuration)\$(ProjectName).pdb</ProgramDataBaseFileName>
515515
<CompileAs>Default</CompileAs>
516+
<EnableEnhancedInstructionSet>NotSet</EnableEnhancedInstructionSet>
516517
</ClCompile>
517518
<ProjectReference>
518519
<LinkLibraryDependencies>false</LinkLibraryDependencies>
@@ -665,8 +666,12 @@
665666
<ForcedIncludeFiles Condition="'$(Configuration)|$(Platform)'=='ReleaseKernel|ARM64'">
666667
</ForcedIncludeFiles>
667668
</ClCompile>
669+
<ClCompile Include="bdx86_idbe.c" />
670+
<ClCompile Include="bdx86_operand.c" />
668671
</ItemGroup>
669672
<ItemGroup>
673+
<ClInclude Include="..\inc\bdx86_api_legacy.h" />
674+
<ClInclude Include="..\inc\bdx86_api_mini.h" />
670675
<ClInclude Include="..\inc\bdx86_core.h" />
671676
<ClInclude Include="..\inc\bdx86_constants.h" />
672677
<ClInclude Include="..\inc\bdx86_cpuidflags.h" />
@@ -678,7 +683,10 @@
678683
<ClInclude Include="include\bdx86_instructions.h" />
679684
<ClInclude Include="include\bdx86_mnemonics.h" />
680685
<ClInclude Include="include\bddisasm_crt.h" />
686+
<ClInclude Include="include\bdx86_modrm.h" />
687+
<ClInclude Include="include\bdx86_operand.h" />
681688
<ClInclude Include="include\bdx86_prefixes.h" />
689+
<ClInclude Include="include\bdx86_rex2.h" />
682690
<ClInclude Include="include\bdx86_tabledefs.h" />
683691
<ClInclude Include="include\bdx86_table_evex.h" />
684692
<ClInclude Include="include\bdx86_table_root.h" />

‎bddisasm/bddisasm.vcxproj.filters‎

Lines changed: 51 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,18 @@
3434
<Filter Include="Header Files\private\x86\tables">
3535
<UniqueIdentifier>{b9961460-d06f-4288-9708-44ca965c4a0d}</UniqueIdentifier>
3636
</Filter>
37+
<Filter Include="Header Files\private\x86\idb">
38+
<UniqueIdentifier>{1afeef2f-6b37-4b08-b321-4789ced61bb8}</UniqueIdentifier>
39+
</Filter>
40+
<Filter Include="Header Files\public\x86\api">
41+
<UniqueIdentifier>{a32fb32a-5ab0-45b4-8262-1791007e2445}</UniqueIdentifier>
42+
</Filter>
43+
<Filter Include="Header Files\public\x86\defs">
44+
<UniqueIdentifier>{cffff9de-0123-42c2-b693-7aee2456a39a}</UniqueIdentifier>
45+
</Filter>
46+
<Filter Include="Header Files\private\x86\opclut">
47+
<UniqueIdentifier>{71d053b5-37c1-4ca8-bc98-3b4a89e7cef4}</UniqueIdentifier>
48+
</Filter>
3749
</ItemGroup>
3850
<ItemGroup>
3951
<ClCompile Include="bddisasm_crt.c">
@@ -48,23 +60,20 @@
4860
<ClCompile Include="bdx86_helpers.c">
4961
<Filter>Source Files\x86</Filter>
5062
</ClCompile>
63+
<ClCompile Include="bdx86_idbe.c">
64+
<Filter>Source Files\x86</Filter>
65+
</ClCompile>
66+
<ClCompile Include="bdx86_operand.c">
67+
<Filter>Source Files\x86</Filter>
68+
</ClCompile>
5169
</ItemGroup>
5270
<ItemGroup>
5371
<ClInclude Include="..\inc\bddisasm_version.h">
5472
<Filter>Header Files\public</Filter>
5573
</ClInclude>
56-
<ClInclude Include="..\inc\bdx86_constants.h">
57-
<Filter>Header Files\public\x86</Filter>
58-
</ClInclude>
59-
<ClInclude Include="..\inc\bdx86_cpuidflags.h">
60-
<Filter>Header Files\public\x86</Filter>
61-
</ClInclude>
6274
<ClInclude Include="..\inc\bddisasm_types.h">
6375
<Filter>Header Files\public</Filter>
6476
</ClInclude>
65-
<ClInclude Include="..\inc\bdx86_registers.h">
66-
<Filter>Header Files\public\x86</Filter>
67-
</ClInclude>
6877
<ClInclude Include="..\inc\bddisasm_status.h">
6978
<Filter>Header Files\public</Filter>
7079
</ClInclude>
@@ -74,15 +83,6 @@
7483
<ClInclude Include="..\inc\bdx86_core.h">
7584
<Filter>Header Files\public\x86</Filter>
7685
</ClInclude>
77-
<ClInclude Include="include\bdx86_instructions.h">
78-
<Filter>Header Files\private\x86</Filter>
79-
</ClInclude>
80-
<ClInclude Include="include\bdx86_mnemonics.h">
81-
<Filter>Header Files\private\x86</Filter>
82-
</ClInclude>
83-
<ClInclude Include="include\bdx86_prefixes.h">
84-
<Filter>Header Files\private\x86</Filter>
85-
</ClInclude>
8686
<ClInclude Include="include\bdx86_tabledefs.h">
8787
<Filter>Header Files\private\x86</Filter>
8888
</ClInclude>
@@ -101,5 +101,38 @@
101101
<ClInclude Include="include\bdx86_table_xop.h">
102102
<Filter>Header Files\private\x86\tables</Filter>
103103
</ClInclude>
104+
<ClInclude Include="include\bdx86_operand.h">
105+
<Filter>Header Files\private\x86</Filter>
106+
</ClInclude>
107+
<ClInclude Include="include\bdx86_instructions.h">
108+
<Filter>Header Files\private\x86\idb</Filter>
109+
</ClInclude>
110+
<ClInclude Include="include\bdx86_mnemonics.h">
111+
<Filter>Header Files\private\x86\idb</Filter>
112+
</ClInclude>
113+
<ClInclude Include="include\bdx86_modrm.h">
114+
<Filter>Header Files\private\x86\opclut</Filter>
115+
</ClInclude>
116+
<ClInclude Include="include\bdx86_prefixes.h">
117+
<Filter>Header Files\private\x86\opclut</Filter>
118+
</ClInclude>
119+
<ClInclude Include="include\bdx86_rex2.h">
120+
<Filter>Header Files\private\x86\opclut</Filter>
121+
</ClInclude>
122+
<ClInclude Include="..\inc\bdx86_api_legacy.h">
123+
<Filter>Header Files\public\x86\api</Filter>
124+
</ClInclude>
125+
<ClInclude Include="..\inc\bdx86_api_mini.h">
126+
<Filter>Header Files\public\x86\api</Filter>
127+
</ClInclude>
128+
<ClInclude Include="..\inc\bdx86_constants.h">
129+
<Filter>Header Files\public\x86\defs</Filter>
130+
</ClInclude>
131+
<ClInclude Include="..\inc\bdx86_cpuidflags.h">
132+
<Filter>Header Files\public\x86\defs</Filter>
133+
</ClInclude>
134+
<ClInclude Include="..\inc\bdx86_registers.h">
135+
<Filter>Header Files\public\x86\defs</Filter>
136+
</ClInclude>
104137
</ItemGroup>
105138
</Project>

‎bddisasm/bddisasm_crt.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ nd_strcat_s(
1212
char *dst,
1313
ND_SIZET dst_size,
1414
const char *src
15-
)
15+
)
1616
{
1717
char *p;
1818
ND_SIZET available;

0 commit comments

Comments
 (0)