Magic-Mirror/radare2
1
0
Fork 0
mirror of https://github.com/radareorg/radare2.git synced 2024-12-03 10:51:01 +00:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

Update some docs

Browse Source
This commit is contained in:
pancake 2024-02-29 11:50:53 +01:00
parent c68246f449
commit 9eff2623b6
9 changed files with 187 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/avr.md
View File

@ -1,30 +1,51 @@
AVR (arduino, atmega128, ..)
============================
# AVR (arduino, atmega128, ..)
This document explains how to debug an AVR microcontroller connecting with the JTAG interface via USB using the GDB protocol, commonly used by Arduino.
On some systems it is necessary to install a driver and the SDK. You can find the links below
## macOS installation
Install JTAG serial driver:
https://www.wch.cn/download/CH341SER_MAC_ZIP.html
* [https://www.wch.cn/download/CH341SER_MAC_ZIP.html](https://www.wch.cn/download/CH341SER_MAC_ZIP.html)
Install SDK from Arduino:
https://www.arduino.cc/en/Main/Software
echo 'PATH="/Applications/Arduino.app//Contents/Java/hardware/tools/avr/bin/:$PATH"' >> ~/.profile
* [https://www.arduino.cc/en/Main/Software](https://www.arduino.cc/en/Main/Software)
```sh
echo 'PATH="/Applications/Arduino.app//Contents/Java/hardware/tools/avr/bin/:$PATH"' >> ~/.profile
```
## Plugin setup
Install avarice, the gdbserver <-> jtag:
r2pm -i avarice
```sh
r2pm -i avarice
```
Run the proxy:
r2pm -r avarice --jtag /dev/tty.wch* --mkI :4242
```sh
r2pm -r avarice --jtag /dev/tty.wch* --mkI :4242
```
## Connecting to the gdb server
Using GDB:
(avr-gdb) target remote :4242
```sh
(avr-gdb) target remote :4242
```
In another terminal now run:
r2 -a avr -d gdb://localhost:4242
```sh
r2 -a avr -d gdb://localhost:4242
```
NOTE: Right now the avr debugger is pretty broken, the memory and register reads result in in correct data.
## Final Notes
Right now the avr debugger is pretty broken, the memory and register reads result in in correct data.

34
doc/brainfuck.md
View File

@ -1,36 +1,36 @@
Brainfuck support for r2
========================
# Brainfuck support for r2
Plugins for brainfuck:
- `asm.bf` - brainfuck assembler and disassembler
- `debug.bf` - debugger using bfvm
- `arch.bf` - code analysis for brainfuck
- `bp.bf` - breakpoints support (experimental)
* `debug.bf` - debugger using bfvm
* `arch.bf` - code analysis for brainfuck
* `bp.bf` - breakpoints support (experimental)
To debug a brainfuck program:
r2 -D bf bfdbg:///tmp/bf
```sh
r2 -D bf bfdbg:///tmp/bf
> dc # continue
> x@scr # show screen buffer contents
> dc # continue
> x@scr # show screen buffer contents
```
The debugger creates virtual sections for code, data, screen and input.
TODO
----
- add support for comments, ignore invalid instructions as nops
- enhance io and debugger plugins to generate sections and set arch opts
## TODO
Hello World
===========
* add support for comments, ignore invalid instructions as nops
* enhance io and debugger plugins to generate sections and set arch opts
```
## Hello World
```brainfuck
>+++++++++[<++++++++>-]<.>+++++++[<++++>-]<+.+++++++..+++.[-]
>++++++++[<++++>-] <.>+++++++++++[<++++++++>-]<-.--------.+++
.------.--------.[-]>++++++++[<++++>- ]<+.[-]++++++++++.
```
```
```sh
$ cat << EOF
>+++++++++[<++++++++>-]<.>+++++++[<++++>-]<+.+++++++..+++.[-]>++++++++[<++++>-] <.>+++++++++++[<++++++++>-]<-.--------.+++.------.--------.[-]>++++++++[<++++>- ]<+.[-]++++++++++.
EOF

20
doc/calling-conventions.md
View File

@ -1,15 +1,12 @@
Calling Conventions profiles
============================
# Calling Conventions
Radare2 uses calling conventions to help in identifying function formal arguments and return types. It is used also as guide for basic function prototype (WIP at the time of writing this wiki).
Profile grammar
===============
## Profile grammar
Since the profiles are based on sdb database, Creating one is as simple as creating group of `key=value` pairs in text file. then parsing it into sdb data file.
Attribute list
==============
## Attribute list
Note that you will substitute `x` for the calling convention name you will use.
@ -27,13 +24,10 @@ Note that you will substitute `x` for the calling convention name you will use.
`cc.x.ret=reg`: used to set where the return value is stored for the given calling convention.
File Path
=========
## File Path
In order to integrate the calling convention profile you created with the r2 source, few set of conventions should be followed:
- Store the unparsed sdb file in `path-to-radare2-source/libr/anal/d`.
- If you want the sdb to be loaded for specific architecture the file name should follow this convention `cc-arch-bits`, for example to create profile that loads automatically for x86 arch with 16 bits call the file `cc-x86-16`
- In the file `path-to-radare2-source/libr/anal/d/makefile` add entry `F+= cc-arch-bits` with desired arch and bits and you should be ready to go.
* Store the unparsed sdb file in `path-to-radare2-source/libr/anal/d`.
* If you want the sdb to be loaded for specific architecture the file name should follow this convention `cc-arch-bits`, for example to create profile that loads automatically for x86 arch with 16 bits call the file `cc-x86-16`
* In the file `path-to-radare2-source/libr/anal/d/makefile` add entry `F+= cc-arch-bits` with desired arch and bits and you should be ready to go.

45
doc/capstone.md
View File

@ -1,31 +1,44 @@
Capstone
========
# Capstone
Capstone Engine is the disassembler engine used by radare2 by default for
some architectures.
R2 supports capstone 3, 4 and 5.
R2 supports capstone 4 and 5.
* capstone3: legacy support (only for Debian probably)
* capstone4: stable release at the moment of writing this
* capstone5: next branch, still under development (default)
* capstone3: legacy support (only available on Debian systems probably)
* capstone4: previous release, found in many distros, not recommended if you care about modern x86 or arm64 binaries
* capstone5: stable release (default)
* capstone6: (aka next) abi/api breaking, not supported yet (see the section below)
By default r2 will build statically against capstone5 (unless you specify
the --with-capstone4 or --with-syscapstone configure flags)
Using system capstone
---------------------
## Capstone6
You can link capstone dynamically (by using --with-syscapstone), this will skip all the
download and build steps of capstone inside `shlr/capstone`.and just link against the version
of capstone found in the system. That's what distros usually want.
Note that capstone6 is still under development (not yet released at the moment of writing this document), so APIs are changing frequently and there are so many changes in APIs and enums that will break support with all the previous versions of Capstone.
NOTE: that building against capstone-master is cursedd, because cs-master reports v5, but code
is from v4, so it fails to compile because of missing enums and archs.
## Using System Capstone
v4
--
You can link capstone dynamically (by using --with-syscapstone), this will skip all the download and build steps of capstone inside `shlr/capstone`.and just link against the version of capstone found in the system. That's what distros usually want.
**NOTE**: that building against capstone-master is cursedd, because cs-master reports v5, but code is from v4, so it fails to compile because of missing enums and archs.
## v4
To build r2 against capstone4 use the following oneliner:
sys/install.sh --with-capstone4
```sh
sys/install.sh --with-capstone4
```
You can find other capstone flags
```sh
$ ./configure --help | grep capstone
--without-capstone dont build the capstone dependency
--with-capstone-next build next branch of the capstone disassembler
--with-capstone5 build v5 branch of capstone5 (default)
--with-capstone4 build v4 branch of capstone
--with-syscapstone force to use system-wide capstone
--without-syscapstone avoid the system-wide capstone
```

8
doc/cross-compile.md
View File

@ -1,6 +1,8 @@
# Crosscompiling
So you want to cross-compile radare to some exotic architecture? Use docker and you'll save some headache:
https://github.com/dockcross/dockcross
* [https://github.com/dockcross/dockcross](https://github.com/dockcross/dockcross)
Here's and example on how changes required for i.e ARMv5 (no hard float) borrowed from `mk/armel.mk`:
@ -20,14 +22,14 @@ CC_AR=${CROSS_ROOT}/${CROSS_TRIPLET}-ar -r ${LIBAR}
After defining your new `mk/arch.mk` file it should be pretty straightforward to install the `dockcross`
tool from one of its own containers:
```
```bash
$ docker run thewtex/cross-compiler-linux-armv5 > ~/bin/dockcross
$ chmod +x ~/bin/dockcross
```
And then, compile normally from inside the container:
```
```bash
$ dockcross --image thewtex/cross-compiler-linux-armv5 ./configure --with-compiler=armel --host=armel
$ dockcross make
```

5
doc/ida.md
View File

@ -1,7 +1,6 @@
IDA
======
# IDA
You can find conversion scripts to work between radare2 and IDA files (IDC, IDB...) here:
* https://github.com/radareorg/radare2-extras/tree/master/r2ida
[https://github.com/radareorg/radare2-extras/tree/master/r2ida](https://github.com/radareorg/radare2-extras/tree/master/r2ida)

38
doc/macros
View File

@ -1,38 +0,0 @@
Examples of Macros
--------------------
NOTE: in radare2, do not add a space between the "," and the next
command otherwise you are in for pain...
1.) Hello, world
(hello,?e Hello World)
.(hello)
2.) Looping inside a macro
(loop_macro,f cnt=3,loop:,?e hello `?vi cnt`,f cnt=`?vi cnt-1`,?= cnt,?!(),.loop:)
.(loop_macro)
Backtrace implementation for x86-64:
------------------------------------
(backtrace,
aa
f prev @ rsp
f base@ rbp
loop:
f next @ `pq 1 @base~[1]`,
f cont @ `pq 1 @base+8~[1]`,
?= next
??()
?= next-0xffffffffffffffff
??()
?= cont-0xffffffffffffffff
??()
?e StackFrame at `?v next` with size `?vi base-prev`
x base-prev@base+16
?e Code: `?v cont`
pdf @ cont
f prev@base
f base@next
.loop:
)
.(backtrace)

44
doc/macros.md Normal file
View File

@ -0,0 +1,44 @@
# Examples of Macros
Macros are defined and executed with the parenthesis command, you may want to quote them using the `'` character at the begining of the line, because the `;` character is used to separate the statements inside them
* Hello, world
```
'(hello;?e Hello World)
.(hello)
```
* Looping inside a macro
```
'(loop_macro;f cnt=3;loop:;?e hello `?vi cnt`;f cnt=`?vi cnt-1`;?= cnt;?!();.loop:)
.(loop_macro)
```
## Backtrace implementation for x86-64:
```
'(backtrace;
aa
f prev @ rsp
f base@ rbp
loop:
f next @ `pq 1 @base~[1]`,
f cont @ `pq 1 @base+8~[1]`,
?= next
??()
?= next-0xffffffffffffffff
??()
?= cont-0xffffffffffffffff
??()
?e StackFrame at `?v next` with size `?vi base-prev`
x base-prev@base+16
?e Code: `?v cont`
pdf @ cont
f prev@base
f base@next
.loop:
)
.(backtrace)
```

105
doc/siol.md
View File

@ -1,77 +1,76 @@
SIOL - Simple IO Layer
======================
# SIOL - Simple IO Layer
Top-Down-View of siol
---------------------
## Top-Down-View of siol
+==================+
| Write-Mask |
+==================+
| Buffer | <--- maybe this could be deprecated, I see no usecase for the buffer
+==================+
| Cache (V) |
+==================+ +========================+
| Maps | <=== | Sections (transformed) |
+==================+ +========================+
| Descs |
| +===========+
| | Cache (P) |
+======+===========+
| Plugin |
+==================+
```
+==================+
| Write-Mask |
+==================+
| Buffer | <--- maybe this could be deprecated, I see no usecase for the buffer
+==================+
| Cache (V) |
+==================+ +========================+
| Maps | <=== | Sections (transformed) |
+==================+ +========================+
| Descs |
| +===========+
| | Cache (P) |
+======+===========+
| Plugin |
+==================+
```
Maps
----
## Maps
every map has a mapid which is a unique identifier. Code from the outside of RIO shall use this id instead of a pointer. This may cost performance, but pointers can hurt you.
Every map has a mapid which is a unique identifier. Code from the outside of RIO shall use this id instead of a pointer. This may cost performance, but pointers can hurt you.
Mapping information in the map:
- from
- to
- delta
- fd
* from
* to
* delta
* fd
Section Transformation
----------------------
atm there are 3 different transformation-targets:
## Section Transformation
- Hexeditor
- Analysis
- Emulation
At the moment there are 3 different transformation-targets:
* Hexeditor
* Analysis
* Emulation
Mapping information in the section:
- addr
- size
- vaddr
- vsize
- fd
* addr
* size
* vaddr
* vsize
* fd
A section can be related to 2 maps:
- memmap
- filemap
* memmap
* filemap
Hexeditor-Transformation:
- check if addr != vaddr, if so continue
- create a map with the size of min (size, vsize), that maps the to fd corresponding desc to vaddr, starting at addr
- filemap is set to the id of the map
- memmap stays 0
* check if addr != vaddr, if so continue
* create a map with the size of min (size, vsize), that maps the to fd corresponding desc to vaddr, starting at addr
* filemap is set to the id of the map
* memmap stays 0
Analysis-Transformation:
- when vsize <= size perform Hexeditor-Transformation, and you're done
- create a map with the size of size, that the to fd corresponding vaddr, starting at addr
- filemap is set to the id of the map
- open a new desc, using the null-plugin, with the size of vsize - size
- create another map with the size of vsize - size, that maps the new desc to vaddr + size, starting at 0x0
- memmap is set to the id of the second map
* when vsize <= size perform Hexeditor-Transformation, and you're done
* create a map with the size of size, that the to fd corresponding vaddr, starting at addr
* filemap is set to the id of the map
* open a new desc, using the null-plugin, with the size of vsize - size
* create another map with the size of vsize - size, that maps the new desc to vaddr + size, starting at 0x0
* memmap is set to the id of the second map
Emulation-Transformation:
- when the section does not allow write-access perform Analysis-Transformation, and you're done
- open a new desc with write-permissions, using the malloc-plugin, with the size of vsize
- copy min (size, vsize) bytes fram the desc, that fd refers to, starting at addr, to the new desc, starting at 0x0
- create a map with the size of vsize, that maps the new desc to vaddr, starting at 0x0
* when the section does not allow write-access perform Analysis-Transformation, and you're done
* open a new desc with write-permissions, using the malloc-plugin, with the size of vsize
* copy min (size, vsize) bytes fram the desc, that fd refers to, starting at addr, to the new desc, starting at 0x0
* create a map with the size of vsize, that maps the new desc to vaddr, starting at 0x0