This is a Hexagon disassembly and analysis plugin generator for rizin
.
It uses the LLVM target description source code
of the Hexagon architecture and additional hand-written code.
This plugin is under continuous work. So checkout the Github issues for missing features or not yet fixed bugs.
-
For formatting we need
clang-format
. If it is not available on your distribution, you can install it from https://apt.llvm.org/. -
Python requirements are in
requirements.txt
-
As a developer you also need
black
,flake8
,reuse
.
We take all the information about the Hexagon instructions and operands from the many LLVM target description files.
Luckily there is a tool which combines all the information of those files into one .json
file which we name Hexagon.json
.
So Hexagon.json
will hold all information about the Hexagon instructions and operands.
In order to generate the Hexagon.json
file we need the llvm-tblgen
binary.
Unfortunately llvm-tblgen
is usually not provided via the package manager. You have to compile LLVM by yourself.
Please follow the LLVM docs (Build the release version to save a lot of RAM).
llvm-tblgen
should be in <somewhere>/llvm-project/build/bin/
after the build.
Please add this directory to your PATH
.
Python 3.11
We require Python 3.11
. Please follow the install-instructions from the Python documentation.
Clone repository
git clone --recurse-submodules https://github.com/rizinorg/rz-hexagon.git
cd rz-hexagon/
Setup a virtual environment
python3 -m venv .venv
# Activate the virtual environment.
# This step might differ from shell to shell (the one below is for bash/zsh).
# Take a look at the Python docs if you are using another one.
# https://docs.python.org/3.11/library/venv.html?highlight=virtual%20environment
source .venv/bin/activate
Install rz-hexagon
as package
pip3 install -r requirements.txt -r rzil_compiler/requirements.txt
# If you enjoy some colors
pip3 install -r optional_requirements.txt
# Install as develop package
pip3 install -e rzil_compiler/
pip3 install -e .
The first time you run the generator you need to add the -j
option.
This will generate the Hexagon.json
from the current LLVM
source.
./LLVMImporter.py -j
It processes the LLVM definition files and generates C code in ./rizin
and its subdirectories.
Copy the generated files to the rizin
directory with
rsync -a rizin/ <rz-src-path>/
You can run the tests with:
cd Tests
python3 -m unittest discover -s . -t .
**Before you open a PR please run and fix the warnings.:
black -l 120 $(git ls-files '*.py')
flake8 --select=W504 --ignore=E203,W503 --max-line-length=120 $(git ls-files '*.py')
reuse lint
-
The best way to start is to take a look at an instruction in
Hexagon.json
. We take all information from there and knowing the different objects makes it easier to understand the code. -
If you need any information about a llvm specific term or variable name from the
Hexagon.json
file a simplegrep -rn "term" llvm-project/llvm/lib/Target/Hexagon/
will usually help. -
If you parse LLVM data always end it with an exception else statement:
if x: ... elif y: ... elif z: ... else: raise ImplementationException("This case seems to be new, please add it.")
-
Names of variables which holds data directly taken from the
Hexagon.json
file should have a name which starts withllvm_
.For example:
llvm_in_operands
holds a list with the content ofHexagon.json::[Instr].InOperandList
.llvm_syntax
holds:$Rdd8 = combine(#0,#$Ii)
(the syntax in LLVM style).syntax
holds:Rdd = combine(#0,#Ii)
(cleaned up LLVM syntax)Instruction.operands
is a dictionary which containsRegister
andImmediate
Python objects.
-
Please take a brief look at the Rizin development guide if you plan to change C code.
- Rot127
- Anton Kochkov
- Florian Märkl