EljakimHerrewijnen/Gupje
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

moved docs to make it compatible with github pages

Browse Source
This commit is contained in:
Eljakim Herrewijnen 2024-11-19 21:13:50 +01:00
parent ec0f85b8b6
commit a31ecd313a
27 changed files with 780 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
build/

3
docs/.vscode/settings.json vendored Normal file
View File

@ -0,0 +1,3 @@
{
"esbonio.sphinx.confDir": ""
}

27
docs/Makefile Normal file
View File

@ -0,0 +1,27 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SPHINXAUTOBUILD = sphinx-autobuild
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
confluence:
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -E -a $(O)
livehtml:
@$(SPHINXAUTOBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --port 34343
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

35
docs/make.bat Normal file
View File

@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

59
docs/source/architectures/arm/debugger/arm_debugger_storage.rst Normal file
View File

@ -0,0 +1,59 @@
********************************
Debugger Storage Overview on ARM
********************************
Overview of the storage setup on ARM Thumb for the debugger.
To interact with this storage dump you can either dump the storage location and parse the entries or use the *utils/debugger/debugger_archs/armT_processor_state.py* processor state, which is also passed as an argument in **GA_arm_thumb_debugger**.
.. note:: All addresses below asume ``STORAGE_LOCATION`` + **Address**
+---------+-----------------+--------------------------------------------------------------------------------+
| Address | Function | Comment |
+=========+=================+================================================================================+
| 0x0 | R0 | Stores Register R0 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x4 | R1 | Stores Register R1 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x8 | R2 | Stores Register R2 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0xc | R3 | Stores Register R3 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x10 | R4 | Stores Register R4 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x14 | R5 | Stores Register R5 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x18 | R6 | Stores Register R6 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x1c | R7 | Stores Register R7 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x20 | R8 | Stores Register R8 (Indirect Function Call Target ``IFC``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x24 | R9 | Stores Register R9 (Platform Register ``P``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x28 | R10 | Stores Register R10 (Thread Pointer ``TP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x2c | R11 | Stores Register R11 (Frame Pointer ``FP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x30 | R12 | Stores Register R12 (Intra-Procedure-call-scratched-Register ``IP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x34 | R13 | Stores Register R13 (Stack Pointer ``SP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x38 | R14 | Stores Register R14 (Link Register ``LR``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x3c | R15 | Stores Register R15 (Program Counter ``PC``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| | | |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7d8 | DBG_MMU_DISABLE | **DISABLED** ``DEBUGGER`` Disable the MMU on entry and enable the MMU on leave |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7ec | DBG_JUMP_TO | ``DEBUGGER`` Address to jump to instead of the debugger |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7f0 | DBG_CONT_EXEC | ``DEBUGGER`` Do not jump in debugger but into |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7f4 | TEMP X0 | ``DEBUGGER`` Temporary storage for X0 value |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7f8 | Store X0 | ``DEBUGGER`` Stores exception id for the ``SMC`` call |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7fc | JUMP_ADDR | ``DEBUGGER`` Memory location that instructs the debugger where to jump to |
+---------+-----------------+--------------------------------------------------------------------------------+

5
docs/source/architectures/arm/index.rst Normal file
View File

@ -0,0 +1,5 @@
===
ARM
===
.. include:: debugger/arm_debugger_storage.rst

31
docs/source/architectures/arm64/aarch64_mmu.rst Normal file
View File

@ -0,0 +1,31 @@
******************************
Memory Managment Unit on ARM64
******************************
This part describes the memory managment unit on ARM64 and how it is used by the debugger.
Single Level Pagetable at EL3
=============================
The documentation described here can also be found at the `official ARM documentation <https://developer.arm.com/documentation/102416/0100/Single-level-table-at-EL3>`_.
Translation Regime
******************
Register ``TCR_ELx`` is used to control the **Tranlation Regime** for the pagetables. The documentation for the ``TCR_EL3`` can be found in the `official ARM documentation <https://developer.arm.com/documentation/ddi0500/d/system-control/aarch64-register-descriptions/translation-control-register--el3>`_.
Translation Table
*****************
The location of the page table is located in register ``ttbr0_el3``. Depending of the configuration of ``TCR_EL3`` the bits for address selection can change.
More documentation can be found `here <https://developer.arm.com/documentation/ddi0595/2021-06/AArch64-Registers/TTBR0-EL3--Translation-Table-Base-Register-0--EL3->`_
Pagetable Entry
***************
The following diagram shows the format of a stage 1 level 1 table entry on EL3.
.. image:: images/mmu/singlelevel_el3_pte.png
Automatic Paging
================
Automatic paging for page walking will be setup in the debugger.
For this the ``ARM64_Concrete_State`` contains a mmu with class ``ARM64_MMU``.

58
docs/source/architectures/arm64/aarch64_vbar.rst Normal file
View File

@ -0,0 +1,58 @@
**********************
Vector Tables in ARM64
**********************
A lot of this documentation can also be found in the `ARM SMC calling convention documentation <https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwitkfqjqNz5AhUJHuwKHZ3vAj4QFnoECBMQAQ&url=https%3A%2F%2Fdocumentation-service.arm.com%2Fstatic%2F5f8ea482f86e16515cdbe3c6%3Ftoken%3D&usg=AOvVaw3QI7Lwrcg6B3BmQ5syZV70>`_
Vector Exception Levels
=======================
In ARM64 each there is a Vector table for each Exception level, except for EL0. So, in practice there is a Vector table for:
* EL3 ``Secure Monitor Call (SMC)``
* EL2 ``Hyper Visor Call (HVC)``
* EL1 ``Super Visor Call (SVC)``
Documentation about this can be found in `the ARM documentation <https://developer.arm.com/documentation/100933/0100/AArch64-exception-vector-table>`_
.. image:: images/vector_table/vector_table_arm64.png
This vector table can be allocated and filled for each of the vector tables described above.
Setting the Vector Base Address
===============================
To set the location of this vector table a call ``MSR`` call can be done to ``VBAR_ELX`` which will write an address to that register. When an execption call is executed, this address is fetched and execution will move to that page, with the corresponding Execption Level(EL)
ARM SMC Calling Convention
==========================
When doing an SMC call in arm64 a synchronous exception is generated that is handled by the secure monitor in EL3.
The SMC call can be in both 32 and 64 bit mode, depending on various bits in the instruction.
For most phones this will be in 64 bit mode.
When doing a SMC call, the register ``ELR_ELn`` is updated to show the location of where the call came from.
This is the address after the call where the exception came from. When doing an ``ERET`` instruction this value is written to the ``PC``.
Stack Pointers
**************
Each Exception Level has its own stack pointers. The registers for these are:
* SP_EL0
* SP_EL1
* SP_EL2
* SP_EL3
``SP_EL3`` is innacessible in EL3, to read it you need to read the ``SP``.
****************************
Debugger VBAR Implementation
****************************
The debugger uses a SMC call to insert a breakpoint at any address. When a SMC call is thrown the processor jumps to the address pointed to in the ``VBAR_EL3`` register.
This register **has to ** point to the debugger.
The debugger will first store all the registers in the storage location, overwrite the stack pointer and send the hello message ``b'GiAs'`` to the host.
An overview of what is happening when a SMC call is dan can be seen below:
.. image:: images/vector_table/smc_handling_arm64.jpg
.. warning:: Currently register X15 gets corrupted when an SMC call is handled.

147
docs/source/architectures/arm64/debugger/arm64_debugger_storage.rst Normal file
View File

@ -0,0 +1,147 @@
**********************************
Debugger Storage Overview on ARM64
**********************************
Overview of the storage setup on ARM64 for the debugger. To interact with this storage dump you can either dump the storage location and parse the entries or use the *utils/debugger/debugger_archs/arm64_processor_state.py* processor state, which is also passed as an argument in **GA_arm64_debugger**.
.. note:: All addresses below asume ``STORAGE_LOCATION`` + **Address**
+---------+------------------------+----------------------------------------------------------------------------------------+
| Address | Function | Comment |
+=========+========================+========================================================================================+
| 0x0 | X0 | Stores Register X0 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x8 | X1 | Stores Register X1 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x10 | X2 | Stores Register X2 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x18 | X3 | Stores Register X3 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x20 | X4 | Stores Register X4 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x28 | X5 | Stores Register X5 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x30 | X6 | Stores Register X6 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x38 | X7 | Stores Register X7 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x40 | X8 | Stores Register X8 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x48 | X9 | Stores Register X9 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x50 | X10 | Stores Register X10 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x58 | X11 | Stores Register X11 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x60 | X12 | Stores Register X12 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x68 | X13 | Stores Register X13 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x70 | X14 | Stores Register X14 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x78 | X15 | Stores Register X15 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x80 | X16 | Stores Register X16 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x88 | X17 | Stores Register X17 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x90 | X18 | Stores Register X18 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x98 | X19 | Stores Register X19 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xa0 | X20 | Stores Register X20 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xa8 | X21 | Stores Register X21 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xb0 | X22 | Stores Register X22 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xb8 | X23 | Stores Register X23 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xc0 | X24 | Stores Register X24 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xc8 | X25 | Stores Register X25 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xd0 | X26 | Stores Register X26 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xd8 | X27 | Stores Register X27 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xe0 | X28 | Stores Register X28 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xe8 | X29 | Stores the ``Frame Pointer`` |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xf0 | X30 | Stores the ``Link Register`` |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xf8 | SP | Stores the ``Stack Pointer`` |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x100 | TTBR0_EL3 | Stores ``TTBR0_EL3`` |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x108 | TTBR0_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x110 | TTBR0_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x118 | SCTLR_EL3 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x120 | SCTLR_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x128 | SCTLR_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x130 | VBAR_EL3 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x130 | VBAR_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x140 | VBAR_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x148 | TCR_EL3 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x150 | TCR_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x158 | TCR_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x160 | ELR_EL3 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x168 | ELR_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x170 | ELR_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x178 | SP_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x180 | SP_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x188 | SP_EL0 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x190 | SPSR_EL3 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x198 | SPSR_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x1a0 | SPSR_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x1a8 | MAIR_EL3 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x1b0 | MAIR_EL2 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x1b8 | MAIR_EL1 | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0x1c0 | CurrentEL | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| | | |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xfc0 | DBG_SETUP_JUMP | ``DEBUGGER`` Set to 0x77 to jump to ``DBG_SETUP_JUMP_ADDRESS`` and when DEVICE_SETUP=1 |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xfc8 | DBG_SETUP_JUMP_ADDRESS | ``DEBUGGER`` Address to jump to when ``DBG_SETUP_JUMP`` is set to *0x77* |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xfd0 | DBG_MMU_DISABLE | **DISABLED** ``DEBUGGER`` Disable the MMU on entry and enable the MMU on leave |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xfd8 | DBG_JUMP_TO | ``DEBUGGER`` Address to jump to instead of the debugger |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xfe0 | DBG_CONT_EXEC | ``DEBUGGER`` Do not jump in debugger but into |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xfe8 | TEMP X0 | ``DEBUGGER`` Temporary storage for X0 value |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xff0 | Store X0 | ``DEBUGGER`` Stores exception id for the ``SMC`` call |
+---------+------------------------+----------------------------------------------------------------------------------------+
| 0xff8 | JUMP_ADDR | ``DEBUGGER`` Memory location that instructs the debugger where to jump to |
+---------+------------------------+----------------------------------------------------------------------------------------+
.. note:: This memory segment is still being updated to add registers
When ``DBG_CONT_EXEC`` is set to **0x777** the debugger will not enter the debugger_main address, but instead restore the original processor state and jump into ``DBG_JUMP_TO``. This allows the debugger to be run without user interaction.

BIN
docs/source/architectures/arm64/images/mmu/singlelevel_el3_pte.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

BIN
docs/source/architectures/arm64/images/vector_table/smc_call_arm64.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/source/architectures/arm64/images/vector_table/smc_handling_arm64.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB

BIN
docs/source/architectures/arm64/images/vector_table/vector_table_arm64.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

9
docs/source/architectures/arm64/index.rst Normal file
View File

@ -0,0 +1,9 @@
=====
ARM64
=====
Documentation for the ARM64 architecture.
.. include:: aarch64_vbar.rst
.. include:: aarch64_mmu.rst
.. include:: system_configuration.rst
.. include:: debugger/arm64_debugger_storage.rst

11
docs/source/architectures/arm64/system_configuration.rst Normal file
View File

@ -0,0 +1,11 @@
********************
System Configuration
********************
Configuration for the processor can be set in the System Control Register for different exception levels. These registers are:
* SCTLR_EL3
* SCTLR_EL2
* SCTLR_EL1
More information about the configuration settings can be found in the `ARM documentation <https://developer.arm.com/documentation/ddi0601/2020-12/AArch64-Registers/SCTLR-EL3--System-Control-Register--EL3->`_

95
docs/source/architectures/arm_thumb/debugger/armT_debugger_storage.rst Normal file
View File

@ -0,0 +1,95 @@
***************************************
Debugger Storage Overview on ARM(Thumb)
***************************************
Overview of the storage setup on ARM Thumb for the debugger.
To interact with this storage dump you can either dump the storage location and parse the entries or use the *utils/debugger/debugger_archs/armT_processor_state.py* processor state, which is also passed as an argument in **GA_arm_thumb_debugger**.
.. note:: All addresses below asume ``STORAGE_LOCATION`` + **Address**
+---------+-----------------+--------------------------------------------------------------------------------+
| Address | Function | Comment |
+=========+=================+================================================================================+
| 0x0 | R0 | Stores Register R0 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x4 | R1 | Stores Register R1 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x8 | R2 | Stores Register R2 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0xc | R3 | Stores Register R3 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x10 | R4 | Stores Register R4 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x14 | R5 | Stores Register R5 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x18 | R6 | Stores Register R6 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x1c | R7 | Stores Register R7 |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x20 | R8 | Stores Register R8 (Indirect Function Call Target ``IFC``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x24 | R9 | Stores Register R9 (Platform Register ``P``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x28 | R10 | Stores Register R10 (Thread Pointer ``TP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x2c | R11 | Stores Register R11 (Frame Pointer ``FP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x30 | R12 | Stores Register R12 (Intra-Procedure-call-scratched-Register ``IP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x34 | R13 | Stores Register R13 (Stack Pointer ``SP``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x38 | R14 | Stores Register R14 (Link Register ``LR``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x3c | R15 | Stores Register R15 (Program Counter ``PC``) |
+---------+-----------------+--------------------------------------------------------------------------------+
| | | |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7d8 | DBG_MMU_DISABLE | **DISABLED** ``DEBUGGER`` Disable the MMU on entry and enable the MMU on leave |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7ec | DBG_JUMP_TO | ``DEBUGGER`` Address to jump to instead of the debugger |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7f0 | DBG_CONT_EXEC | ``DEBUGGER`` Do not jump in debugger but into |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7f4 | TEMP X0 | ``DEBUGGER`` Temporary storage for X0 value |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7f8 | Store X0 | ``DEBUGGER`` Stores exception id for the ``SMC`` call |
+---------+-----------------+--------------------------------------------------------------------------------+
| 0x7fc | JUMP_ADDR | ``DEBUGGER`` Memory location that instructs the debugger where to jump to |
+---------+-----------------+--------------------------------------------------------------------------------+
.. note:: This memory segment is still being updated to add registers
When ``DBG_CONT_EXEC`` is set to **0x77** the debugger will not enter the debugger_main address, but instead restore the original processor state and jump into ``DBG_JUMP_TO``.
This allows the debugger to be run without user interaction.
.. note::
By default `register r12 <https://developer.arm.com/documentation/dui0056/d/using-the-procedure-call-standard/register-roles-and-names/register-roles>`_ is corrupted for debugger usage(usually the high registers are not used in thumb mode)
Low/high registers
------------------
ARM in thumb mode has low and high registers. The low registers are R0-R7 and the high registers are R8-R15.
The high registers can not be directly accessed in thumb mode. The ``LDR`` and ``STR`` can not be used for accessing the high registers.
The ``MOV`` register however can be used to access these registers, which is enough for the debugger to use these registers.
.. code-block:: assembly
:caption: Accessing high registers in thumb mode and branch to it.
ldr r2, =addr_debugger_main
mov r12, r2
bx r12
addr_debugger_main: .word 0x100000
Instructions
============
Some notes on instructions in ``ARM Thumb``.
Branch Exchange
---------------
The ``BX`` instruction is used to branch to a new address and exchange the instruction set if required(ARM/Thumb).
The ``BX`` instruction does **not** set the LR.

6
docs/source/architectures/arm_thumb/index.rst Normal file
View File

@ -0,0 +1,6 @@
==============
ARM Thumb Mode
==============
Documentation for the ARM architecture in ``Thumb`` Mode.
.. include:: debugger/armT_debugger_storage.rst

32
docs/source/conf.py Normal file
View File

@ -0,0 +1,32 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'gupje'
copyright = '2024, Eljakim'
author = 'Eljakim'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [ 'myst_parser',
'sphinx_wagtail_theme',
'sphinx.ext.todo',
'sphinxcontrib.confluencebuilder',
"sphinxcontrib.drawio",
]
templates_path = ['_templates']
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_wagtail_theme'
html_static_path = ['_static']

32
docs/source/getting_started.rst Normal file
View File

@ -0,0 +1,32 @@
===============
Getting Started
===============
Clone gupje somewhere on your system:
.. code-block:: bash
git clone https://git.herreweb.nl/EljakimHerrewijnen/Gupje
Cross compiler
--------------
You will also need a cross compiler for the target you are going to debug.
For this we use the ``Android NDK``. Download one from the `official website <https://developer.android.com/ndk>`_ and extract it somewhere on your system.
.. code-block:: bash
wget https://dl.google.com/android/repository/android-ndk-r21e-linux-x86_64.zip
unzip android-ndk-r21e-linux-x86_64.zip
Now set the ``ANDROID_NDK_ROOT`` environment variable:
.. code-block:: bash
export ANDROID_NDK_ROOT=/path/to/android-ndk-r21e
Target Setup
------------
Gupje is compiled against a specific target. This means that you need to download a target or build one.
The Raspberry pi 4 is a good example target to start with. Please see the `Raspberry Pi 4 target <targets/rpi4.html>`_ for more information.

1
docs/source/images/debugger_flow.drawio.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

1
docs/source/images/gupje_overview.drawio.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

32
docs/source/index.rst Normal file
View File

@ -0,0 +1,32 @@
.. gupje documentation master file, created by
sphinx-quickstart on Thu Mar 28 15:26:50 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Gupje Architecture based debugger
=================================
This is the documentation for the ``Gupje`` debugger.
.. toctree::
:maxdepth: 3
:caption: Setup:
overview.rst
getting_started.rst
.. toctree::
:maxdepth: 2
:caption: Example Targets:
targets/rpi4.rst
targets/nvidia_shield.rst
targets/samsung_s7.rst
.. toctree::
:maxdepth: 2
:caption: Architectures:
architectures/arm64/index.rst
architectures/arm/index.rst
architectures/arm_thumb/index.rst

100
docs/source/overview.rst Normal file
View File

@ -0,0 +1,100 @@
==============
Gupje overview
==============
Gupje is a stub debugger that is designed to be minimal and requires 3 pages(0x1000) of data to be loaded on a target system.
A high level overview of how the memory mapping for this works is shown below.
.. figure:: images/gupje_overview.drawio.svg
.. note::
In the future the debugger will probably grow to 4 pages, to include an extra page for the debugger to use in custom functionality.
Inner workings
--------------
When the debugger is entered it will save the state of the processor into it's storage page. This is done in assembly and is architecture dependent.
When a new architecture is added the first thing that needs to be done is to implement these functionalities.
.. figure:: images/debugger_flow.drawio.svg
The debugger will then wait for commands from the host. The host can send commands to the debugger to read/write memory, jump to an address, etc.
When the user is done it will send the ``REST`` command to the debugger. This will restore the state of the processor and jump to the address defined in ``DEBUGGER_JUMP``.
The debugger also uses a stack that is defined in the debugger. This is done to not taint the original stack of the processor.
API
===
The debugger has a simple API that is used to communicate with the device. The following commands are supported:
Memory Read(Peek)
-----------------
Read an address in memory to the host.
Memory Write(Poke)
------------------
Write a buffer to an address in memory.
Get debugger main(SELF)
-----------------------
Get the main entry point of the debugger. This is used to jump to only the debugger without setting up the stack and registers again.
This taints the device but is very usefull for debugging and showing where the debugger is in memory.
Concrete main(MAIN)
-------------------
Execute the ``concrete_main`` function. This function is fully user customizable and can be used to implement custom functionality.
Like executing boot stages in a Qualcomm bootROM.
Flush Cache(FLSH)
-----------------
Execute architecture specific instructions in order to flush the cache.
.. note::
Only arm64 is supported for this function. The support is there for arm and thumb but not implemented. Probably there will be a change here to support data/code cache flushes.
Jump to address(JUMP)
---------------------
Simple function that will just jump to an address without restoring the stack or registers. Usefull for testing the debugger or relocating it.
Dump special registers(SPEC)
----------------------------
Will dump the special registers to the host. This is architecture dependent and will only dump the registers that are supported. For ARM64 checks for each exception level are implemented.
Synchronize State(SYNC)
-----------------------
This function can be called from the debugger and will force write the registers from the saved state into the processor.
Sync Special(SYNS)
------------------
Will force write the special registers from the saved state into the processor. Usefull for overwriting the ``VBAR_ELN`` and others.
Not all registers are supported here and in the future this will probably be changed to be code pushed from the host to save space and support all special registers.
.. note::
This function is currently only properly implemented for ARM64.
Restore and Jump(REST)
----------------------
This function restores the state of the processor from it's internal storage and jump's to the address defined in ``DEBUGGER_JUMP``.
.. caution::
Currently there is always a register corrupted on the jump function(we need to branch to a register). I have not found a good method to mitigate this(maybe ldr pc in arm/thumb but wont work for arm64)
Restore and Return(RRET)
------------------------
Does the same as ``Restore and Jump`` but instead of jumping it returns to the address that called the debugger(LR).
Glitching
=========
A debug flag is added for adding glitching to the debugger. The command ``GLIT`` will jump to the glitch function but this is not very well implemented yet.
The goal is to add several testable glitch cases to the debugger for profiling.
Features
========
In a typical usecase the flow of the debugger would look as something like this:

3
docs/source/targets/nvidia_shield.rst Normal file
View File

@ -0,0 +1,3 @@
====================
Nvidia Shield Tablet
====================

86
docs/source/targets/rpi4.rst Normal file
View File

@ -0,0 +1,86 @@
==============
Raspberry Pi 4
==============
The Raspberry Pi 4 is a single-board computer developed by the ``Raspberry Pi Foundation``. It is freely available and requires no exploit to run code on it.
On top of that it is well supported in ``Qemu``, making this the cheapest and easiest target for gupje.
Code
----
The github code for this `is here <https://github.com/EljakimHerrewijnen/rpi4_gupje>`_.
.. hint::
The code that runs on the Raspberry Pi4 is based on `this awesome repository <https://github.com/ethanfaust/rpi4-baremetal-uart>`_.
Clone this repository *somewhere* and link the cloned folder in the ``devices/`` folder of gupje.
.. code-block:: bash
git clone --recursive https://github.com/EljakimHerrewijnen/rpi4_gupje
cd /path/to/gupje/devices
ln -s /path/to/rpi4_gupje rpi4
You can now build the target by running the following command from gupje's root directory directory:
.. code-block:: bash
cd /path/to/gupje
make -f devices/rpi4/Makefile
In ``bin/rpi4/`` you will find the ``debugger.bin`` file, which will be used by the ``qemu.py`` script.
Running Qemu
############
From ``devices/rpi4`` navigate to ``rpi4-baremetal-uart/`` folder and run make with a cross compiler.
.. code-block:: bash
cd /path/to/gupje/devices/rpi4/rpi4-baremetal-uart
ARCH=arm64 PREFIX=aarch64-linux-gnu- make
Implementation
==============
Only send and receive need to be implemented for this target. For this target UART is used.
The debugger expects send/recv to be handled by the user so we need to build some logic to know that the data has been send and that the amount of expected data has been received. The following C code implements the send/recv for UART.
.. code-block:: c
void recv_data(void *address, uint32_t size){
for(int i=0; i < size; i++){
*((char *)address + i) = uart_get();
}
}
void send(void *address, uint64_t size, uint32_t *error){
for(int i=0; i < size; i++){
uart_send(*((char *)address + i));
}
}
However, in this implementation the debugger will need to link the uart_get and uart_send functions. In order to do that we copy the functions from the elf file and add them to the symbols.txt file.
.. code-block:: bash
$ readelf -a kernel8.elf | grep uart_
25: 00000000000803a8 36 FUNC GLOBAL DEFAULT 1 uart_get
27: 0000000000080384 36 FUNC GLOBAL DEFAULT 1 uart_send
34: 0000000000080400 88 FUNC GLOBAL DEFAULT 1 uart_puts
35: 000000000008024c 312 FUNC GLOBAL DEFAULT 1 uart_init
36: 0000000000080458 84 FUNC GLOBAL DEFAULT 1 uart_hex
39: 00000000000803cc 52 FUNC GLOBAL DEFAULT 1 uart_getc
Add the symbols uart_get and uart_send to the symbols.txt file, along with the debugger regions:
.. code-block:: text
debugger_storage = 0x85000;
debugger_stack = 0x83000;
debugger_entry = 0x81000;
uart_get = 0x00000000000803a8;
uart_send = 0x0000000000080384;
See the makefile for details on how the linking is done.

5
docs/source/targets/samsung_s7.rst Normal file
View File

@ -0,0 +1,5 @@
==========
Samsung S7
==========
Exploitation done by Frederick in `his blog <https://fredericb.info/2020/06/exynos-usbdl-unsigned-code-loader-for-exynos-bootrom.html>`_.

2
simple_device.drawio.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 11 KiB