capstone

1
Code structure
2
--------------
3

4
Capstone source is organized as followings.
5

6
.                   <- core engine + README + COMPILE_CMAKE.TXT etc
7
├── arch            <- code handling disasm engine for each arch
8
│   ├── AArch64     <- AArch64 engine
9
│   ├── Alpha       <- Alpha engine
10
│   ├── ARM         <- ARM engine
11
│   ├── BPF         <- Berkeley Packet Filter engine
12
│   ├── EVM         <- Ethereum engine
13
│   ├── HPPA        <- HPPA engine
14
│   ├── M680X       <- M680X engine
15
│   ├── M68K        <- M68K engine
16
│   ├── Mips        <- Mips engine
17
│   ├── MOS65XX     <- MOS65XX engine
18
│   ├── PowerPC     <- PowerPC engine
19
│   ├── RISCV       <- RISCV engine
20
│   ├── SH          <- SH engine
21
│   ├── Sparc       <- Sparc engine
22
│   ├── SystemZ     <- SystemZ engine
23
│   ├── TMS320C64x  <- TMS320C64x engine
24
│   ├── TriCore     <- TriCore engine
25
│   └── WASM        <- WASM engine
26
├── bindings        <- all bindings are under this dir
27
│   ├── java        <- Java bindings + test code
28
│   ├── ocaml       <- Ocaml bindings + test code
29
│   └── python      <- Python bindings + test code
30
├── contrib         <- Code contributed by community to help Capstone integration
31
├── cstool          <- Cstool
32
├── docs            <- Documentation
33
├── include         <- API headers in C language (*.h)
34
├── msvc            <- Microsoft Visual Studio support (for Windows compile)
35
├── packages        <- Packages for Linux/OSX/BSD.
36
├── windows         <- Windows support (for Windows kernel driver compile)
37
├── suite           <- Development test tools - for Capstone developers only
38
├── tests           <- Test code (in C language)
39
└── xcode           <- Xcode support (for MacOSX compile)
40

41

42
Follow the instructions in COMPILE_CMAKE.TXT for how to compile and run test code.
43

44
Note: if you find some strange bugs, it is recommended to firstly clean
45
the code and try to recompile/reinstall again. This can be done with:
46

47
	$ ./make.sh
48
	$ sudo ./make.sh install
49

50
Then test Capstone with cstool, for example:
51

52
	$ cstool x32 "90 91"
53

54
At the same time, for Java/Ocaml/Python bindings, be sure to always use
55
the bindings coming with the core to avoid potential incompatibility issue
56
with older versions.
57
See bindings/<language>/README for detail instructions on how to compile &
58
install the bindings.
59

60

61
Coding style
62
------------
63
- C code follows Linux kernel coding style, using tabs for indentation.
64
- Python code uses 4 spaces for indentation.
65

66
Updating an Architecture
67
------------------------
68

69
The update tool for Capstone is called `auto-sync` and can be found in `suite/auto-sync`.
70

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

74
The documentation how to update with `auto-sync` or refactor an architecture module
75
can be found in [docs/AutoSync.md](docs/AutoSync.md).
76

77
If a module does not support `auto-sync` yet, it is highly recommended to refactor it
78
instead of attempting to update it manually.
79
Refactoring will take less time and updates it during the procedure.
80

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

87
Adding an architecture
88
----------------------
89

90
If your architecture is supported in LLVM or one of its forks, you can use `auto-sync` to
91
add the new module.
92

93
<!-- TODO: Move this info to the auto-sync docs -->
94

95
Obviously, you first need to write all the logic and put it in a new directory arch/newarch
96
Then, you have to modify other files.
97
(You can look for one architecture such as EVM in these files to get what you need to do)
98

99
Integrate:
100
- cs.c
101
- cstool/cstool.c
102
- cstool/cstool_newarch.c: print the architecture specific details
103
- include/capstone/capstone.h
104
- include/capstone/newarch.h: create this file to export all specifics about the new architecture
105

106
Compile:
107
- CMakeLists.txt
108
- Makefile
109
- config.mk
110

111
Tests:
112
- tests/Makefile
113
- tests/test_basic.c
114
- tests/test_iter.c
115
- tests/test_newarch.c
116
- suite/fuzz/platform.c: add the architecture and its modes to the list of fuzzed platforms
117
- suite/capstone_get_setup.c
118
- suite/MC/newarch/mode.mc: samples
119
- suite/test_corpus.py: correspondence between architecture and mode as text and architecture number for fuzzing
120
- suite/cstest/
121

122
Bindings:
123
- bindings/Makefile
124
- bindings/const_generator.py: add the header file and the architecture
125
- bindings/python/Makefile
126
- bindings/python/capstone/__init__.py
127
- bindings/python/capstone/newarch.py: define the python structures
128
- bindings/python/capstone/newarch_const.py: generate this file
129
- bindings/python/test_newarch.py: create a basic decoding test
130
- bindings/python/test_all.py
131

132
Docs:
133
- README.md
134
- HACK.txt
135
- CREDITS.txt: add your name
136