Skip to content

Added Linux vs. Windows note, llvm-symbolizer tip, various other minor notes and clarifications #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: doc-fixups
Choose a base branch
from
Open

Added Linux vs. Windows note, llvm-symbolizer tip, various other minor notes and clarifications #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion suite/auto-sync/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ Please refer to [intro.md](intro.md) for an introduction about this tool.

## Install

> ⚠️
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use the Github markdown highlighting for this:
https://github.com/orgs/community/discussions/16925

> Auto-Sync only runs on Linux, running on Windows is desirable but not a priority at the moment
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better just state it and link the issue: capstone-engine#2755.
So people have a place to check for updates and complain. Also below.


#### Setup Python environment and Tree-sitter

```
Expand All @@ -36,6 +39,7 @@ pip install -e .
#### Clone Capstones LLVM fork and build `llvm-tblgen`

```bash
cd <capstone-root>/suite/auto-sync/
git clone https://github.com/capstone-engine/llvm-capstone vendor/llvm_root/
cd vendor/llvm_root/llvm-capstone
git checkout auto-sync
Expand All @@ -44,7 +48,7 @@ cd build
# You can also build the "Release" version
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ../llvm
cmake --build . --target llvm-tblgen --config Debug
cd <capstone-root>/suite/auto-sync/
cd ..
```

#### Install `llvm-mc` and `FileCheck`
Expand All @@ -55,6 +59,7 @@ You can also get the binaries [here](https://releases.llvm.org/download.html) or
install it with your package manager (usually something like `llvm-18-dev`).
Just ensure it is in your `PATH` as `llvm-mc` and `FileCheck` (not as `llvm-mc-18` or similar though!).

`llvm-symbolizer` is also a useful tool to display human-readable stacktraces when LLVM crashes with a stacktrace, optionally make sure you have it on `PATH` or run the crashing command prefixed with `LLVM_SYMBOLIZER_PATH=<path-to-llvm-symbolizer-binary>`
## Architecture

Please read [ARCHITECTURE.md](https://github.com/capstone-engine/capstone/blob/next/docs/ARCHITECTURE.md) to understand how `Auto-Sync` works.
Expand Down
10 changes: 7 additions & 3 deletions suite/auto-sync/RefactorGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ Note:
- `PrinterCapstone` is the class defined in `llvm-capstone/llvm/utils/TabelGen/PrinterCapstone.cpp`
- Always attempt to make the translated C file behave as closely as possible to the original C++ file! This greatly helps debugging and assures that Capstone behaves almost exactly the same as original LLVM.


> ⚠️
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also here

> Refactoring an architecture to Auto-Sync is only possible on Linux, running on Windows is desirable but not a priority at the moment
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

capstone-engine#2755


- ### Prepare
- Read `CONTRIBUTING.md`
- Read `docs/ARCHITECTURE.md`
Expand All @@ -33,7 +37,7 @@ Note:
- Clone and build `llvm-tblgen` (see docs)
- Quickly check options of the updater `ASUpdater -h`
- Add Arch name in `Target.py`
- In [llvm-capstone](https://github.com/capstone-engine/llvm-capstone) handle arch in `PrinterCapstone.cpp::decoderEmitterEmitDecodeInstruction()` (add decoder function)
- In [llvm-capstone](https://github.com/capstone-engine/llvm-capstone) handle arch in `PrinterCapstone.cpp::decoderEmitterEmitDecodeInstruction()` (add decoder function), rebuild for the changes to take effect
[!NOTE] Architecture specific code generation.
There are several oddities of architectures which require slightly different generated code.
If you search through `PrinterCapstone.cpp` for architecture names like `AArch64`, `ARM`, or `Sparc` you can see how these are handled.
Expand All @@ -42,8 +46,8 @@ Note:
- Check if `inc` files in `build` look good.
- ### Translation and Patching
- Check for template functions in `<ARCH>InstPrinter.cpp` and `<ARCH>Disassember.cpp`
- Copy new config in `arch_conf.json` (LoongArch for a minimal example).
- Don't forget to add `ARCHIntPrinter.cpp` to the list of the `AddCSDetail` tests!
- Copy new config in `arch_config.json` (LoongArch for a minimal example).
- Don't forget to add `ARCHIntPrinter.cpp` to the list of the `AddCSDetail` tests defined earlier in the json file!
- Add as a minimum the `<ARCH>InstPrinter.cpp`, `<ARCH>InstPrinter.h` and `<ARCH>Disassembler.cpp` to the translation list.
- Tip: The variables use in there are defined in `path_vars.json`
- Add architecture specific includes in `Patches/Includes.py`. Copy the code from another architecture for the beginning.
Expand Down
Loading