1
0
mirror of https://github.com/bitdefender/bddisasm.git synced 2024-12-23 06:28:13 +00:00

Update README

This commit is contained in:
Ionel-Cristinel ANICHITEI 2021-03-30 21:04:21 +03:00
parent cc6cf1e2b6
commit c20e45a8e4

169
README.md
View File

@ -29,82 +29,142 @@ The main objectives of this disassembler are:
## Build and install ## Build and install
### Windows ### Using CMake
This is the recommended way of using the library.
Prerequesites:
- CMake 3.16 or newer (older version may work, but they have not been tested)
- Ninja (optional, but recommended, especially on Windows)
The build process was tested with GCC and Clang on Linux and MSVC on Windows. Note that the Windows kernel build target is available only when using [MSBuild](#-Using-MSBuild-on-Windows).
To build the project run:
```console
mkdir build
cmake -B build .
cmake --build build
```
This will build `bddisasm`, `bdshemu`, and `disasmtool`. For skipping the `disasmtool` build configure CMake with `BDD_INCLUDE_TOOL=OFF`:
```console
mkdir build
cmake -B build . -DBDD_INCLUDE_TOOL=OFF
```
To install the project use:
```console
cmake --build build --target install
```
This will install the `bddisasm` and `bdshemu` static libraries and their public headers. If `disasmtool` was built it will also be installed. Depending on the install location you may need to run the command as root.
Optionally, if a python 3 interpreter is found the instruction tables can be regenerated with:
```console
cmake --build build --target isagenerator
```
To disable the `isagenerator` target configure CMake with `BDD_INCLUDE_ISAGENERATOR=OFF`.
Once installed, CMake projects can use `find_package` to find the library:
```cmake
find_package(bddisasm REQUIRED)
```
Two targets are provided:
- `bddisasm::bddisasm` - this should be used for targets that need only the decoder, without the shell code emulator
- `bddisasm::bdshemu` - this should be used for targets that need the shell code emulator (note that it will pull in `bddisasm::bddisasm` automatically)
There is no need to manually set include or link directories, simply use `target_link_libraries` with the needed target, for example:
```cmake
find_package(bddisasm REQUIRED)
# decoder-tool needs only the decoder library
target_link_libraries(decoder-tool PRIVATE bddisasm::bddisasm)
# emulator-tool needs bdshemu
target_link_libraries(emulator-tool PRIVATE bddisasm::bdshemu)
```
#### Using as a sub-project
The project can be consumed as a sub-project, either by adding it as a git submodule, or by using [CMake's FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html):
With `FetchContent`:
```cmake
FetchContent_Declare(
bddisasm
GIT_REPOSITORY https://github.com/bddisasm/bddisasm
GIT_TAG origin/master
)
FetchContent_MakeAvailable(bddisasm)
```
As a git submodule:
```cmake
# Assuming the submodule is checked out at external/bddisasm
add_subdirectory(external/bddisasm)
```
In both cases the `bddisasm::bddisasm` and `bddisasm::bdshemu` targets will be provided.
When used as a sub-project the `disasmtool`, `isagenerator`, and `install` targets are not available.
#### Packaging
`CPack` is used to generate packages. Simply run the `package` target to generate a package. By default, on Linux the package will be a `.deb` file, and on Windows a `.zip` file. This can be changed by setting `CPACK_GENERATOR` when configurin CMake.
### Using Make on Linux
To build the project run `make` in the root of the repository. This will build only the `bddisasm` and `bdshemu` static libraries, without `disasmtool`.
To install the project run `make install`. Depending on the install location you may need to run the command as root.
### Using MSBuild on Windows
In order to build the projects on Windows you need: In order to build the projects on Windows you need:
* [Visual Studio 2019](https://visualstudio.microsoft.com/vs/) with the Desktop development with C++ workload. - [Visual Studio 2019](https://visualstudio.microsoft.com/vs/) with the Desktop development with C++ workload.
* [Windows SDK 10.0.18362.0](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/). - [Windows SDK 10.0.18362.0](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/).
* [Python 3.7 or newer](https://www.python.org/downloads/release/python-373/) - [Python 3.7 or newer](https://www.python.org/downloads/release/python-373/) (optional)
When you first open the solution Visual Studio should prompt you to install any missing components. When you first open `bddisasm.sln` in Visual Studio should prompt you to install any missing components.
This should be enough to build bddisasm, disasmtool and bdshemu for the Debug and Release configurations. This should be enough to build `bddisasm`, `bdshemu`, and `disasmtool`.
For the DebugKernel and ReleaseKernel configurations, [WDK 1903](https://go.microsoft.com/fwlink/?linkid=2085767) is needed, alongside the Windows Driver Kit Visual Studio extension (the WDK installer should take care of this). For the DebugKernel and ReleaseKernel configurations, [WDK 1903](https://go.microsoft.com/fwlink/?linkid=2085767) is needed, alongside the Windows Driver Kit Visual Studio extension (the WDK installer should take care of this).
For isagenerator, Python 3 is needed. For `isagenerator`, Python 3 is needed.
Building any of the projects is done directly from Visual Studio. Building any of the projects is done directly from Visual Studio.
The results will be in the bin directory in the root of the repository. The results will be in the bin directory in the root of the repository.
### Linux
In order to build the projects on Linux you need:
* gcc
* make
* cmake 3.12 or newer (optional)
#### Building and installing with make
In order to build bddisasm and bdshemu run `make` in the root of the repository. The results will be placed in the bin directory.
In order to install bddisasm and bdshemu run `make install`.
#### Building and installing with cmake
```console
mkdir build
cd build
cmake ..
make
make install
```
The default build type is Release. Using cmake provides support for pkg-config. Other CMake projects can also use `find_package(bddisasm CONFIG REQUIRED)` to find bddisasm. In both cases the following variables will be defined:
* `BDDISASM_INCLUDE_DIRS` - holds the path of the `bddisasm` directory, which contains the public `bddisasm` and `bdshemu` headers.
* `BDDISASM_LIBRARY_DIRS` - holds the path of the directory that contains the `libbddisasm.a` and `libbdshemu.a` libraries.
* `BDDISASM_LIBRARIES` - holds the libraries against which integrators should link.
### Building disasmtool_lix
For disasmtool_lix you also need:
* g++
* cmake 3.12 or newer
* [RapidJSON](https://github.com/Tencent/rapidjson/)
In order to build disasmtool_lix go to the disasmtool_lix directory and run `make`. The results will be in the bin directory in the disasmtool_lix/build directory.
## Decoding instructions ## Decoding instructions
### Decoding API ### Decoding API
There are 4 decoding functions, but internally, they all do the same, albeit some of them with implicit arguments: There are 4 decoding functions, but internally, they all do the same, albeit some of them with implicit arguments:
* `NDSTATUS NdDecode(INSTRUX *Instrux, const uint8_t *Code, uint8_t DefCode, uint8_t DefData)` - this API should be used only if you don't care about the length of the input buffer;
* `NDSTATUS NdDecodeEx(INSTRUX *Instrux, const uint8_t *Code, size_t Size, uint8_t DefCode, uint8_t DefData);` - decode instruction from a buffer with maximum length `Size`; - `NDSTATUS NdDecode(INSTRUX *Instrux, const uint8_t *Code, uint8_t DefCode, uint8_t DefData)` - this API should be used only if you don't care about the length of the input buffer;
* `NDSTATUS NdDecodeEx2(INSTRUX *Instrux, const uint8_t *Code, size_t Size, uint8_t DefCode, uint8_t DefData, uint8_t DefStack, uint8_t PreferedVendor);` - decode instructions with a preferred vendor; - `NDSTATUS NdDecodeEx(INSTRUX *Instrux, const uint8_t *Code, size_t Size, uint8_t DefCode, uint8_t DefData);` - decode instruction from a buffer with maximum length `Size`;
* `NDSTATUS NdDecodeWithContext(INSTRUX *Instrux, const uint8_t *Code, size_t Size, ND_CONTEXT *Context);` - base decode API; the input parameters - `DefCode`, `DefData`, `DefStack`, `VendMode` and `FeatMode` must all be filled in the `Context` structure before calling this function. The Context structure should also be initialized using `NdInitContext` before the first decode call. - `NDSTATUS NdDecodeEx2(INSTRUX *Instrux, const uint8_t *Code, size_t Size, uint8_t DefCode, uint8_t DefData, uint8_t DefStack, uint8_t PreferedVendor);` - decode instructions with a preferred vendor;
- `NDSTATUS NdDecodeWithContext(INSTRUX *Instrux, const uint8_t *Code, size_t Size, ND_CONTEXT *Context);` - base decode API; the input parameters - `DefCode`, `DefData`, `DefStack`, `VendMode` and `FeatMode` must all be filled in the `Context` structure before calling this function. The Context structure should also be initialized using `NdInitContext` before the first decode call.
Note that by default, the default vendor `ND_VEND_ANY` is used for decoding (which means that bddisasm will try to decode as much as possible). Also, the default features mask is `ND_FEAT_ALL`, meaning that bddisasm will optimistically try to decode instructions which are mapped onto the wide NOP space as well (for example, MPX or CET). If these parameters must be changed, it is advised to use the `NdDecodeWithContext` API. Note that by default, the default vendor `ND_VEND_ANY` is used for decoding (which means that bddisasm will try to decode as much as possible). Also, the default features mask is `ND_FEAT_ALL`, meaning that bddisasm will optimistically try to decode instructions which are mapped onto the wide NOP space as well (for example, MPX or CET). If these parameters must be changed, it is advised to use the `NdDecodeWithContext` API.
Converting decoded instructions to textual disassembly must be done using the `NdToText` API. bddisasm only supports Intel, masm-style syntax. Converting decoded instructions to textual disassembly must be done using the `NdToText` API. bddisasm only supports Intel, masm-style syntax.
### Example ### Example
Working with bddisasm is very easy. Decoding and printing the disassembly of an instruction is quick & simple: Working with bddisasm is very easy. Decoding and printing the disassembly of an instruction is quick & simple:
@ -201,6 +261,7 @@ int main()
``` ```
Working with the extended API is also trivial: Working with the extended API is also trivial:
```c ```c
INSTRUX ix; INSTRUX ix;
ND_CONTEXT ctx; ND_CONTEXT ctx;