| Code structure |
| -------------- |
| |
| Capstone source is organized as followings. |
| |
| . <- core engine + README + COMPILE.TXT 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 + test code |
| │ ├── ocaml <- Ocaml bindings + test code |
| │ └── python <- Python bindings + test code |
| ├── contrib <- Code contributed by community to help Capstone integration |
| ├── cstool <- Cstool |
| ├── docs <- Documentation |
| ├── include <- API headers in C language (*.h) |
| ├── msvc <- Microsoft Visual Studio support (for Windows compile) |
| ├── packages <- Packages for Linux/OSX/BSD. |
| ├── windows <- Windows support (for Windows kernel driver compile) |
| ├── suite <- Development test tools - for Capstone developers only |
| ├── tests <- Test code (in C language) |
| └── xcode <- Xcode support (for MacOSX compile) |
| |
| |
| Follow the instructions in COMPILE.TXT for how to compile and run test code. |
| |
| Note: if you find some strange bugs, it is recommended to firstly clean |
| the code and try to recompile/reinstall again. This can be done with: |
| |
| $ ./make.sh |
| $ sudo ./make.sh install |
| |
| Then test Capstone with cstool, for example: |
| |
| $ cstool x32 "90 91" |
| |
| At the same time, for Java/Ocaml/Python bindings, be sure to always use |
| the bindings coming with the core to avoid potential incompatibility issue |
| with older versions. |
| See bindings/<language>/README for detail instructions on how to compile & |
| install the bindings. |
| |
| |
| Coding style |
| ------------ |
| - C code follows Linux kernel coding style, using tabs for indentation. |
| - Python code uses 4 spaces for indentation. |
| |
| 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 [docs/AutoSync.md](docs/AutoSync.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. |
| |
| <!-- TODO: Move this info to the auto-sync docs --> |
| |
| Obviously, you first need to write all the logic and put it in a new directory arch/newarch |
| Then, you have to modify other files. |
| (You can look for one architecture such as EVM in these files to get what you need to do) |
| |
| Integrate: |
| - cs.c |
| - cstool/cstool.c |
| - cstool/cstool_newarch.c: print the architecture specific details |
| - include/capstone/capstone.h |
| - include/capstone/newarch.h: create this file to export all specifics about the new architecture |
| |
| Compile: |
| - CMakeLists.txt |
| - Makefile |
| - config.mk |
| |
| Tests: |
| - tests/Makefile |
| - tests/test_basic.c |
| - tests/test_detail.c |
| - tests/test_iter.c |
| - tests/test_newarch.c |
| - suite/fuzz/platform.c: add the architecture and its modes to the list of fuzzed platforms |
| - suite/capstone_get_setup.c |
| - suite/MC/newarch/mode.mc: samples |
| - suite/test_corpus.py: correspondence between architecture and mode as text and architecture number for fuzzing |
| |
| Bindings: |
| - bindings/Makefile |
| - bindings/const_generator.py: add the header file and the architecture |
| - bindings/python/Makefile |
| - bindings/python/capstone/__init__.py |
| - bindings/python/capstone/newarch.py: define the python structures |
| - bindings/python/capstone/newarch_const.py: generate this file |
| - bindings/python/test_newarch.py: create a basic decoding test |
| - bindings/python/test_all.py |
| |
| Docs: |
| - README.md |
| - HACK.txt |
| - CREDITS.txt: add your name |
