capstone/CONTRIBUTING.md

Code structure

Capstone source is organized as followings.

.                   <- core engine + README.md + BUILDING.md etc
├── arch            <- code handling disasm engine for each arch
│   ├── AArch64     <- AArch64 engine
│   ├── Alpha       <- Alpha engine
│   ├── ARM         <- ARM engine
│   ├── BPF         <- Berkeley Packet Filter engine
│   ├── EVM         <- Ethereum engine
│   ├── HPPA        <- HPPA engine
│   ├── M680X       <- M680X engine
│   ├── M68K        <- M68K engine
│   ├── Mips        <- Mips engine
│   ├── MOS65XX     <- MOS65XX engine
│   ├── PowerPC     <- PowerPC engine
│   ├── RISCV       <- RISCV engine
│   ├── SH          <- SH engine
│   ├── Sparc       <- Sparc engine
│   ├── SystemZ     <- SystemZ engine
│   ├── TMS320C64x  <- TMS320C64x engine
│   ├── TriCore     <- TriCore engine
│   └── WASM        <- WASM engine
├── bindings        <- all bindings are under this dir
│   ├── java        <- Java bindings
│   ├── ocaml       <- Ocaml bindings
│   └── python      <- Python bindings
│       └── cstest  <- Testing tool for the Python bindings.
├── suite           <- Several tools used for development
│   ├── cstest      <- Testing tool to consume and check the test `yaml` files in `tests`
│   ├── fuzz        <- Fuzzer
│   └── auto-sync   <- The updater for Capstone modules
├── contrib         <- Code contributed by community to help Capstone integration
├── cstool          <- Cstool
├── docs            <- Documentation
├── include         <- API headers in C language (*.h)
├── packages        <- Packages for Linux/OSX/BSD.
├── windows         <- Windows support (for Windows kernel driver compile)
├── tests           <- Unit and itegration tests
└── xcode           <- Xcode support (for MacOSX compile)

Building

Follow the instructions in BUILDING.md for how to compile and run test code.

Testing

General testing docs are at tests/README.md.

You can test single instructions easily with the cstool. For example:

$ cstool x32 "90 91"

Using cstool is also the prefered way for debugging a single instruction.

Bindings

Bindings currently have not equivalent to a cstool.

The Python bindings have cstool implemented.

Other bindings are out-of-date for a while because of missing maintainers. They only have legacy integration tests.

Please check the issues or open a new one if you intent to work on them or need them.

Coding style

• We provide a .clang-format for C code.
• Python files should be formatted with black.

Support

Please always open an issue or leave a comment in one, before starting work on an architecture! We can give support and save you a lot of time.

Updating an Architecture

The update tool for Capstone is called Auto-Sync and can be found in suite/auto-sync.

Not all architectures are supported yet. Run suite/auto-sync/Updater/ASUpdater.py -h to get a list of currently supported architectures.

The documentation how to update with Auto-Sync or refactor an architecture module can be found in suite/auto-sync/README.md.

If a module does not support Auto-Sync yet, it is highly recommended to refactor it instead of attempting to update it manually. Refactoring will take less time and updates it during the procedure.

The one exception is x86. In LLVM we use several emitter backends to generate C code. One of those LLVM backends (the DecoderEmitter) has two versions. One for x86 and another for all the other architectures. Until now it was not worth it to refactoring this unique x86 backend. So x86 is not supported currently.

Adding an Architecture

If your architecture is supported in LLVM or one of its forks, you can use Auto-Sync to add the new module. Checkout suite/auto-sync/README.md.

Otherwise, you need to implement the disassembler on your own and make it work with the Capstone API.