Skip to content

Commit b9ce76e

Browse files
officialcjuniorbemojo2021
authored and
wargio
committed
Document CPU and platform profiles (#65)
* new tutorial for find the easy pass of hackthebox challenges. (#63) Add a new tutorial for finding the easy pass of hackthebox challenges * Fix the broken links due names being lowercase. (#64) * Document CPU and platform profiles * Document the configuration variable `asm.platform` * Address changes and wrap the lines up nicely Co-authored-by: bemojo2021 <85988120+bemojo2021@users.noreply.github.com>
1 parent 6b404af commit b9ce76e

File tree

3 files changed

+96
-0
lines changed

3 files changed

+96
-0
lines changed

‎src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@
5656
* [Symbols information](analysis/symbols.md)
5757
* [Signatures](signatures/zignatures.md)
5858
* [Graph commands](analysis/graphs.md)
59+
* [CPU and platform profiles](analysis/cpu_platform_profiles.md)
5960
* [Scripting](scripting/intro.md)
6061
* [Loops](scripting/loops.md)
6162
* [Macros](scripting/macros.md)

‎src/analysis/cpu_platform_profiles.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# CPU and platform profiles
2+
3+
## The motivation
4+
5+
The computer ecosystem, especially in embedded systems is vast and growing and is thus
6+
diverse and is full of trivial differences. CPUs and development boards differ by minor and sometimes
7+
large differences in their design, ports, MMIO registers and other peripherals. Rizin handles these
8+
differences by storing the data regarding each CPUs and platforms in [SDB](https://book.rizin.re/basic_commands/sdb.html?highlight=SDB#sdb) files in a standard format, instead of hardcoding them with each of the
9+
disassembler plugins. This information will be parsed and added as flags and comments during the analysis
10+
loop and will show up in the disassembly and other places, making reverse engineering on those particular
11+
chips ets is much easier. This also helps in easy addition of a new port, in maintenance and in user-friendliness.
12+
13+
## How it works
14+
15+
### CPU profiles
16+
17+
All the specifics pertaining to a CPU is written down in a CPU profile. It is designed in a way that allows you
18+
to enter CPU specefic values like: size of the RAM (`RAM_SIZE`), size of the ROM (`ROM_SIZE`) and many more.
19+
CPU profiles can be selected using the configuration variable `asm.cpu`. Firstly, Rizin checks whether the
20+
a CPU profile exists for the selected CPU and architecture. If it exists, Rizin generates the filepath of the
21+
profile and gets to a stage where it's ready to be loaded up. During analysis (`aa`), it's loaded up and the values are
22+
parsed and handled. CPU profiles also allow you to add information regarding the IO and extended IO registers of a CPU.
23+
The information pertaining to the IO and extended IO registers are added as flags at their corresponding offsets.
24+
25+
The CPU profile of AVR's ATTiny88 CPU looks like this:
26+
27+
```config
28+
RAM_SIZE=512
29+
ROM_SIZE=8192
30+
INTERRUPT_VECTOR_SIZE=2
31+
32+
PINB=io
33+
PINB.address=0x03
34+
DDRB=io
35+
DDRB.address=0x04
36+
PORTB=io
37+
```
38+
Here, `PINB` is the name and `io` is the type of the port and this will be added as a
39+
flag at the offset `0x03`. The type can be `ext_io` if it's an extended IO register, as well. Both will be added
40+
as [flags](https://book.rizin.re/basic_commands/flags.html?highlight=flags#flags) and the only difference between
41+
them is that they will be added in different [flagspaces](https://book.rizin.re/refcard/intro.html?highlight=flagspa#flagspaces).
42+
43+
CPU profiles also support mapping the ROM. According the `ROM_ADDRESS` and `ROM_SIZE`, a [section](https://book.rizin.re/basic_commands/sections.html?highlight=section#sections) named `.rom` will be added during analysis.
44+
45+
#### Adding CPU profiles
46+
47+
CPU profiles are stored in SDB files under the directory `lirbz/asm/cpus` and that's where you will have to put
48+
your new profile. The files follow a naming convention like `arch-cpu`. You can see the complete list of things
49+
that are parsed at `librz/analysis/arch_profile.c` and if necessary, a new key can be easily added.
50+
51+
To add a new CPU profile, firstly make sure that you have the name of the CPU defined in the list of CPUs defined
52+
by the variable `cpus` in the corresponding architecture's disassembler plugin (`RzAsmPlugin`). Then, simply add
53+
the SDB file in the directory, add the entry in the `meson.build` of the same directory and build again. Choose
54+
the right CPU and architecture and analyze again (`aa`) to load up the CPU profile.
55+
56+
For reference, you can see the previously added CPU profile of ATmega16 here: [librz/asm/cpus/avr-ATmega16.sdb.txt](https://github.com/rizinorg/rizin/blob/dev/librz/asm/cpus/avr-ATmega16.sdb.txt).
57+
58+
### Platform profiles
59+
60+
Platform profiles are designed with an idea to support adding information that is pertaining to a specific board
61+
or a micro controller. For example, most of the Raspberry Pi-s use a specific Broadcom chip and its peripherals
62+
like registers and interrupts will be the same for all Raspberry Pi-s. These profiles can be selected using the
63+
configuration variable `asm.platforms` and is loaded during analysis (`aa`). If you run `e asm.platform=?`, you
64+
can see the supported platforms by the selected architecture and CPU.
65+
66+
Let's have a look at Broadcom 2835's platform profile:
67+
68+
```config
69+
AUX_IRQ=name
70+
AUX_IRQ.address=0x7e215000
71+
AUX_IRQ.comment=Auxiliary Interrupt status
72+
73+
AUX_MU_IO_REG=name
74+
AUX_MU_IO_REG.address=0x7e215040
75+
AUX_MU_IO_REG.comment=Mini UART I/O Data
76+
```
77+
78+
Just like in CPU profiles, the `name` will be added as a flag and the `comment` as a [comment](https://book.rizin.re/disassembling/adding_metadata.html?highlight=Comment#adding-metadata-to-disassembly) (`CCu`).
79+
80+
#### Adding platform profiles
81+
82+
Platform profiles are stored in `librz/asm/platforms/` and that's where you will have to put your profile. They
83+
follow a naming convention like `arch-cpu-platform`.
84+
85+
To add a new platform profile, we will have to define the name of the platform in the variable `platforms` in
86+
the `RzAsmPlugin` definition corresponding architecture's disassembler plugin. You will also need to add the
87+
CPU is it's not already added. Then, add the entry in the `meson.build` of the same directory and build again.
88+
Choose the right CPU, architecture and platform and analyze again (`aa`).
89+
90+
You can also check out the platform profiles that were previously added at [librz/asm/platforms/arm-arm1176-bcm2835.sdb.txt](https://github.com/rizinorg/rizin/blob/dev/librz/asm/platforms/arm-arm1176-bcm2835.sdb.txt).

‎src/configuration/evars.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,11 @@ When turned on, the raw bytes will be displayed along with the instructions:
7272

7373
You can use this configuration variable to define the CPU type. For example, if you had picked the architecture as AVR, you can choose your CPU type (ATmega1281, ATmega2561, etc) using `asm.cpu`.
7474

75+
### asm.platform: `string`
76+
77+
You can use this configuration variable to select the platform and it'll load up the corresponding
78+
platform profile during analysis. See the section about [CPU and platform profiles](https://book.rizin.re/analysis/cpu_platform_profiles.html) for more information.
79+
7580
### asm.flags: `bool`
7681

7782
When set to "true", the disassembler view will have the flags column.

0 commit comments

Comments
 (0)