initial

documentation/.vscode/settings.json

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

documentation/Makefile

@@ -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 34341
+
+# 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)

documentation/build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 4a910bc60671c0ff2dc823bc3bdd3901
+tags: 645f666f9bcd5a90fca523b33c5a78b7

documentation/build/_sources/bootrom/s905x3.rst.txt

@@ -0,0 +1,7 @@
+==============
+BootROM S905X3
+==============
+For the binaries of the BootROM, please refer to the following link:
+https://git.herreweb.nl/EljakimHerrewijnen/Bootrom_collections
+
+Also the ghidra server will contain an Amlogic Project(when I have set it up).

documentation/build/_sources/index.rst.txt

@@ -0,0 +1,18 @@
+.. Amlogic documentation master file, created by
+   sphinx-quickstart on Sat Mar 30 12:38:51 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Herreguard R&D on Amlogic
+=========================
+Research and tools developed for hacking Amlogic based devices. 
+This project serves as one of the reference projects on how to do emulation and fuzzing.
+
+
+.. toctree:: 
+   :maxdepth: 2
+   :numbered:
+   :caption: Bootroms
+
+   s905x3/s905x3.rst
+

documentation/build/_sources/s905x3/debugger_implementation.rst.txt

@@ -0,0 +1,8 @@
+Debugger Implementation
+=======================
+
+The debugger for this processor is implemented with the following memory map:
+
+.. drawio-image:: debugger_memory_overview.drawio
+   :export-scale: 150
+

documentation/build/_sources/s905x3/emulation.rst.txt

@@ -0,0 +1,69 @@
+Emulation
+=========
+
+Figure out where the stack is set:
+
+.. figure:: find_stack_address.png
+
+The stack is set at: ``0xfffe3800``.
+
+Devices
+-------
+
+The goal is to make a fuzzer for the ``USB`` and ``I2C`` devices. 
+To get insight and help with reverse engineering an emulator is being developed.
+
+UART Device
+###########
+UART is implemented in software. When the device boots it always sends a message over UART, this can now be printed:
+
+.. code-block:: text
+
+    print(bytes(self.get_device("UART").get_rx()))
+    b'BL:511f6b:\x00\x00\x00\x00\x00\x00;FEAT:FF800228:0;POC:0;RCY:0;USB:0;'
+
+Timer Device
+############
+Timer device is also implemented. 
+
+TODO
+####
+* Implement USB device
+* Dump Efuses from reference device and use it in the emulator, along with an efuse device
+
+I2C Device
+##########
+Quickly after boot a string is read from I2C. 
+According to several sources on the internet this I2C device is in the HDMI port(TODO check this). 
+
+I2C is a serial protocol, which relies on 2 lines, SCK for clock and SDA for data. For this SoC and using the emulator we can see that GPIO25 is used for SCL and GPIO27 for SDA.
+
+For Emulating this 
+
+Explanation of I2C according to ChatGPT:
+
+.. code-block:: text
+
+    The I2C (Inter-Integrated Circuit) protocol is a popular serial communication protocol used for communication between integrated circuits (ICs) in various electronic devices. It was developed by Philips (now NXP Semiconductors) and is widely adopted due to its simplicity and versatility.
+
+    Key features of the I2C protocol include:
+
+    Master-Slave Architecture: The I2C bus typically consists of one or more master devices and multiple slave devices. The master device initiates and controls the communication, while the slave devices respond to commands and provide data or services.
+
+    Two-Wire Communication: I2C utilizes two lines for communication: a serial data line (SDA) and a serial clock line (SCL). Both lines are bidirectional, allowing data to be transmitted in both directions.
+
+    Addressing: Each slave device on the I2C bus has a unique address, allowing the master device to communicate with specific slaves. Addressing can be 7-bit or 10-bit, depending on the device and the variant of the I2C protocol.
+
+    Start and Stop Conditions: Communication on the I2C bus is initiated by the master device by asserting a start condition (a falling edge on SDA while SCL is high). The start condition indicates the beginning of a transmission. The master also sends a stop condition (a rising edge on SDA while SCL is high) to indicate the end of a transmission.
+
+    Data Transmission: Data is transferred in bytes (8 bits) between the master and slave devices. Each byte is followed by an acknowledgment (ACK) or not-acknowledgment (NACK) bit, indicating whether the receiver successfully received the data.
+
+    Clock Synchronization: The I2C protocol relies on the synchronized clock signals on the SCL line. Both the master and slave devices operate based on this clock signal.
+
+    Standard and Fast Modes: The I2C protocol supports two main modes: Standard Mode (up to 100 kbit/s) and Fast Mode (up to 400 kbit/s). Some devices also support High-Speed Mode (up to 3.4 Mbit/s) and Ultra-Fast Mode (up to 5 Mbit/s).
+
+    Multi-Master Support: I2C supports multi-master communication, allowing multiple master devices to coexist on the same bus. Collision detection and arbitration mechanisms are employed to prevent conflicts and ensure proper communication.
+
+    The I2C protocol is commonly used for various purposes, including connecting sensors, memory devices, displays, and other peripheral devices to microcontrollers, embedded systems, and other electronic devices. It provides a simple and efficient means of serial communication with minimal wiring requirements.
+
+    It's important to note that different devices and implementations may have specific variations or additional features built on top of the basic I2C protocol. Therefore, it's always recommended to refer to the device datasheet or the specific implementation documentation for detailed information on the usage and configuration of I2C in a particular system.

documentation/build/_static/basic.css

@@ -0,0 +1,903 @@
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+    clear: both;
+}
+
+div.section::after {
+    display: block;
+    content: '';
+    clear: left;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+    width: 100%;
+    font-size: 90%;
+}
+
+div.related h3 {
+    display: none;
+}
+
+div.related ul {
+    margin: 0;
+    padding: 0 0 0 10px;
+    list-style: none;
+}
+
+div.related li {
+    display: inline;
+}
+
+div.related li.right {
+    float: right;
+    margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+    padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+    float: left;
+    width: 230px;
+    margin-left: -100%;
+    font-size: 90%;
+    word-wrap: break-word;
+    overflow-wrap : break-word;
+}
+
+div.sphinxsidebar ul {
+    list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+    margin-left: 20px;
+    list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+    margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox form.search {
+    overflow: hidden;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+    float: left;
+    width: 80%;
+    padding: 0.25em;
+    box-sizing: border-box;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+    float: left;
+    width: 20%;
+    border-left: none;
+    padding: 0.25em;
+    box-sizing: border-box;
+}
+
+
+img {
+    border: 0;
+    max-width: 100%;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li p.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+    width: 100%;
+}
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable ul {
+    margin-top: 0;
+    margin-bottom: 0;
+    list-style-type: none;
+}
+
+table.indextable > tbody > tr > td > ul {
+    padding-left: 0em;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+
+div.modindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+/* -- domain module index --------------------------------------------------- */
+
+table.modindextable td {
+    padding: 2px;
+    border-collapse: collapse;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+div.body {
+    min-width: 360px;
+    max-width: 800px;
+}
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+    -moz-hyphens: auto;
+    -ms-hyphens: auto;
+    -webkit-hyphens: auto;
+    hyphens: auto;
+}
+
+a.headerlink {
+    visibility: hidden;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink,
+caption:hover > a.headerlink,
+p.caption:hover > a.headerlink,
+div.code-block-caption:hover > a.headerlink {
+    visibility: visible;
+}
+
+div.body p.caption {
+    text-align: inherit;
+}
+
+div.body td {
+    text-align: left;
+}
+
+.first {
+    margin-top: 0 !important;
+}
+
+p.rubric {
+    margin-top: 30px;
+    font-weight: bold;
+}
+
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+img.align-default, figure.align-default, .figure.align-default {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    text-align: center;
+}
+
+.align-default {
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar,
+aside.sidebar {
+    margin: 0 0 0.5em 1em;
+    border: 1px solid #ddb;
+    padding: 7px;
+    background-color: #ffe;
+    width: 40%;
+    float: right;
+    clear: right;
+    overflow-x: auto;
+}
+
+p.sidebar-title {
+    font-weight: bold;
+}
+
+nav.contents,
+aside.topic,
+div.admonition, div.topic, blockquote {
+    clear: left;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+nav.contents,
+aside.topic,
+div.topic {
+    border: 1px solid #ccc;
+    padding: 7px;
+    margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+}
+
+div.admonition dt {
+    font-weight: bold;
+}
+
+p.admonition-title {
+    margin: 0px 10px 5px 0px;
+    font-weight: bold;
+}
+
+div.body p.centered {
+    text-align: center;
+    margin-top: 25px;
+}
+
+/* -- content of sidebars/topics/admonitions -------------------------------- */
+
+div.sidebar > :last-child,
+aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
+div.topic > :last-child,
+div.admonition > :last-child {
+    margin-bottom: 0;
+}
+
+div.sidebar::after,
+aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
+div.topic::after,
+div.admonition::after,
+blockquote::after {
+    display: block;
+    content: '';
+    clear: both;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    border: 0;
+    border-collapse: collapse;
+}
+
+table.align-center {
+    margin-left: auto;
+    margin-right: auto;
+}
+
+table.align-default {
+    margin-left: auto;
+    margin-right: auto;
+}
+
+table caption span.caption-number {
+    font-style: italic;
+}
+
+table caption span.caption-text {
+}
+
+table.docutils td, table.docutils th {
+    padding: 1px 8px 1px 5px;
+    border-top: 0;
+    border-left: 0;
+    border-right: 0;
+    border-bottom: 1px solid #aaa;
+}
+
+th {
+    text-align: left;
+    padding-right: 5px;
+}
+
+table.citation {
+    border-left: solid 1px gray;
+    margin-left: 1px;
+}
+
+table.citation td {
+    border-bottom: none;
+}
+
+th > :first-child,
+td > :first-child {
+    margin-top: 0px;
+}
+
+th > :last-child,
+td > :last-child {
+    margin-bottom: 0px;
+}
+
+/* -- figures --------------------------------------------------------------- */
+
+div.figure, figure {
+    margin: 0.5em;
+    padding: 0.5em;
+}
+
+div.figure p.caption, figcaption {
+    padding: 0.3em;
+}
+
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
+    font-style: italic;
+}
+
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
+}
+
+/* -- field list styles ----------------------------------------------------- */
+
+table.field-list td, table.field-list th {
+    border: 0 !important;
+}
+
+.field-list ul {
+    margin: 0;
+    padding-left: 1em;
+}
+
+.field-list p {
+    margin: 0;
+}
+
+.field-name {
+    -moz-hyphens: manual;
+    -ms-hyphens: manual;
+    -webkit-hyphens: manual;
+    hyphens: manual;
+}
+
+/* -- hlist styles ---------------------------------------------------------- */
+
+table.hlist {
+    margin: 1em 0;
+}
+
+table.hlist td {
+    vertical-align: top;
+}
+
+/* -- object description styles --------------------------------------------- */
+
+.sig {
+	font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+.sig-name {
+	font-size: 1.1em;
+}
+
+code.descname {
+    font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+    background-color: transparent;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.sig-paren {
+    font-size: larger;
+}
+
+.sig-param.n {
+	font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+	font-family: unset;
+}
+
+.sig.c   .k, .sig.c   .kt,
+.sig.cpp .k, .sig.cpp .kt {
+	color: #0033B3;
+}
+
+.sig.c   .m,
+.sig.cpp .m {
+	color: #1750EB;
+}
+
+.sig.c   .s, .sig.c   .sc,
+.sig.cpp .s, .sig.cpp .sc {
+	color: #067D17;
+}
+
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+    list-style: decimal;
+}
+
+ol.loweralpha {
+    list-style: lower-alpha;
+}
+
+ol.upperalpha {
+    list-style: upper-alpha;
+}
+
+ol.lowerroman {
+    list-style: lower-roman;
+}
+
+ol.upperroman {
+    list-style: upper-roman;
+}
+
+:not(li) > ol > li:first-child > :first-child,
+:not(li) > ul > li:first-child > :first-child {
+    margin-top: 0px;
+}
+
+:not(li) > ol > li:last-child > :last-child,
+:not(li) > ul > li:last-child > :last-child {
+    margin-bottom: 0px;
+}
+
+ol.simple ol p,
+ol.simple ul p,
+ul.simple ol p,
+ul.simple ul p {
+    margin-top: 0;
+}
+
+ol.simple > li:not(:first-child) > p,
+ul.simple > li:not(:first-child) > p {
+    margin-top: 0;
+}
+
+ol.simple p,
+ul.simple p {
+    margin-bottom: 0;
+}
+
+aside.footnote > span,
+div.citation > span {
+    float: left;
+}
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5em;
+}
+aside.footnote > p {
+  margin-left: 2em;
+}
+div.citation > p {
+  margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
+    margin-bottom: 0em;
+}
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
+    content: "";
+    clear: both;
+}
+
+dl.field-list {
+    display: grid;
+    grid-template-columns: fit-content(30%) auto;
+}
+
+dl.field-list > dt {
+    font-weight: bold;
+    word-break: break-word;
+    padding-left: 0.5em;
+    padding-right: 5px;
+}
+
+dl.field-list > dd {
+    padding-left: 0.5em;
+    margin-top: 0em;
+    margin-left: 0em;
+    margin-bottom: 0em;
+}
+
+dl {
+    margin-bottom: 15px;
+}
+
+dd > :first-child {
+    margin-top: 0px;
+}
+
+dd ul, dd table {
+    margin-bottom: 10px;
+}
+
+dd {
+    margin-top: 3px;
+    margin-bottom: 10px;
+    margin-left: 30px;
+}
+
+dl > dd:last-child,
+dl > dd:last-child > :last-child {
+    margin-bottom: 0;
+}
+
+dt:target, span.highlighted {
+    background-color: #fbe54e;
+}
+
+rect.highlighted {
+    fill: #fbe54e;
+}
+
+dl.glossary dt {
+    font-weight: bold;
+    font-size: 1.1em;
+}
+
+.versionmodified {
+    font-style: italic;
+}
+
+.system-message {
+    background-color: #fda;
+    padding: 5px;
+    border: 3px solid red;
+}
+
+.footnote:target  {
+    background-color: #ffa;
+}
+
+.line-block {
+    display: block;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.line-block .line-block {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+    font-family: sans-serif;
+}
+
+.accelerator {
+    text-decoration: underline;
+}
+
+.classifier {
+    font-style: oblique;
+}
+
+.classifier:before {
+    font-style: normal;
+    margin: 0 0.5em;
+    content: ":";
+    display: inline-block;
+}
+
+abbr, acronym {
+    border-bottom: dotted 1px;
+    cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+    overflow: auto;
+    overflow-y: hidden;  /* fixes display issues on Chrome browsers */
+}
+
+pre, div[class*="highlight-"] {
+    clear: both;
+}
+
+span.pre {
+    -moz-hyphens: none;
+    -ms-hyphens: none;
+    -webkit-hyphens: none;
+    hyphens: none;
+    white-space: nowrap;
+}
+
+div[class*="highlight-"] {
+    margin: 1em 0;
+}
+
+td.linenos pre {
+    border: 0;
+    background-color: transparent;
+    color: #aaa;
+}
+
+table.highlighttable {
+    display: block;
+}
+
+table.highlighttable tbody {
+    display: block;
+}
+
+table.highlighttable tr {
+    display: flex;
+}
+
+table.highlighttable td {
+    margin: 0;
+    padding: 0;
+}
+
+table.highlighttable td.linenos {
+    padding-right: 0.5em;
+}
+
+table.highlighttable td.code {
+    flex: 1;
+    overflow: hidden;
+}
+
+.highlight .hll {
+    display: block;
+}
+
+div.highlight pre,
+table.highlighttable pre {
+    margin: 0;
+}
+
+div.code-block-caption + div {
+    margin-top: 0;
+}
+
+div.code-block-caption {
+    margin-top: 1em;
+    padding: 2px 5px;
+    font-size: small;
+}
+
+div.code-block-caption code {
+    background-color: transparent;
+}
+
+table.highlighttable td.linenos,
+span.linenos,
+div.highlight span.gp {  /* gp: Generic.Prompt */
+  user-select: none;
+  -webkit-user-select: text; /* Safari fallback only */
+  -webkit-user-select: none; /* Chrome/Safari */
+  -moz-user-select: none; /* Firefox */
+  -ms-user-select: none; /* IE10+ */
+}
+
+div.code-block-caption span.caption-number {
+    padding: 0.1em 0.3em;
+    font-style: italic;
+}
+
+div.code-block-caption span.caption-text {
+}
+
+div.literal-block-wrapper {
+    margin: 1em 0;
+}
+
+code.xref, a code {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+    background-color: transparent;
+}
+
+.viewcode-link {
+    float: right;
+}
+
+.viewcode-back {
+    float: right;
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    margin: -1px -10px;
+    padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+    vertical-align: middle;
+}
+
+div.body div.math p {
+    text-align: center;
+}
+
+span.eqno {
+    float: right;
+}
+
+span.eqno a.headerlink {
+    position: absolute;
+    z-index: 1;
+}
+
+div.math:hover a.headerlink {
+    visibility: visible;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+    div.document,
+    div.documentwrapper,
+    div.bodywrapper {
+        margin: 0 !important;
+        width: 100%;
+    }
+
+    div.sphinxsidebar,
+    div.related,
+    div.footer,
+    #top-link {
+        display: none;
+    }
+}

documentation/build/_static/css/badge_only.css

@@ -0,0 +1 @@
+.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}

documentation/build/_static/doctools.js

@@ -0,0 +1,156 @@
+/*
+ * doctools.js
+ * ~~~~~~~~~~~
+ *
+ * Base JavaScript utilities for all Sphinx HTML documentation.
+ *
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+"use strict";
+
+const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
+  "TEXTAREA",
+  "INPUT",
+  "SELECT",
+  "BUTTON",
+]);
+
+const _ready = (callback) => {
+  if (document.readyState !== "loading") {
+    callback();
+  } else {
+    document.addEventListener("DOMContentLoaded", callback);
+  }
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+const Documentation = {
+  init: () => {
+    Documentation.initDomainIndexTable();
+    Documentation.initOnKeyListeners();
+  },
+
+  /**
+   * i18n support
+   */
+  TRANSLATIONS: {},
+  PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
+  LOCALE: "unknown",
+
+  // gettext and ngettext don't access this so that the functions
+  // can safely bound to a different name (_ = Documentation.gettext)
+  gettext: (string) => {
+    const translated = Documentation.TRANSLATIONS[string];
+    switch (typeof translated) {
+      case "undefined":
+        return string; // no translation
+      case "string":
+        return translated; // translation exists
+      default:
+        return translated[0]; // (singular, plural) translation tuple exists
+    }
+  },
+
+  ngettext: (singular, plural, n) => {
+    const translated = Documentation.TRANSLATIONS[singular];
+    if (typeof translated !== "undefined")
+      return translated[Documentation.PLURAL_EXPR(n)];
+    return n === 1 ? singular : plural;
+  },
+
+  addTranslations: (catalog) => {
+    Object.assign(Documentation.TRANSLATIONS, catalog.messages);
+    Documentation.PLURAL_EXPR = new Function(
+      "n",
+      `return (${catalog.plural_expr})`
+    );
+    Documentation.LOCALE = catalog.locale;
+  },
+
+  /**
+   * helper function to focus on search bar
+   */
+  focusSearchBar: () => {
+    document.querySelectorAll("input[name=q]")[0]?.focus();
+  },
+
+  /**
+   * Initialise the domain index toggle buttons
+   */
+  initDomainIndexTable: () => {
+    const toggler = (el) => {
+      const idNumber = el.id.substr(7);
+      const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
+      if (el.src.substr(-9) === "minus.png") {
+        el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
+        toggledRows.forEach((el) => (el.style.display = "none"));
+      } else {
+        el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
+        toggledRows.forEach((el) => (el.style.display = ""));
+      }
+    };
+
+    const togglerElements = document.querySelectorAll("img.toggler");
+    togglerElements.forEach((el) =>
+      el.addEventListener("click", (event) => toggler(event.currentTarget))
+    );
+    togglerElements.forEach((el) => (el.style.display = ""));
+    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
+  },
+
+  initOnKeyListeners: () => {
+    // only install a listener if it is really needed
+    if (
+      !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
+      !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
+    )
+      return;
+
+    document.addEventListener("keydown", (event) => {
+      // bail for input elements
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      // bail with special keys
+      if (event.altKey || event.ctrlKey || event.metaKey) return;
+
+      if (!event.shiftKey) {
+        switch (event.key) {
+          case "ArrowLeft":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+            const prevLink = document.querySelector('link[rel="prev"]');
+            if (prevLink && prevLink.href) {
+              window.location.href = prevLink.href;
+              event.preventDefault();
+            }
+            break;
+          case "ArrowRight":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+            const nextLink = document.querySelector('link[rel="next"]');
+            if (nextLink && nextLink.href) {
+              window.location.href = nextLink.href;
+              event.preventDefault();
+            }
+            break;
+        }
+      }
+
+      // some keyboard layouts may need Shift to get /
+      switch (event.key) {
+        case "/":
+          if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
+          Documentation.focusSearchBar();
+          event.preventDefault();
+      }
+    });
+  },
+};
+
+// quick alias for translations
+const _ = Documentation.gettext;
+
+_ready(Documentation.init);

documentation/build/_static/documentation_options.js

@@ -0,0 +1,14 @@
+var DOCUMENTATION_OPTIONS = {
+    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
+    VERSION: '',
+    LANGUAGE: 'en',
+    COLLAPSE_INDEX: false,
+    BUILDER: 'html',
+    FILE_SUFFIX: '.html',
+    LINK_SUFFIX: '.html',
+    HAS_SOURCE: true,
+    SOURCELINK_SUFFIX: '.txt',
+    NAVIGATION_WITH_KEYS: false,
+    SHOW_SEARCH_SUMMARY: true,
+    ENABLE_SEARCH_SHORTCUTS: true,
+};

documentation/build/_static/drawio.css

@@ -0,0 +1,8 @@
+img.drawio {
+    border: 0;
+    max-width: 100%;
+}
+
+object.drawio {
+    max-width: 100%;
+}

documentation/build/_static/js/badge_only.js

@@ -0,0 +1 @@
+!function(e){var t={};function r(n){if(t[n])return t[n].exports;var o=t[n]={i:n,l:!1,exports:{}};return e[n].call(o.exports,o,o.exports,r),o.l=!0,o.exports}r.m=e,r.c=t,r.d=function(e,t,n){r.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:n})},r.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return r.d(t,"a",t),t},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r.p="",r(r.s=4)}({4:function(e,t,r){}});

documentation/build/_static/js/html5shiv-printshiv.min.js

@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3-pre | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x<style>"+b+"</style>",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=y.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=y.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),y.elements=c+" "+a,j(b)}function f(a){var b=x[a[v]];return b||(b={},w++,a[v]=w,x[w]=b),b}function g(a,c,d){if(c||(c=b),q)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():u.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||t.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),q)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return y.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(y,b.frag)}function j(a){a||(a=b);var d=f(a);return!y.shivCSS||p||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),q||i(a,d),a}function k(a){for(var b,c=a.getElementsByTagName("*"),e=c.length,f=RegExp("^(?:"+d().join("|")+")$","i"),g=[];e--;)b=c[e],f.test(b.nodeName)&&g.push(b.applyElement(l(b)));return g}function l(a){for(var b,c=a.attributes,d=c.length,e=a.ownerDocument.createElement(A+":"+a.nodeName);d--;)b=c[d],b.specified&&e.setAttribute(b.nodeName,b.nodeValue);return e.style.cssText=a.style.cssText,e}function m(a){for(var b,c=a.split("{"),e=c.length,f=RegExp("(^|[\\s,>+~])("+d().join("|")+")(?=[[\\s,>+~#.:]|$)","gi"),g="$1"+A+"\\:$2";e--;)b=c[e]=c[e].split("}"),b[b.length-1]=b[b.length-1].replace(f,g),c[e]=b.join("}");return c.join("{")}function n(a){for(var b=a.length;b--;)a[b].removeNode()}function o(a){function b(){clearTimeout(g._removeSheetTimer),d&&d.removeNode(!0),d=null}var d,e,g=f(a),h=a.namespaces,i=a.parentWindow;return!B||a.printShived?a:("undefined"==typeof h[A]&&h.add(A),i.attachEvent("onbeforeprint",function(){b();for(var f,g,h,i=a.styleSheets,j=[],l=i.length,n=Array(l);l--;)n[l]=i[l];for(;h=n.pop();)if(!h.disabled&&z.test(h.media)){try{f=h.imports,g=f.length}catch(o){g=0}for(l=0;g>l;l++)n.push(f[l]);try{j.push(h.cssText)}catch(o){}}j=m(j.reverse().join("")),e=k(a),d=c(a,j)}),i.attachEvent("onafterprint",function(){n(e),clearTimeout(g._removeSheetTimer),g._removeSheetTimer=setTimeout(b,500)}),a.printShived=!0,a)}var p,q,r="3.7.3",s=a.html5||{},t=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,u=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,v="_html5shiv",w=0,x={};!function(){try{var a=b.createElement("a");a.innerHTML="<xyz></xyz>",p="hidden"in a,q=1==a.childNodes.length||function(){b.createElement("a");var a=b.createDocumentFragment();return"undefined"==typeof a.cloneNode||"undefined"==typeof a.createDocumentFragment||"undefined"==typeof a.createElement}()}catch(c){p=!0,q=!0}}();var y={elements:s.elements||"abbr article aside audio bdi canvas data datalist details dialog figcaption figure footer header hgroup main mark meter nav output picture progress section summary template time video",version:r,shivCSS:s.shivCSS!==!1,supportsUnknownElements:q,shivMethods:s.shivMethods!==!1,type:"default",shivDocument:j,createElement:g,createDocumentFragment:h,addElements:e};a.html5=y,j(b);var z=/^$|\b(?:all|print)\b/,A="html5shiv",B=!q&&function(){var c=b.documentElement;return!("undefined"==typeof b.namespaces||"undefined"==typeof b.parentWindow||"undefined"==typeof c.applyElement||"undefined"==typeof c.removeNode||"undefined"==typeof a.attachEvent)}();y.type+=" print",y.shivPrint=o,o(b),"object"==typeof module&&module.exports&&(module.exports=y)}("undefined"!=typeof window?window:this,document);

documentation/build/_static/js/html5shiv.min.js

@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x<style>"+b+"</style>",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3-pre",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="<xyz></xyz>",k="hidden"in a,l=1==a.childNodes.length||function(){b.createElement("a");var a=b.createDocumentFragment();return"undefined"==typeof a.cloneNode||"undefined"==typeof a.createDocumentFragment||"undefined"==typeof a.createElement}()}catch(c){k=!0,l=!0}}();var t={elements:n.elements||"abbr article aside audio bdi canvas data datalist details dialog figcaption figure footer header hgroup main mark meter nav output picture progress section summary template time video",version:m,shivCSS:n.shivCSS!==!1,supportsUnknownElements:l,shivMethods:n.shivMethods!==!1,type:"default",shivDocument:j,createElement:g,createDocumentFragment:h,addElements:e};a.html5=t,j(b),"object"==typeof module&&module.exports&&(module.exports=t)}("undefined"!=typeof window?window:this,document);

documentation/build/_static/language_data.js

@@ -0,0 +1,199 @@
+/*
+ * language_data.js
+ * ~~~~~~~~~~~~~~~~
+ *
+ * This script contains the language-specific data used by searchtools.js,
+ * namely the list of stopwords, stemmer, scorer and splitter.
+ *
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
+
+
+/* Non-minified version is copied as a separate JS file, is available */
+
+/**
+ * Porter Stemmer
+ */
+var Stemmer = function() {
+
+  var step2list = {
+    ational: 'ate',
+    tional: 'tion',
+    enci: 'ence',
+    anci: 'ance',
+    izer: 'ize',
+    bli: 'ble',
+    alli: 'al',
+    entli: 'ent',
+    eli: 'e',
+    ousli: 'ous',
+    ization: 'ize',
+    ation: 'ate',
+    ator: 'ate',
+    alism: 'al',
+    iveness: 'ive',
+    fulness: 'ful',
+    ousness: 'ous',
+    aliti: 'al',
+    iviti: 'ive',
+    biliti: 'ble',
+    logi: 'log'
+  };
+
+  var step3list = {
+    icate: 'ic',
+    ative: '',
+    alize: 'al',
+    iciti: 'ic',
+    ical: 'ic',
+    ful: '',
+    ness: ''
+  };
+
+  var c = "[^aeiou]";          // consonant
+  var v = "[aeiouy]";          // vowel
+  var C = c + "[^aeiouy]*";    // consonant sequence
+  var V = v + "[aeiou]*";      // vowel sequence
+
+  var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
+  var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
+  var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
+  var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
+
+  this.stemWord = function (w) {
+    var stem;
+    var suffix;
+    var firstch;
+    var origword = w;
+
+    if (w.length < 3)
+      return w;
+
+    var re;
+    var re2;
+    var re3;
+    var re4;
+
+    firstch = w.substr(0,1);
+    if (firstch == "y")
+      w = firstch.toUpperCase() + w.substr(1);
+
+    // Step 1a
+    re = /^(.+?)(ss|i)es$/;
+    re2 = /^(.+?)([^s])s$/;
+
+    if (re.test(w))
+      w = w.replace(re,"$1$2");
+    else if (re2.test(w))
+      w = w.replace(re2,"$1$2");
+
+    // Step 1b
+    re = /^(.+?)eed$/;
+    re2 = /^(.+?)(ed|ing)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      re = new RegExp(mgr0);
+      if (re.test(fp[1])) {
+        re = /.$/;
+        w = w.replace(re,"");
+      }
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1];
+      re2 = new RegExp(s_v);
+      if (re2.test(stem)) {
+        w = stem;
+        re2 = /(at|bl|iz)$/;
+        re3 = new RegExp("([^aeiouylsz])\\1$");
+        re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+        if (re2.test(w))
+          w = w + "e";
+        else if (re3.test(w)) {
+          re = /.$/;
+          w = w.replace(re,"");
+        }
+        else if (re4.test(w))
+          w = w + "e";
+      }
+    }
+
+    // Step 1c
+    re = /^(.+?)y$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(s_v);
+      if (re.test(stem))
+        w = stem + "i";
+    }
+
+    // Step 2
+    re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step2list[suffix];
+    }
+
+    // Step 3
+    re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step3list[suffix];
+    }
+
+    // Step 4
+    re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+    re2 = /^(.+?)(s|t)(ion)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      if (re.test(stem))
+        w = stem;
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1] + fp[2];
+      re2 = new RegExp(mgr1);
+      if (re2.test(stem))
+        w = stem;
+    }
+
+    // Step 5
+    re = /^(.+?)e$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      re2 = new RegExp(meq1);
+      re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+      if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
+        w = stem;
+    }
+    re = /ll$/;
+    re2 = new RegExp(mgr1);
+    if (re.test(w) && re2.test(w)) {
+      re = /.$/;
+      w = w.replace(re,"");
+    }
+
+    // and turn initial Y back to y
+    if (firstch == "y")
+      w = firstch.toLowerCase() + w.substr(1);
+    return w;
+  }
+}
+

documentation/build/_static/pygments.css

@@ -0,0 +1,74 @@
+pre { line-height: 125%; }
+td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
+span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
+td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+.highlight .hll { background-color: #ffffcc }
+.highlight { background: #f8f8f8; }
+.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #008000; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */
+.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #9C6500 } /* Comment.Preproc */
+.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */
+.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #E40000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #008400 } /* Generic.Inserted */
+.highlight .go { color: #717171 } /* Generic.Output */
+.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0044DD } /* Generic.Traceback */
+.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #008000 } /* Keyword.Pseudo */
+.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #B00040 } /* Keyword.Type */
+.highlight .m { color: #666666 } /* Literal.Number */
+.highlight .s { color: #BA2121 } /* Literal.String */
+.highlight .na { color: #687822 } /* Name.Attribute */
+.highlight .nb { color: #008000 } /* Name.Builtin */
+.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
+.highlight .no { color: #880000 } /* Name.Constant */
+.highlight .nd { color: #AA22FF } /* Name.Decorator */
+.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #0000FF } /* Name.Function */
+.highlight .nl { color: #767600 } /* Name.Label */
+.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #19177C } /* Name.Variable */
+.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mb { color: #666666 } /* Literal.Number.Bin */
+.highlight .mf { color: #666666 } /* Literal.Number.Float */
+.highlight .mh { color: #666666 } /* Literal.Number.Hex */
+.highlight .mi { color: #666666 } /* Literal.Number.Integer */
+.highlight .mo { color: #666666 } /* Literal.Number.Oct */
+.highlight .sa { color: #BA2121 } /* Literal.String.Affix */
+.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
+.highlight .sc { color: #BA2121 } /* Literal.String.Char */
+.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
+.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
+.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */
+.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
+.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */
+.highlight .sx { color: #008000 } /* Literal.String.Other */
+.highlight .sr { color: #A45A77 } /* Literal.String.Regex */
+.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
+.highlight .ss { color: #19177C } /* Literal.String.Symbol */
+.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
+.highlight .fm { color: #0000FF } /* Name.Function.Magic */
+.highlight .vc { color: #19177C } /* Name.Variable.Class */
+.highlight .vg { color: #19177C } /* Name.Variable.Global */
+.highlight .vi { color: #19177C } /* Name.Variable.Instance */
+.highlight .vm { color: #19177C } /* Name.Variable.Magic */
+.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */

documentation/build/_static/searchtools.js

@@ -0,0 +1,566 @@
+/*
+ * searchtools.js
+ * ~~~~~~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilities for the full-text search.
+ *
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+"use strict";
+
+/**
+ * Simple result scoring code.
+ */
+if (typeof Scorer === "undefined") {
+  var Scorer = {
+    // Implement the following function to further tweak the score for each result
+    // The function takes a result array [docname, title, anchor, descr, score, filename]
+    // and returns the new score.
+    /*
+    score: result => {
+      const [docname, title, anchor, descr, score, filename] = result
+      return score
+    },
+    */
+
+    // query matches the full name of an object
+    objNameMatch: 11,
+    // or matches in the last dotted part of the object name
+    objPartialMatch: 6,
+    // Additive scores depending on the priority of the object
+    objPrio: {
+      0: 15, // used to be importantResults
+      1: 5, // used to be objectResults
+      2: -5, // used to be unimportantResults
+    },
+    //  Used when the priority is not in the mapping.
+    objPrioDefault: 0,
+
+    // query found in title
+    title: 15,
+    partialTitle: 7,
+    // query found in terms
+    term: 5,
+    partialTerm: 2,
+  };
+}
+
+const _removeChildren = (element) => {
+  while (element && element.lastChild) element.removeChild(element.lastChild);
+};
+
+/**
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
+ */
+const _escapeRegExp = (string) =>
+  string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+
+const _displayItem = (item, searchTerms) => {
+  const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
+  const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
+  const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
+  const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
+  const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
+
+  const [docName, title, anchor, descr, score, _filename] = item;
+
+  let listItem = document.createElement("li");
+  let requestUrl;
+  let linkUrl;
+  if (docBuilder === "dirhtml") {
+    // dirhtml builder
+    let dirname = docName + "/";
+    if (dirname.match(/\/index\/$/))
+      dirname = dirname.substring(0, dirname.length - 6);
+    else if (dirname === "index/") dirname = "";
+    requestUrl = docUrlRoot + dirname;
+    linkUrl = requestUrl;
+  } else {
+    // normal html builders
+    requestUrl = docUrlRoot + docName + docFileSuffix;
+    linkUrl = docName + docLinkSuffix;
+  }
+  let linkEl = listItem.appendChild(document.createElement("a"));
+  linkEl.href = linkUrl + anchor;
+  linkEl.dataset.score = score;
+  linkEl.innerHTML = title;
+  if (descr)
+    listItem.appendChild(document.createElement("span")).innerHTML =
+      " (" + descr + ")";
+  else if (showSearchSummary)
+    fetch(requestUrl)
+      .then((responseData) => responseData.text())
+      .then((data) => {
+        if (data)
+          listItem.appendChild(
+            Search.makeSearchSummary(data, searchTerms)
+          );
+      });
+  Search.output.appendChild(listItem);
+};
+const _finishSearch = (resultCount) => {
+  Search.stopPulse();
+  Search.title.innerText = _("Search Results");
+  if (!resultCount)
+    Search.status.innerText = Documentation.gettext(
+      "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
+    );
+  else
+    Search.status.innerText = _(
+      `Search finished, found ${resultCount} page(s) matching the search query.`
+    );
+};
+const _displayNextItem = (
+  results,
+  resultCount,
+  searchTerms
+) => {
+  // results left, load the summary and display it
+  // this is intended to be dynamic (don't sub resultsCount)
+  if (results.length) {
+    _displayItem(results.pop(), searchTerms);
+    setTimeout(
+      () => _displayNextItem(results, resultCount, searchTerms),
+      5
+    );
+  }
+  // search finished, update title and status message
+  else _finishSearch(resultCount);
+};
+
+/**
+ * Default splitQuery function. Can be overridden in ``sphinx.search`` with a
+ * custom function per language.
+ *
+ * The regular expression works by splitting the string on consecutive characters
+ * that are not Unicode letters, numbers, underscores, or emoji characters.
+ * This is the same as ``\W+`` in Python, preserving the surrogate pair area.
+ */
+if (typeof splitQuery === "undefined") {
+  var splitQuery = (query) => query
+      .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
+      .filter(term => term)  // remove remaining empty strings
+}
+
+/**
+ * Search Module
+ */
+const Search = {
+  _index: null,
+  _queued_query: null,
+  _pulse_status: -1,
+
+  htmlToText: (htmlString) => {
+    const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
+    htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() });
+    const docContent = htmlElement.querySelector('[role="main"]');
+    if (docContent !== undefined) return docContent.textContent;
+    console.warn(
+      "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template."
+    );
+    return "";
+  },
+
+  init: () => {
+    const query = new URLSearchParams(window.location.search).get("q");
+    document
+      .querySelectorAll('input[name="q"]')
+      .forEach((el) => (el.value = query));
+    if (query) Search.performSearch(query);
+  },
+
+  loadIndex: (url) =>
+    (document.body.appendChild(document.createElement("script")).src = url),
+
+  setIndex: (index) => {
+    Search._index = index;
+    if (Search._queued_query !== null) {
+      const query = Search._queued_query;
+      Search._queued_query = null;
+      Search.query(query);
+    }
+  },
+
+  hasIndex: () => Search._index !== null,
+
+  deferQuery: (query) => (Search._queued_query = query),
+
+  stopPulse: () => (Search._pulse_status = -1),
+
+  startPulse: () => {
+    if (Search._pulse_status >= 0) return;
+
+    const pulse = () => {
+      Search._pulse_status = (Search._pulse_status + 1) % 4;
+      Search.dots.innerText = ".".repeat(Search._pulse_status);
+      if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
+    };
+    pulse();
+  },
+
+  /**
+   * perform a search for something (or wait until index is loaded)
+   */
+  performSearch: (query) => {
+    // create the required interface elements
+    const searchText = document.createElement("h2");
+    searchText.textContent = _("Searching");
+    const searchSummary = document.createElement("p");
+    searchSummary.classList.add("search-summary");
+    searchSummary.innerText = "";
+    const searchList = document.createElement("ul");
+    searchList.classList.add("search");
+
+    const out = document.getElementById("search-results");
+    Search.title = out.appendChild(searchText);
+    Search.dots = Search.title.appendChild(document.createElement("span"));
+    Search.status = out.appendChild(searchSummary);
+    Search.output = out.appendChild(searchList);
+
+    const searchProgress = document.getElementById("search-progress");
+    // Some themes don't use the search progress node
+    if (searchProgress) {
+      searchProgress.innerText = _("Preparing search...");
+    }
+    Search.startPulse();
+
+    // index already loaded, the browser was quick!
+    if (Search.hasIndex()) Search.query(query);
+    else Search.deferQuery(query);
+  },
+
+  /**
+   * execute search (requires search index to be loaded)
+   */
+  query: (query) => {
+    const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
+    const titles = Search._index.titles;
+    const allTitles = Search._index.alltitles;
+    const indexEntries = Search._index.indexentries;
+
+    // stem the search terms and add them to the correct list
+    const stemmer = new Stemmer();
+    const searchTerms = new Set();
+    const excludedTerms = new Set();
+    const highlightTerms = new Set();
+    const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
+    splitQuery(query.trim()).forEach((queryTerm) => {
+      const queryTermLower = queryTerm.toLowerCase();
+
+      // maybe skip this "word"
+      // stopwords array is from language_data.js
+      if (
+        stopwords.indexOf(queryTermLower) !== -1 ||
+        queryTerm.match(/^\d+$/)
+      )
+        return;
+
+      // stem the word
+      let word = stemmer.stemWord(queryTermLower);
+      // select the correct list
+      if (word[0] === "-") excludedTerms.add(word.substr(1));
+      else {
+        searchTerms.add(word);
+        highlightTerms.add(queryTermLower);
+      }
+    });
+
+    if (SPHINX_HIGHLIGHT_ENABLED) {  // set in sphinx_highlight.js
+      localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
+    }
+
+    // console.debug("SEARCH: searching for:");
+    // console.info("required: ", [...searchTerms]);
+    // console.info("excluded: ", [...excludedTerms]);
+
+    // array of [docname, title, anchor, descr, score, filename]
+    let results = [];
+    _removeChildren(document.getElementById("search-progress"));
+
+    const queryLower = query.toLowerCase();
+    for (const [title, foundTitles] of Object.entries(allTitles)) {
+      if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) {
+        for (const [file, id] of foundTitles) {
+          let score = Math.round(100 * queryLower.length / title.length)
+          results.push([
+            docNames[file],
+            titles[file] !== title ? `${titles[file]} > ${title}` : title,
+            id !== null ? "#" + id : "",
+            null,
+            score,
+            filenames[file],
+          ]);
+        }
+      }
+    }
+
+    // search for explicit entries in index directives
+    for (const [entry, foundEntries] of Object.entries(indexEntries)) {
+      if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
+        for (const [file, id] of foundEntries) {
+          let score = Math.round(100 * queryLower.length / entry.length)
+          results.push([
+            docNames[file],
+            titles[file],
+            id ? "#" + id : "",
+            null,
+            score,
+            filenames[file],
+          ]);
+        }
+      }
+    }
+
+    // lookup as object
+    objectTerms.forEach((term) =>
+      results.push(...Search.performObjectSearch(term, objectTerms))
+    );
+
+    // lookup as search terms in fulltext
+    results.push(...Search.performTermsSearch(searchTerms, excludedTerms));
+
+    // let the scorer override scores with a custom scoring function
+    if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item)));
+
+    // now sort the results by score (in opposite order of appearance, since the
+    // display function below uses pop() to retrieve items) and then
+    // alphabetically
+    results.sort((a, b) => {
+      const leftScore = a[4];
+      const rightScore = b[4];
+      if (leftScore === rightScore) {
+        // same score: sort alphabetically
+        const leftTitle = a[1].toLowerCase();
+        const rightTitle = b[1].toLowerCase();
+        if (leftTitle === rightTitle) return 0;
+        return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
+      }
+      return leftScore > rightScore ? 1 : -1;
+    });
+
+    // remove duplicate search results
+    // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
+    let seen = new Set();
+    results = results.reverse().reduce((acc, result) => {
+      let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(',');
+      if (!seen.has(resultStr)) {
+        acc.push(result);
+        seen.add(resultStr);
+      }
+      return acc;
+    }, []);
+
+    results = results.reverse();
+
+    // for debugging
+    //Search.lastresults = results.slice();  // a copy
+    // console.info("search results:", Search.lastresults);
+
+    // print the results
+    _displayNextItem(results, results.length, searchTerms);
+  },
+
+  /**
+   * search for object names
+   */
+  performObjectSearch: (object, objectTerms) => {
+    const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
+    const objects = Search._index.objects;
+    const objNames = Search._index.objnames;
+    const titles = Search._index.titles;
+
+    const results = [];
+
+    const objectSearchCallback = (prefix, match) => {
+      const name = match[4]
+      const fullname = (prefix ? prefix + "." : "") + name;
+      const fullnameLower = fullname.toLowerCase();
+      if (fullnameLower.indexOf(object) < 0) return;
+
+      let score = 0;
+      const parts = fullnameLower.split(".");
+
+      // check for different match types: exact matches of full name or
+      // "last name" (i.e. last dotted part)
+      if (fullnameLower === object || parts.slice(-1)[0] === object)
+        score += Scorer.objNameMatch;
+      else if (parts.slice(-1)[0].indexOf(object) > -1)
+        score += Scorer.objPartialMatch; // matches in last name
+
+      const objName = objNames[match[1]][2];
+      const title = titles[match[0]];
+
+      // If more than one term searched for, we require other words to be
+      // found in the name/title/description
+      const otherTerms = new Set(objectTerms);
+      otherTerms.delete(object);
+      if (otherTerms.size > 0) {
+        const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
+        if (
+          [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
+        )
+          return;
+      }
+
+      let anchor = match[3];
+      if (anchor === "") anchor = fullname;
+      else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
+
+      const descr = objName + _(", in ") + title;
+
+      // add custom score for some objects according to scorer
+      if (Scorer.objPrio.hasOwnProperty(match[2]))
+        score += Scorer.objPrio[match[2]];
+      else score += Scorer.objPrioDefault;
+
+      results.push([
+        docNames[match[0]],
+        fullname,
+        "#" + anchor,
+        descr,
+        score,
+        filenames[match[0]],
+      ]);
+    };
+    Object.keys(objects).forEach((prefix) =>
+      objects[prefix].forEach((array) =>
+        objectSearchCallback(prefix, array)
+      )
+    );
+    return results;
+  },
+
+  /**
+   * search for full-text terms in the index
+   */
+  performTermsSearch: (searchTerms, excludedTerms) => {
+    // prepare search
+    const terms = Search._index.terms;
+    const titleTerms = Search._index.titleterms;
+    const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
+    const titles = Search._index.titles;
+
+    const scoreMap = new Map();
+    const fileMap = new Map();
+
+    // perform the search on the required terms
+    searchTerms.forEach((word) => {
+      const files = [];
+      const arr = [
+        { files: terms[word], score: Scorer.term },
+        { files: titleTerms[word], score: Scorer.title },
+      ];
+      // add support for partial matches
+      if (word.length > 2) {
+        const escapedWord = _escapeRegExp(word);
+        Object.keys(terms).forEach((term) => {
+          if (term.match(escapedWord) && !terms[word])
+            arr.push({ files: terms[term], score: Scorer.partialTerm });
+        });
+        Object.keys(titleTerms).forEach((term) => {
+          if (term.match(escapedWord) && !titleTerms[word])
+            arr.push({ files: titleTerms[word], score: Scorer.partialTitle });
+        });
+      }
+
+      // no match but word was a required one
+      if (arr.every((record) => record.files === undefined)) return;
+
+      // found search word in contents
+      arr.forEach((record) => {
+        if (record.files === undefined) return;
+
+        let recordFiles = record.files;
+        if (recordFiles.length === undefined) recordFiles = [recordFiles];
+        files.push(...recordFiles);
+
+        // set score for the word in each file
+        recordFiles.forEach((file) => {
+          if (!scoreMap.has(file)) scoreMap.set(file, {});
+          scoreMap.get(file)[word] = record.score;
+        });
+      });
+
+      // create the mapping
+      files.forEach((file) => {
+        if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1)
+          fileMap.get(file).push(word);
+        else fileMap.set(file, [word]);
+      });
+    });
+
+    // now check if the files don't contain excluded terms
+    const results = [];
+    for (const [file, wordList] of fileMap) {
+      // check if all requirements are matched
+
+      // as search terms with length < 3 are discarded
+      const filteredTermCount = [...searchTerms].filter(
+        (term) => term.length > 2
+      ).length;
+      if (
+        wordList.length !== searchTerms.size &&
+        wordList.length !== filteredTermCount
+      )
+        continue;
+
+      // ensure that none of the excluded terms is in the search result
+      if (
+        [...excludedTerms].some(
+          (term) =>
+            terms[term] === file ||
+            titleTerms[term] === file ||
+            (terms[term] || []).includes(file) ||
+            (titleTerms[term] || []).includes(file)
+        )
+      )
+        break;
+
+      // select one (max) score for the file.
+      const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
+      // add result to the result list
+      results.push([
+        docNames[file],
+        titles[file],
+        "",
+        null,
+        score,
+        filenames[file],
+      ]);
+    }
+    return results;
+  },
+
+  /**
+   * helper function to return a node containing the
+   * search summary for a given text. keywords is a list
+   * of stemmed words.
+   */
+  makeSearchSummary: (htmlText, keywords) => {
+    const text = Search.htmlToText(htmlText);
+    if (text === "") return null;
+
+    const textLower = text.toLowerCase();
+    const actualStartPosition = [...keywords]
+      .map((k) => textLower.indexOf(k.toLowerCase()))
+      .filter((i) => i > -1)
+      .slice(-1)[0];
+    const startWithContext = Math.max(actualStartPosition - 120, 0);
+
+    const top = startWithContext === 0 ? "" : "...";
+    const tail = startWithContext + 240 < text.length ? "..." : "";
+
+    let summary = document.createElement("p");
+    summary.classList.add("context");
+    summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
+
+    return summary;
+  },
+};
+
+_ready(Search.init);

documentation/build/_static/sphinx_highlight.js

@@ -0,0 +1,144 @@
+/* Highlighting utilities for Sphinx HTML documentation. */
+"use strict";
+
+const SPHINX_HIGHLIGHT_ENABLED = true
+
+/**
+ * highlight a given string on a node by wrapping it in
+ * span elements with the given class name.
+ */
+const _highlight = (node, addItems, text, className) => {
+  if (node.nodeType === Node.TEXT_NODE) {
+    const val = node.nodeValue;
+    const parent = node.parentNode;
+    const pos = val.toLowerCase().indexOf(text);
+    if (
+      pos >= 0 &&
+      !parent.classList.contains(className) &&
+      !parent.classList.contains("nohighlight")
+    ) {
+      let span;
+
+      const closestNode = parent.closest("body, svg, foreignObject");
+      const isInSVG = closestNode && closestNode.matches("svg");
+      if (isInSVG) {
+        span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+      } else {
+        span = document.createElement("span");
+        span.classList.add(className);
+      }
+
+      span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+      parent.insertBefore(
+        span,
+        parent.insertBefore(
+          document.createTextNode(val.substr(pos + text.length)),
+          node.nextSibling
+        )
+      );
+      node.nodeValue = val.substr(0, pos);
+
+      if (isInSVG) {
+        const rect = document.createElementNS(
+          "http://www.w3.org/2000/svg",
+          "rect"
+        );
+        const bbox = parent.getBBox();
+        rect.x.baseVal.value = bbox.x;
+        rect.y.baseVal.value = bbox.y;
+        rect.width.baseVal.value = bbox.width;
+        rect.height.baseVal.value = bbox.height;
+        rect.setAttribute("class", className);
+        addItems.push({ parent: parent, target: rect });
+      }
+    }
+  } else if (node.matches && !node.matches("button, select, textarea")) {
+    node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
+  }
+};
+const _highlightText = (thisNode, text, className) => {
+  let addItems = [];
+  _highlight(thisNode, addItems, text, className);
+  addItems.forEach((obj) =>
+    obj.parent.insertAdjacentElement("beforebegin", obj.target)
+  );
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+const SphinxHighlight = {
+
+  /**
+   * highlight the search words provided in localstorage in the text
+   */
+  highlightSearchWords: () => {
+    if (!SPHINX_HIGHLIGHT_ENABLED) return;  // bail if no highlight
+
+    // get and clear terms from localstorage
+    const url = new URL(window.location);
+    const highlight =
+        localStorage.getItem("sphinx_highlight_terms")
+        || url.searchParams.get("highlight")
+        || "";
+    localStorage.removeItem("sphinx_highlight_terms")
+    url.searchParams.delete("highlight");
+    window.history.replaceState({}, "", url);
+
+    // get individual terms from highlight string
+    const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
+    if (terms.length === 0) return; // nothing to do
+
+    // There should never be more than one element matching "div.body"
+    const divBody = document.querySelectorAll("div.body");
+    const body = divBody.length ? divBody[0] : document.querySelector("body");
+    window.setTimeout(() => {
+      terms.forEach((term) => _highlightText(body, term, "highlighted"));
+    }, 10);
+
+    const searchBox = document.getElementById("searchbox");
+    if (searchBox === null) return;
+    searchBox.appendChild(
+      document
+        .createRange()
+        .createContextualFragment(
+          '<p class="highlight-link">' +
+            '<a href="javascript:SphinxHighlight.hideSearchWords()">' +
+            _("Hide Search Matches") +
+            "</a></p>"
+        )
+    );
+  },
+
+  /**
+   * helper function to hide the search marks again
+   */
+  hideSearchWords: () => {
+    document
+      .querySelectorAll("#searchbox .highlight-link")
+      .forEach((el) => el.remove());
+    document
+      .querySelectorAll("span.highlighted")
+      .forEach((el) => el.classList.remove("highlighted"));
+    localStorage.removeItem("sphinx_highlight_terms")
+  },
+
+  initEscapeListener: () => {
+    // only install a listener if it is really needed
+    if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
+
+    document.addEventListener("keydown", (event) => {
+      // bail for input elements
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      // bail with special keys
+      if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
+      if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
+        SphinxHighlight.hideSearchWords();
+        event.preventDefault();
+      }
+    });
+  },
+};
+
+_ready(SphinxHighlight.highlightSearchWords);
+_ready(SphinxHighlight.initEscapeListener);

documentation/build/bootrom/s905x3.html

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>BootROM S905X3 &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/drawio.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
+        <script src="../_static/doctools.js"></script>
+        <script src="../_static/sphinx_highlight.js"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" />
+    <link rel="prev" title="Herreguard R&amp;D on Amlogic" href="../index.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="../index.html" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"><ul>
+<li><a class="reference internal" href="#">BootROM S905X3</a></li>
+</ul>
+</div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">BootROM S905X3</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="../_sources/bootrom/s905x3.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <section id="bootrom-s905x3">
+<h1>BootROM S905X3<a class="headerlink" href="#bootrom-s905x3" title="Permalink to this heading"></a></h1>
+<p>For the binaries of the BootROM, please refer to the following link:
+<a class="reference external" href="https://git.herreweb.nl/EljakimHerrewijnen/Bootrom_collections">https://git.herreweb.nl/EljakimHerrewijnen/Bootrom_collections</a></p>
+<p>Also the ghidra server will contain an Amlogic Project(when I have set it up).</p>
+</section>
+
+
+           </div>
+          </div>
+          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+        <a href="../index.html" class="btn btn-neutral float-left" title="Herreguard R&amp;D on Amlogic" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+    </div>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>

documentation/build/genindex.html

@@ -0,0 +1,97 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Index &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="_static/drawio.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
+        <script src="_static/doctools.js"></script>
+        <script src="_static/sphinx_highlight.js"></script>
+    <script src="_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="#" />
+    <link rel="search" title="Search" href="search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="index.html" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"></div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="index.html">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="index.html" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">Index</li>
+      <li class="wy-breadcrumbs-aside">
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+
+<h1 id="index">Index</h1>
+
+<div class="genindex-jumpbox">
+ 
+</div>
+
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>

documentation/build/index.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Herreguard R&amp;D on Amlogic &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="_static/drawio.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
+        <script src="_static/doctools.js"></script>
+        <script src="_static/sphinx_highlight.js"></script>
+    <script src="_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="BootROM S905X3" href="s905x3/s905x3.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="#" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"><ul>
+<li><a class="reference internal" href="#">Herreguard R&amp;D on Amlogic</a></li>
+</ul>
+</div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="#">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="#" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">Herreguard R&amp;D on Amlogic</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="_sources/index.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <section id="herreguard-r-d-on-amlogic">
+<h1>Herreguard R&amp;D on Amlogic<a class="headerlink" href="#herreguard-r-d-on-amlogic" title="Permalink to this heading"></a></h1>
+<p>Research and tools developed for hacking Amlogic based devices.
+This project serves as one of the reference projects on how to do emulation and fuzzing.</p>
+<div class="toctree-wrapper compound">
+<p class="caption" role="heading"><span class="caption-text">Bootroms</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="s905x3/s905x3.html">BootROM S905X3</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="s905x3/s905x3.html#bootrom-exploit">Bootrom Exploit</a></li>
+<li class="toctree-l2"><a class="reference internal" href="s905x3/s905x3.html#u-boot">U-Boot</a></li>
+<li class="toctree-l2"><a class="reference internal" href="s905x3/s905x3.html#emulation">Emulation</a></li>
+</ul>
+</li>
+</ul>
+</div>
+</section>
+
+
+           </div>
+          </div>
+          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+        <a href="s905x3/s905x3.html" class="btn btn-neutral float-right" title="BootROM S905X3" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+    </div>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>

documentation/build/s905x3/debugger_implementation.html

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Debugger Implementation &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/drawio.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
+        <script src="../_static/doctools.js"></script>
+        <script src="../_static/sphinx_highlight.js"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="../index.html" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"><ul>
+<li><a class="reference internal" href="#">Debugger Implementation</a></li>
+</ul>
+</div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">Debugger Implementation</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="../_sources/s905x3/debugger_implementation.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <section id="debugger-implementation">
+<h1>Debugger Implementation<a class="headerlink" href="#debugger-implementation" title="Permalink to this heading"></a></h1>
+<p>The debugger for this processor is implemented with the following memory map:</p>
+<img alt="../_images/debugger_memory_overview.svg" class="drawio" src="../_images/debugger_memory_overview.svg" /></section>
+
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>

documentation/build/s905x3/emulation.html

@@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Emulation &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/drawio.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
+        <script src="../_static/doctools.js"></script>
+        <script src="../_static/sphinx_highlight.js"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="../index.html" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"><ul>
+<li><a class="reference internal" href="#">Emulation</a><ul>
+<li><a class="reference internal" href="#devices">Devices</a><ul>
+<li><a class="reference internal" href="#uart-device">UART Device</a></li>
+<li><a class="reference internal" href="#timer-device">Timer Device</a></li>
+<li><a class="reference internal" href="#todo">TODO</a></li>
+<li><a class="reference internal" href="#i2c-device">I2C Device</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">Emulation</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="../_sources/s905x3/emulation.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <section id="emulation">
+<h1>Emulation<a class="headerlink" href="#emulation" title="Permalink to this heading"></a></h1>
+<p>Figure out where the stack is set:</p>
+<figure class="align-default">
+<img alt="../_images/find_stack_address.png" src="../_images/find_stack_address.png" />
+</figure>
+<p>The stack is set at: <code class="docutils literal notranslate"><span class="pre">0xfffe3800</span></code>.</p>
+<section id="devices">
+<h2>Devices<a class="headerlink" href="#devices" title="Permalink to this heading"></a></h2>
+<p>The goal is to make a fuzzer for the <code class="docutils literal notranslate"><span class="pre">USB</span></code> and <code class="docutils literal notranslate"><span class="pre">I2C</span></code> devices.
+To get insight and help with reverse engineering an emulator is being developed.</p>
+<section id="uart-device">
+<h3>UART Device<a class="headerlink" href="#uart-device" title="Permalink to this heading"></a></h3>
+<p>UART is implemented in software. When the device boots it always sends a message over UART, this can now be printed:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>print(bytes(self.get_device(&quot;UART&quot;).get_rx()))
+b&#39;BL:511f6b:\x00\x00\x00\x00\x00\x00;FEAT:FF800228:0;POC:0;RCY:0;USB:0;&#39;
+</pre></div>
+</div>
+</section>
+<section id="timer-device">
+<h3>Timer Device<a class="headerlink" href="#timer-device" title="Permalink to this heading"></a></h3>
+<p>Timer device is also implemented.</p>
+</section>
+<section id="todo">
+<h3>TODO<a class="headerlink" href="#todo" title="Permalink to this heading"></a></h3>
+<ul class="simple">
+<li><p>Implement USB device</p></li>
+<li><p>Dump Efuses from reference device and use it in the emulator, along with an efuse device</p></li>
+</ul>
+</section>
+<section id="i2c-device">
+<h3>I2C Device<a class="headerlink" href="#i2c-device" title="Permalink to this heading"></a></h3>
+<p>Quickly after boot a string is read from I2C.
+According to several sources on the internet this I2C device is in the HDMI port(TODO check this).</p>
+<p>I2C is a serial protocol, which relies on 2 lines, SCK for clock and SDA for data. For this SoC and using the emulator we can see that GPIO25 is used for SCL and GPIO27 for SDA.</p>
+<p>For Emulating this</p>
+<p>Explanation of I2C according to ChatGPT:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>The I2C (Inter-Integrated Circuit) protocol is a popular serial communication protocol used for communication between integrated circuits (ICs) in various electronic devices. It was developed by Philips (now NXP Semiconductors) and is widely adopted due to its simplicity and versatility.
+
+Key features of the I2C protocol include:
+
+Master-Slave Architecture: The I2C bus typically consists of one or more master devices and multiple slave devices. The master device initiates and controls the communication, while the slave devices respond to commands and provide data or services.
+
+Two-Wire Communication: I2C utilizes two lines for communication: a serial data line (SDA) and a serial clock line (SCL). Both lines are bidirectional, allowing data to be transmitted in both directions.
+
+Addressing: Each slave device on the I2C bus has a unique address, allowing the master device to communicate with specific slaves. Addressing can be 7-bit or 10-bit, depending on the device and the variant of the I2C protocol.
+
+Start and Stop Conditions: Communication on the I2C bus is initiated by the master device by asserting a start condition (a falling edge on SDA while SCL is high). The start condition indicates the beginning of a transmission. The master also sends a stop condition (a rising edge on SDA while SCL is high) to indicate the end of a transmission.
+
+Data Transmission: Data is transferred in bytes (8 bits) between the master and slave devices. Each byte is followed by an acknowledgment (ACK) or not-acknowledgment (NACK) bit, indicating whether the receiver successfully received the data.
+
+Clock Synchronization: The I2C protocol relies on the synchronized clock signals on the SCL line. Both the master and slave devices operate based on this clock signal.
+
+Standard and Fast Modes: The I2C protocol supports two main modes: Standard Mode (up to 100 kbit/s) and Fast Mode (up to 400 kbit/s). Some devices also support High-Speed Mode (up to 3.4 Mbit/s) and Ultra-Fast Mode (up to 5 Mbit/s).
+
+Multi-Master Support: I2C supports multi-master communication, allowing multiple master devices to coexist on the same bus. Collision detection and arbitration mechanisms are employed to prevent conflicts and ensure proper communication.
+
+The I2C protocol is commonly used for various purposes, including connecting sensors, memory devices, displays, and other peripheral devices to microcontrollers, embedded systems, and other electronic devices. It provides a simple and efficient means of serial communication with minimal wiring requirements.
+
+It&#39;s important to note that different devices and implementations may have specific variations or additional features built on top of the basic I2C protocol. Therefore, it&#39;s always recommended to refer to the device datasheet or the specific implementation documentation for detailed information on the usage and configuration of I2C in a particular system.
+</pre></div>
+</div>
+</section>
+</section>
+</section>
+
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>

documentation/build/s905x3/s905x3.html

@@ -0,0 +1,314 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>BootROM S905X3 &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/drawio.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
+        <script src="../_static/doctools.js"></script>
+        <script src="../_static/sphinx_highlight.js"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" />
+    <link rel="prev" title="Herreguard R&amp;D on Amlogic" href="../index.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="../index.html" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"><ul>
+<li><a class="reference internal" href="#">BootROM S905X3</a><ul>
+<li><a class="reference internal" href="#bootrom-exploit">Bootrom Exploit</a><ul>
+<li><a class="reference internal" href="#github">github</a></li>
+<li><a class="reference internal" href="#dumping-the-bootrom">Dumping the bootrom</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#u-boot">U-Boot</a><ul>
+<li><a class="reference internal" href="#build-u-boot">Build U-Boot</a></li>
+<li><a class="reference internal" href="#implementing-usb">Implementing USB</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#emulation">Emulation</a><ul>
+<li><a class="reference internal" href="#fastboot">Fastboot</a><ul>
+<li><a class="reference internal" href="#getvar">getvar</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">BootROM S905X3</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="../_sources/s905x3/s905x3.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <section id="bootrom-s905x3">
+<h1>BootROM S905X3<a class="headerlink" href="#bootrom-s905x3" title="Permalink to this heading"></a></h1>
+<p>For the binaries of the BootROM, please refer to the following link:
+<a class="reference external" href="https://git.herreweb.nl/EljakimHerrewijnen/Bootrom_collections">https://git.herreweb.nl/EljakimHerrewijnen/Bootrom_collections</a></p>
+<p>Also the ghidra server will contain an Amlogic Project(when I have set it up).</p>
+<p>This Amlogic processor is in a lot of Android TV boxes, which you can buy on marketplaces like Aliexpress.
+These devices are fun to buy because they are cheap but have quite a lot of pheriperals and features, which you would usually not have in a development board.</p>
+<p>The device used in here is the <code class="docutils literal notranslate"><span class="pre">VONTAR</span> <span class="pre">X96</span> <span class="pre">Air</span></code> whic is <a class="reference external" href="https://nl.aliexpress.com/item/4000218231701.html?spm=a2g0o.order_list.order_list_main.140.21ef79d2UAsDbQ&amp;gatewayAdapt=glo2nld">available on aliexpress</a>.</p>
+<p>This device has the following features:</p>
+<blockquote>
+<div><ul class="simple">
+<li><p>4GB LPDDR4 RAM</p></li>
+<li><p>64GB eMMC storage</p></li>
+<li><p>1000Mbit ethernet</p></li>
+<li><p>Wifi &amp; Bluetooth</p></li>
+</ul>
+</div></blockquote>
+<section id="bootrom-exploit">
+<h2>Bootrom Exploit<a class="headerlink" href="#bootrom-exploit" title="Permalink to this heading"></a></h2>
+<p>There is already a bootrom vulnerability for this SoC family, which was published on <a class="reference external" href="https://fredericb.info/2021/02/amlogic-usbdl-unsigned-code-loader-for-amlogic-bootrom.html">fred’s blog</a>.
+This vulnerability has not yet been exploited on this specific SoC type, so let’s first exploit it.</p>
+<p>Let’s first take a look at the memory layout used by the SoC</p>
+<img alt="../_images/soc_memory_1.svg" class="drawio" src="../_images/soc_memory_1.svg" /><p>According to the documentation from fred’s notes, the vulnerability is in the handling of the <strong>REQ_WR_LARGE_MEM</strong> command.
+This command does not check if we send empty transfers and due to this we can overflow the download buffer and overwrite our <code class="docutils literal notranslate"><span class="pre">Link</span> <span class="pre">Register</span> <span class="pre">(LR)</span></code>.</p>
+<p>To check if this vulnerability is present we will first see if we can crash the device. We do this by trying to overflow a large portion of the download buffer and to send payloads with valid pointers to the start of the bootrom.
+We should be able to send at least 64kb of data to the download buffer, if we can overflow the first part we should at some point get a crash and have an indication of where the stack is located on the target device.</p>
+<p>The code to do this is here:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_vulnerability</span><span class="p">():</span>
+    <span class="n">device</span> <span class="o">=</span> <span class="n">AmlogicDevice</span><span class="p">()</span>
+    <span class="n">controlData</span> <span class="o">=</span> <span class="n">pack</span><span class="p">(</span><span class="s1">&#39;&lt;IIII&#39;</span><span class="p">,</span> <span class="n">D_BUFFER_START</span><span class="p">,</span> <span class="n">D_BUFFER_MAX</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
+    <span class="n">device</span><span class="o">.</span><span class="n">dev</span><span class="o">.</span><span class="n">ctrl_transfer</span><span class="p">(</span><span class="n">bmRequestType</span> <span class="o">=</span> <span class="mh">0x40</span><span class="p">,</span>
+        <span class="n">bRequest</span> <span class="o">=</span> <span class="n">REQ_WR_LARGE_MEM</span><span class="p">,</span>
+        <span class="n">wValue</span> <span class="o">=</span> <span class="n">BULK_TRANSFER_SIZE</span><span class="p">,</span>
+        <span class="n">wIndex</span> <span class="o">=</span> <span class="mi">100000</span><span class="p">,</span>
+        <span class="n">data_or_wLength</span> <span class="o">=</span> <span class="n">controlData</span><span class="p">)</span>
+
+    <span class="n">guess_overflow</span> <span class="o">=</span> <span class="mi">1070</span> <span class="c1"># 0xfffe3688 on a reference device, which is 1078 empty buffers ((0xfffe3688 - D_BUFFER_START) // BULK_TRANSFER_SIZE)</span>
+    <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">guess_overflow</span><span class="p">):</span>
+        <span class="n">device</span><span class="o">.</span><span class="n">usb_write</span><span class="p">(</span><span class="sa">b</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+
+    <span class="n">overflow_addr</span> <span class="o">=</span> <span class="n">D_BUFFER_START</span> <span class="o">+</span> <span class="p">(</span><span class="n">guess_overflow</span> <span class="o">*</span> <span class="n">BULK_TRANSFER_SIZE</span><span class="p">)</span>
+    <span class="n">payload</span> <span class="o">=</span> <span class="n">struct</span><span class="o">.</span><span class="n">pack</span><span class="p">(</span><span class="s2">&quot;&lt;Q&quot;</span><span class="p">,</span> <span class="n">BOOTROM_START</span><span class="p">)</span> <span class="o">*</span> <span class="p">(</span><span class="n">BULK_TRANSFER_SIZE</span> <span class="o">//</span> <span class="mi">8</span><span class="p">)</span>
+    <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
+        <span class="n">device</span><span class="o">.</span><span class="n">usb_write</span><span class="p">(</span><span class="n">payload</span><span class="p">)</span>
+        <span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Overflowing: </span><span class="si">{</span><span class="nb">hex</span><span class="p">(</span><span class="n">overflow_addr</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+
+<span class="c1"># Results in:</span>
+<span class="c1"># [i] Overflowing: 0xfffe2e00</span>
+</pre></div>
+</div>
+<p>The result of this code is that the device crashes at overflow address <strong>0xfffe2e00</strong>, meaning we are probably overwriting the stack here.</p>
+<p>This overflow can now be visualised as follows:</p>
+<img alt="../_images/soc_memory_overflow.svg" class="drawio" src="../_images/soc_memory_overflow.svg" /><section id="github">
+<h3>github<a class="headerlink" href="#github" title="Permalink to this heading"></a></h3>
+<p>As it turns out, someone else has already exploited this vulnerability, this code can be found <a class="reference external" href="https://github.com/Raxone/amlogic-usbdl_s905x3">on github</a>. This is why it is always good to do a thorough research on existing research when starting a new project.</p>
+</section>
+<section id="dumping-the-bootrom">
+<h3>Dumping the bootrom<a class="headerlink" href="#dumping-the-bootrom" title="Permalink to this heading"></a></h3>
+<p>Using the above code and reference code from uboot we can attach the debugger to this device. We need to implement send/receive, however with only a functioning send we can already know that the debugger is living and we first want to dump the bootrom.</p>
+<p>One of the <em>currently</em> missing functionalities is something to run code on the first boot/setup of the GA, since it assumes peek/poke is already setup. This might be something we will need to change in the future. We can dump the bootrom with the following code:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span><span class="w"> </span><span class="nf">recv_data</span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">data</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">len</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
+<span class="w">    </span><span class="c1">//Dump bootrom</span>
+<span class="w">    </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">tx</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span><span class="w"></span>
+<span class="w">    </span><span class="n">send</span><span class="p">((</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="mh">0xFFFF0000</span><span class="p">,</span><span class="w"> </span><span class="mh">0x10000</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">tx</span><span class="p">);</span><span class="w"></span>
+<span class="p">}</span><span class="w"></span>
+</pre></div>
+</div>
+</section>
+</section>
+<section id="u-boot">
+<h2>U-Boot<a class="headerlink" href="#u-boot" title="Permalink to this heading"></a></h2>
+<p>To get more insight into some <code class="docutils literal notranslate"><span class="pre">BootROM</span></code> functions, we can build <code class="docutils literal notranslate"><span class="pre">U-Boot</span></code>. This is an opensource and widely used bootloader.
+A lot of functionalities are copied into the <code class="docutils literal notranslate"><span class="pre">BootROM</span></code>, meaning that we could try to get some structures and functions from <code class="docutils literal notranslate"><span class="pre">U-Boot</span></code> into Ghidra.</p>
+<p>To do this we will have to build <code class="docutils literal notranslate"><span class="pre">U-Boot</span></code> with symbols, then create a symbol database from <code class="docutils literal notranslate"><span class="pre">U-Boot</span></code> into Ghidra and use that database to find and rename functions in the <code class="docutils literal notranslate"><span class="pre">BootROM</span></code></p>
+<section id="build-u-boot">
+<h3>Build U-Boot<a class="headerlink" href="#build-u-boot" title="Permalink to this heading"></a></h3>
+<p>To build U-Boot you will need:</p>
+<blockquote>
+<div><ul class="simple">
+<li><p>a gcc-aarch64 compiler (sudo apt install gcc-aarch64-linux-gnu)</p></li>
+<li><p>bison (sudo apt install bison)</p></li>
+<li><p>flex (sudo apt install flex)</p></li>
+</ul>
+</div></blockquote>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git clone https://source.denx.de/u-boot/u-boot.git
+<span class="gp">$ </span><span class="nb">export</span> <span class="nv">CROSS_COMPILE</span><span class="o">=</span>aarch64-linux-gnu-
+<span class="gp">$ </span><span class="nb">export</span> <span class="nv">ARCH</span><span class="o">=</span>arm64
+<span class="gp">$ </span>make sei610_defconfig
+<span class="gp">$ </span>make -j2
+</pre></div>
+</div>
+</section>
+<section id="implementing-usb">
+<h3>Implementing USB<a class="headerlink" href="#implementing-usb" title="Permalink to this heading"></a></h3>
+</section>
+</section>
+<section id="emulation">
+<h2>Emulation<a class="headerlink" href="#emulation" title="Permalink to this heading"></a></h2>
+<p>Figure out where the stack is set:</p>
+<figure class="align-default">
+<img alt="../_images/find_stack_address.png" src="../_images/find_stack_address.png" />
+</figure>
+<p>The stack is set at: <code class="docutils literal notranslate"><span class="pre">0xfffe3800</span></code>.</p>
+<p>The goal is to make a fuzzer for the <code class="docutils literal notranslate"><span class="pre">USB</span></code> and <code class="docutils literal notranslate"><span class="pre">I2C</span></code> devices.
+To get insight and help with reverse engineering an emulator is being developed.</p>
+<p>UART is implemented in software. When the device boots it always sends a message over UART, this can now be printed:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>print(bytes(self.get_device(&quot;UART&quot;).get_rx()))
+b&#39;BL:511f6b:\x00\x00\x00\x00\x00\x00;FEAT:FF800228:0;POC:0;RCY:0;USB:0;&#39;
+</pre></div>
+</div>
+<p>Timer device is also implemented.</p>
+<ul class="simple">
+<li><p>Implement USB device</p></li>
+<li><p>Dump Efuses from reference device and use it in the emulator, along with an efuse device</p></li>
+</ul>
+<p>Quickly after boot a string is read from I2C.
+According to several sources on the internet this I2C device is in the HDMI port(TODO check this).</p>
+<p>I2C is a serial protocol, which relies on 2 lines, SCK for clock and SDA for data. For this SoC and using the emulator we can see that GPIO25 is used for SCL and GPIO27 for SDA.</p>
+<p>For Emulating this</p>
+<p>Explanation of I2C according to ChatGPT:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>The I2C (Inter-Integrated Circuit) protocol is a popular serial communication protocol used for communication between integrated circuits (ICs) in various electronic devices. It was developed by Philips (now NXP Semiconductors) and is widely adopted due to its simplicity and versatility.
+
+Key features of the I2C protocol include:
+
+Master-Slave Architecture: The I2C bus typically consists of one or more master devices and multiple slave devices. The master device initiates and controls the communication, while the slave devices respond to commands and provide data or services.
+
+Two-Wire Communication: I2C utilizes two lines for communication: a serial data line (SDA) and a serial clock line (SCL). Both lines are bidirectional, allowing data to be transmitted in both directions.
+
+Addressing: Each slave device on the I2C bus has a unique address, allowing the master device to communicate with specific slaves. Addressing can be 7-bit or 10-bit, depending on the device and the variant of the I2C protocol.
+
+Start and Stop Conditions: Communication on the I2C bus is initiated by the master device by asserting a start condition (a falling edge on SDA while SCL is high). The start condition indicates the beginning of a transmission. The master also sends a stop condition (a rising edge on SDA while SCL is high) to indicate the end of a transmission.
+
+Data Transmission: Data is transferred in bytes (8 bits) between the master and slave devices. Each byte is followed by an acknowledgment (ACK) or not-acknowledgment (NACK) bit, indicating whether the receiver successfully received the data.
+
+Clock Synchronization: The I2C protocol relies on the synchronized clock signals on the SCL line. Both the master and slave devices operate based on this clock signal.
+
+Standard and Fast Modes: The I2C protocol supports two main modes: Standard Mode (up to 100 kbit/s) and Fast Mode (up to 400 kbit/s). Some devices also support High-Speed Mode (up to 3.4 Mbit/s) and Ultra-Fast Mode (up to 5 Mbit/s).
+
+Multi-Master Support: I2C supports multi-master communication, allowing multiple master devices to coexist on the same bus. Collision detection and arbitration mechanisms are employed to prevent conflicts and ensure proper communication.
+
+The I2C protocol is commonly used for various purposes, including connecting sensors, memory devices, displays, and other peripheral devices to microcontrollers, embedded systems, and other electronic devices. It provides a simple and efficient means of serial communication with minimal wiring requirements.
+
+It&#39;s important to note that different devices and implementations may have specific variations or additional features built on top of the basic I2C protocol. Therefore, it&#39;s always recommended to refer to the device datasheet or the specific implementation documentation for detailed information on the usage and configuration of I2C in a particular system.
+</pre></div>
+</div>
+<section id="fastboot">
+<h3>Fastboot<a class="headerlink" href="#fastboot" title="Permalink to this heading"></a></h3>
+<p>Commands available on Chromecast device:</p>
+<section id="getvar">
+<h4>getvar<a class="headerlink" href="#getvar" title="Permalink to this heading"></a></h4>
+<pre class="literal-block">amlogic.usb_write(b&quot;getvar:version&quot;)
+d = amlogic.usb_read(0x200)
+d
+b'OKAY0.1\x00downloadsize\x000x\x00max-download-size\x00serialno\x00product\x00AMLOGIC\x00i\x00'
+d.decode()
+'OKAY0.1\x00downloadsize\x000x\x00max-download-size\x00serialno\x00product\x00AMLOGIC\x00i\x00'
+print(d.decode())
+OKAY0.1downloadsize0xmax-download-sizeserialnoproductAMLOGICi
+amlogic.usb_write(b&quot;getvar:downloadsize&quot;)
+hexdump(amlogic.usb_read(0x200))
+        ┌─────────────────────────────────────────────────┬──────────────────┐
+0x00000000 │ 4f 4b 41 59 30 78 30 30 30 32 39 38 30 30 00 6c │ OKAY0x00029800.l │
+0x00000010 │ 6f 61 64 2d 73 69 7a 65 00 73 65 72 69 61 6c 6e │ oad-size.serialn │
+0x00000020 │ 6f 00 70 72 6f 64 75 63 74 00 41 4d 4c 4f 47 49 │ o.product.AMLOGI │
+0x00000030 │ 43 00 69 64 65 6e 74 69 66 79 00 67 65 74 63 68 │ C.identify.getch │
+0x00000040 │ 69 70 69 6e 00                                  │ ipin.            │
+        └─────────────────────────────────────────────────┴──────────────────┘
+
+amlogic.usb_write(b&quot;getvar:serialno&quot;)
+hexdump(amlogic.usb_read(0x200))
+           ┌─────────────────────────────────────────────────┬──────────────────┐
+0x00000000 │ 4f 4b 41 59 38 30 64 39 63 33 30 38 38 38 39 31 │ OKAY80d9c3088891 │
+0x00000010 │ 32 65 31 62 30 30 30 30 30 30 30 30 00 00 00 00 │ 2e1b00000000.... │
+0x00000020 │ 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 │ ................ │
+0x00000030 │ 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 │ ................ │
+0x00000040 │ 00 00 00 00 00                                  │ .....            │
+           └─────────────────────────────────────────────────┴──────────────────┘</pre>
+<p>Max number of arguments is 0xb?</p>
+<p>Seems we dump something from the stack when doing the getvar:identify command</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>amlogic.usb_write(b&quot;getvar:identify:::::identify&quot;)
+hexdump(amlogic.usb_read(0x200))
+           ┌─────────────────────────────────────────────────┬──────────────────┐
+0x00000000 │ 4f 4b 41 59 06 00 00 00 01 00 00 0f 00 b1 02 f7 │ OKAY............ │
+0x00000010 │ 00 00 00 00 00 00 00 00 00 00 00 00 20 ee 02 f7 │ ............ ... │
+0x00000020 │ 00 00 00 00 a8 44 ff ff 00 00 00 00 48 c1 02 f7 │ .....D......H... │
+0x00000030 │ 00 00 00 00 a4 30 ff ff 00 00 00 00 b0 ee 02 f7 │ .....0.......... │
+0x00000040 │ 00 00 00 00 00                                  │ .....            │
+           └─────────────────────────────────────────────────┴──────────────────┘
+</pre></div>
+</div>
+<p>Using multiple commands it’s possible to <em>somewhat</em> influence what we dump from the stack.</p>
+<p>Download size seems to be 0x29800</p>
+</section>
+</section>
+</section>
+</section>
+
+
+           </div>
+          </div>
+          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+        <a href="../index.html" class="btn btn-neutral float-left" title="Herreguard R&amp;D on Amlogic" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+    </div>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>

documentation/build/search.html

@@ -0,0 +1,112 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Search &mdash; Amlogic  documentation</title>
+      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="_static/drawio.css" type="text/css" />
+    
+  <!--[if lt IE 9]>
+    <script src="_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
+        <script src="_static/doctools.js"></script>
+        <script src="_static/sphinx_highlight.js"></script>
+    <script src="_static/js/theme.js"></script>
+    <script src="_static/searchtools.js"></script>
+    <script src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="#" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="index.html" class="icon icon-home"> Amlogic
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="#" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <!-- Local TOC -->
+              <div class="local-toc"></div>
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="index.html">Amlogic</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="index.html" class="icon icon-home"></a></li>
+      <li class="breadcrumb-item active">Search</li>
+      <li class="wy-breadcrumbs-aside">
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <noscript>
+  <div id="fallback" class="admonition warning">
+    <p class="last">
+      Please activate JavaScript to enable the search functionality.
+    </p>
+  </div>
+  </noscript>
+
+  
+  <div id="search-results">
+  
+  </div>
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Eljakim.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script>
+  <script>
+    jQuery(function() { Search.loadIndex("searchindex.js"); });
+  </script>
+  
+  <script id="searchindexloader"></script>
+   
+
+
+</body>
+</html>

documentation/make.bat

@@ -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

documentation/source/conf.py

@@ -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 = 'Amlogic'
+copyright = '2024, Eljakim'
+author = 'Eljakim'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [  'myst_parser',
+                'sphinx_rtd_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_rtd_theme'
+html_static_path = ['_static']

documentation/source/index.rst

@@ -0,0 +1,18 @@
+.. Amlogic documentation master file, created by
+   sphinx-quickstart on Sat Mar 30 12:38:51 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Herreguard R&D on Amlogic
+=========================
+Research and tools developed for hacking Amlogic based devices. 
+This project serves as one of the reference projects on how to do emulation and fuzzing.
+
+
+.. toctree:: 
+   :maxdepth: 2
+   :numbered:
+   :caption: Bootroms
+
+   s905x3/s905x3.rst
+

documentation/source/s905x3/debugger_implementation.rst

@@ -0,0 +1,8 @@
+Debugger Implementation
+=======================
+
+The debugger for this processor is implemented with the following memory map:
+
+.. drawio-image:: debugger_memory_overview.drawio
+   :export-scale: 150
+

documentation/source/s905x3/debugger_memory_overview.drawio

@@ -0,0 +1 @@
+<mxfile host="1vtmh4hnua035b8vqu9jrn1ka8tkta44i3pdn3p5gt5k4an46inh" modified="2022-12-18T13:49:53.795Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Code/1.72.2 Chrome/102.0.5005.167 Electron/19.0.17 Safari/537.36" etag="awVsGq9fG2seb3ryHsJI" version="12.2.4" pages="1"><diagram id="c3WyWKUafv7mUJTXAcmN" name="Page-1">zZlbb5swFMc/TaTtoZPBYMhjk7TdNFWbmmmXp8kBQ7wSHDlOQ/rpZ4IJFztZJgEpL8HHHIP//p3jS0ZwusoeOF4vH1lIkpENwmwEZyPbthxoyZ/csi8sCPmFIeY0VA9Vhjl9JcoIlHVLQ7JpPCgYSwRdN40BS1MSiIYNc852zcciljTfusYx0QzzACe69QcNxbKw+i6o7B8JjZflmy2gala4fFgZNkscsl3NBO9GcMoZE8XdKpuSJBev1KXwuz9Re/wwTlJxiQOl8fo29H5/m3/6E4LXx+wmfrpRrbzgZKs6rD5W7EsFONumIckbASM42S2pIPM1DvLanRxzaVuKVSJLlryNaJJMWcL4wRdGUWQHgbRvBGfPpFYTogVykazRu1F+E+GCZDWT6tYDYSsi+F4+UtaWo6EYs0rJd9WIOaVtWRstVDpiRUl8bLsSUt4oLf9DV6jpCrJ7eQFQ8lFTWHZT/FvaDoRyPbchFPJ0oY4A14Vy+tLJ0XSayIDgbCWN75DzefG+Yx4JOsGjN14A0BGPqMkj8g08mmT2+5IZGXC0gLreDo+ec20exwahZBLDV9bJbyU4S9dpPKRM5ftrOs3YLk0YDqV1spVxxjsN3BATPzIGLgp8soj6CVwLXhi4bn9K6zP0jCy2cdyxwMS1nEP+0wSe2Af4pQdLRXNul1dHwnst4Q2JAPom4XvT3TZngsXbypju1TOBvtL5wmlMU5y7zgUOnrtNBC7xQ8fEqW8vIOpqRdniERkSgZFH2IHOprXjG5yDDGvHvshzz+TAHhhDAI8tz8SYPfPQ0LnwmOOGyIWmhWLOnn2GvX45s6Grdb+vyPPOc8Z4fljQJWkAuIBEJtIAsGaT6bCkQaBL3Rtp/gnS4PVIG+uB1hdp+j5D6zNJw9v8AEuWggRvNjRoKiA7zvc/c+w+yASpyr/qlbNMQVmU9mUpo6LuJ4tHN3lfeeWF0qkAtDwCs8+NwIZteUAamVtgHhNxwTKXhI3jOH3samPjniGTkwQL+tI8xDMNmHrDV0ZlL06eKPlt4os+Ki+7dujWasgGrYZAq6FCGa2hAz/Hbl+ElGlPVmWvb2S17imJRUAGLTZuHWbe4FsHiC6cLq0OwtiwOyuymDNcFmvtCKAz3Hxp2CTVkPs+uX3qFDQsl8CRcbb0JGfTgWdLx3DK3NtsadhmFaC5VwPNsXoDTRar/0WKVFj9uwTv/gI=</diagram></mxfile>

documentation/source/s905x3/emulation.rst

@@ -0,0 +1,69 @@
+Emulation
+=========
+
+Figure out where the stack is set:
+
+.. figure:: find_stack_address.png
+
+The stack is set at: ``0xfffe3800``.
+
+Devices
+-------
+
+The goal is to make a fuzzer for the ``USB`` and ``I2C`` devices. 
+To get insight and help with reverse engineering an emulator is being developed.
+
+UART Device
+###########
+UART is implemented in software. When the device boots it always sends a message over UART, this can now be printed:
+
+.. code-block:: text
+
+    print(bytes(self.get_device("UART").get_rx()))
+    b'BL:511f6b:\x00\x00\x00\x00\x00\x00;FEAT:FF800228:0;POC:0;RCY:0;USB:0;'
+
+Timer Device
+############
+Timer device is also implemented. 
+
+TODO
+####
+* Implement USB device
+* Dump Efuses from reference device and use it in the emulator, along with an efuse device
+
+I2C Device
+##########
+Quickly after boot a string is read from I2C. 
+According to several sources on the internet this I2C device is in the HDMI port(TODO check this). 
+
+I2C is a serial protocol, which relies on 2 lines, SCK for clock and SDA for data. For this SoC and using the emulator we can see that GPIO25 is used for SCL and GPIO27 for SDA.
+
+For Emulating this 
+
+Explanation of I2C according to ChatGPT:
+
+.. code-block:: text
+
+    The I2C (Inter-Integrated Circuit) protocol is a popular serial communication protocol used for communication between integrated circuits (ICs) in various electronic devices. It was developed by Philips (now NXP Semiconductors) and is widely adopted due to its simplicity and versatility.
+
+    Key features of the I2C protocol include:
+
+    Master-Slave Architecture: The I2C bus typically consists of one or more master devices and multiple slave devices. The master device initiates and controls the communication, while the slave devices respond to commands and provide data or services.
+
+    Two-Wire Communication: I2C utilizes two lines for communication: a serial data line (SDA) and a serial clock line (SCL). Both lines are bidirectional, allowing data to be transmitted in both directions.
+
+    Addressing: Each slave device on the I2C bus has a unique address, allowing the master device to communicate with specific slaves. Addressing can be 7-bit or 10-bit, depending on the device and the variant of the I2C protocol.
+
+    Start and Stop Conditions: Communication on the I2C bus is initiated by the master device by asserting a start condition (a falling edge on SDA while SCL is high). The start condition indicates the beginning of a transmission. The master also sends a stop condition (a rising edge on SDA while SCL is high) to indicate the end of a transmission.
+
+    Data Transmission: Data is transferred in bytes (8 bits) between the master and slave devices. Each byte is followed by an acknowledgment (ACK) or not-acknowledgment (NACK) bit, indicating whether the receiver successfully received the data.
+
+    Clock Synchronization: The I2C protocol relies on the synchronized clock signals on the SCL line. Both the master and slave devices operate based on this clock signal.
+
+    Standard and Fast Modes: The I2C protocol supports two main modes: Standard Mode (up to 100 kbit/s) and Fast Mode (up to 400 kbit/s). Some devices also support High-Speed Mode (up to 3.4 Mbit/s) and Ultra-Fast Mode (up to 5 Mbit/s).
+
+    Multi-Master Support: I2C supports multi-master communication, allowing multiple master devices to coexist on the same bus. Collision detection and arbitration mechanisms are employed to prevent conflicts and ensure proper communication.
+
+    The I2C protocol is commonly used for various purposes, including connecting sensors, memory devices, displays, and other peripheral devices to microcontrollers, embedded systems, and other electronic devices. It provides a simple and efficient means of serial communication with minimal wiring requirements.
+
+    It's important to note that different devices and implementations may have specific variations or additional features built on top of the basic I2C protocol. Therefore, it's always recommended to refer to the device datasheet or the specific implementation documentation for detailed information on the usage and configuration of I2C in a particular system.

documentation/source/s905x3/soc_memory_1.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-11-30T21:52:54.703Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.3.0 Chrome/104.0.5112.114 Electron/20.1.3 Safari/537.36" etag="8SgH3kv1q6hSqkNxlHDF" version="20.3.0" type="device"><diagram id="c3WyWKUafv7mUJTXAcmN" name="Page-1">zZddb5swFIZ/DdJ2UclgY+BySdOumnIzJu1yMth8rCZGjjNIf/2cxg5QqJpKpA3KhXnPsbEfvwcTBy6r9l6SulgLyrjjAdo68NbxPBd5nnP4Abo/KmEAjkIuS2qSOiEun5gRbdqupGw7SFRCcFXWQzEVmw1L1UAjUopmmJYJPnxqTXI2EuKU8LH6u6SqMKvwQad/Z2Ve2Ce7wEQqYpONsC0IFU1PgisHLqUQ6tiq2iXjB3iWy7Hf3SvR08Qk26hzOpRlXn+jwZ9f8cNfCp7W7U3+88aM8o/wnVmwmazaWwJS7DaUHQYBDlw0RalYXJP0EG30nmutUBXXd65uZiXnS8GFfO4Lsyzz0lTrWyXFI+tFKE6wj3VkvAw7JyYVa3uSWdY9ExVTcq9TbNTuhvGYa5E33Y4hqxW93cK2IzEuyU9jdyB1w7B8B1c44graO30BYP3RI6yXqd5GOwMoPxyC8uEY1MnAfVDoUpzQiNNCF4QUlRa/YPQj+TqzHxl+xY9BlAAwkx/xC8xowo9TmMNLYcYTdnSBua7Hjxh8th+jCVD6JUauixMM0IhT9JGY7Onc4/SwXq1nrVVKWJhN1ipOQ5Zkl6lVGLrn1aqLokvBHR/Kt6LZcEGoVhc7/RKTs5JmLvVZMEU6wgEkc53SwQvS0bjYYfihLvamqz25rmpHrv/J1T7+mokVSR/nLXefhRRNmTD0EogvZEJ0rgnh++Hq2+7r/jnW+48EV/8B</diagram></mxfile>

documentation/source/s905x3/soc_memory_overflow.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-11-30T21:50:42.955Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.3.0 Chrome/104.0.5112.114 Electron/20.1.3 Safari/537.36" etag="VGcZJAgJ3Qm-u54l4md1" version="20.3.0" type="device"><diagram id="c3WyWKUafv7mUJTXAcmN" name="Page-1">zZhdb5swFIZ/TaTtopPBYOCy+ehWTdGqZVK3q8nBBrySOHKchvTXzxSbQEzWTIK2uQl+sQ/2c94DmBGcrIrPAm+yOSc0H7mAFCM4HbmuA31P/ZXKoVJCN6qEVDCiOx2FBXuiWgRa3TFCt62OkvNcsk1bjPl6TWPZ0rAQfN/ulvC8fdUNTqklLGKc2+o9IzLTq/DBUf9CWZqZKztAn1lh01kL2wwTvm9IcDaCE8G5rI5WxYTmJTzDpRp3c+ZsPTFB1/KSAYylm2sS/P6xuP1DwNO8uEq/X+kojzjf6QXrycqDISD4bk1oGQSM4HifMUkXGxyXZ/cq50rL5CpXLUcdJizPJzzn4nksTJLEjWOlb6XgD7RxhqAl8pE6oydAhaTF2ZU5NS9lNMpXVIqD6mIGmGxojzkG+f6YMc9oWSNbyAzE2iVpHfsIUh1olv/BFVpcQXGjfgAYfzQIq5XLl9H2AMoP26B8aIOqDdwE5Q3FybM4jVVBCL5S4gfkfV1+7NmPFJ3xYxAtAejJj+gEs9fhxy7M4VCYUYcdHaB/78ePCLy1H6MOUOomht8XJxh4FqfoNTGZp3OD0+18Nu+1VgmmYdJZqygO6TIZplZh6FxWq44XDQXXfihP+X6dc0yUOt6pm5jolTR1iE+DLtIRCiDu6ykdnJCO7GKH4au62O2u9uX7qnbP8d+42u23mYXE8UO/5e7TkHhdJgzdJUQDmdC71IRwMLj2K9C3R5rkaqvQJ96ZM/Vn/65xgrfZc3QzfKEvjXeSKykVmDDFuRk1uB5PnDqq2SG5Ze8cb7d6qkMkruPVtTNxaLDEBVbirIzRNbkuN6GqFZc8WNxOUjujCoU4/CwbnyAKjfCrEiA0wrRo9p8emq07KphaHhVGLJg0EZFuVwEBCHT7GK9sHBqN02jV+iixtswnWVQM+E7E9ALbSyxSKl+8+di+aOTd70i70QTNsWSP7Ql3eUFf4Y4ztZTadvVN1dju9BW9Wqge1dx9nwaKzvjXBKpAWIGerVkvu8utqnn8iFB1P36KgbO/</diagram></mxfile>

source/bootrom_emulator/.gitignore

@@ -0,0 +1,167 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+#
+
+# Ignore remote_devices/ folder. These should be added by the user
+dump/
+remote_devices/
+external/
+venv/

source/bootrom_emulator/.vscode/launch.json

@@ -0,0 +1,25 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Run Emulator",
+            "type": "python",
+            "request": "launch",
+            "program": "fuzzer.py",
+            "console": "integratedTerminal",
+            "justMyCode": false
+        },
+        {
+            "name": "Run Emulator",
+            "type": "python",
+            "request": "launch",
+            "program": "fuzzer.py",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            ""
+        },
+    ]
+}

source/bootrom_emulator/Dockerfile

@@ -0,0 +1,20 @@
+# Dockerfile for fuzzing deployment
+
+FROM aflplusplus/aflplusplus
+
+RUN apt-get update && apt-get install -y \
+    vim \
+    net-tools \
+    build-essential \
+    cmake \
+    screen \
+&& rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /requirements.txt
+
+RUN pip3 install --upgrade pip
+RUN pip3 install -r /requirements.txt
+
+# RUN pip3 uninstall -y unicorn
+# RUN rm -rf unicorn/build_python/
+# RUN cd unicorn/bindings/python/ && python3 setup.py install

source/bootrom_emulator/Readme.md

@@ -0,0 +1,23 @@
+# Fuzzer
+
+```bash
+sudo docker build --tag amlogicfuzzer:0.1 -f Dockerfile .
+sudo docker create --name amlogicfuzzer -ti -v $(pwd):/fuzz amlogicfuzzer:0.1
+sudo docker start amlogicfuzzer
+sudo docker exec -ti amlogicfuzzer bash
+```
+
+## Deployting
+Save the container
+```bash
+```
+
+## Usage
+```bash
+afl-fuzz -U -m none  -o /tmp/output_fuzz -i input/ python3 fuzzer.py
+```
+
+debug
+```bash
+AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 AFL_SKIP_CPUFREQ=1 AFL_DEBUG=1 afl-fuzz -U -m none  -o /tmp/output_fuzz2 -i input/ python3 fuzzer.py @@
+```

source/bootrom_emulator/add_memory_maps.py

@@ -0,0 +1,165 @@
+# from utils.utils import *
+# # Circular import fix
+# from typing import TYPE_CHECKING
+# if TYPE_CHECKING:
+#     from emulator import GA_Emulator
+
+# Add memory maps from https://dn.odroid.com/S905X3/ODROID-C4/Docs/S905X3_Public_Datasheet_Hardkernel.pdf
+
+memory_maps = '''
+START END REGION (NORMAL)
+FFFF0000 FFFFFFFF a55_rom
+FFFE8000 FFFEFFFF reserved
+FFFA0000 FFFE7FFF ahb sram
+FFE80000 FFF9FFFF reserved
+FFE40000 FFE7FFFF mali
+FFE0D000 FFE3FFFF reserved
+FFE0B000 FFE0CFFF reserved
+FFE09000 FFE0AFFF usbctrl
+FFE07000 FFE08FFF emmcC
+FFE05000 FFE06FFF emmcB
+FFE03000 FFE04FFF emmcA
+FFE02000 FFE02FFF bt656
+FFE01000 FFE01FFF htx_hdcp22
+FFE00000 FFE00FFF reserved
+FFD27000 FFDFFFFF reserved
+FFD26000 FFD26FFF async_fifo3
+FFD25000 FFD25FFF sc
+FFD24000 FFD24FFF uart0
+FFD23000 FFD23FFF uart1
+FFD22000 FFD22FFF uart2
+FFD21000 FFD21FFF reserved
+FFD20000 FFD20FFF reserved
+FFD1F000 FFD1FFFF i2c_m0
+FFD1E000 FFD1EFFF i2c_m1
+FFD1D000 FFD1DFFF i2c_m2
+FFD1C000 FFD1CFFF i2c_m3
+FFD1B000 FFD1BFFF pwm_ab
+FFD1A000 FFD1AFFF pwm_cd
+FFD19000 FFD19FFF pwm_ef
+FFD18000 FFD18FFF msr_clk
+FFD17000 FFD17FFF reserve
+FFD16000 FFD16FFF reserved
+FFD15000 FFD15FFF spicc_1
+FFD14000 FFD14FFF spifc
+FFD13000 FFD13FFF spicc_0
+FFD12000 FFD12FFF reserved
+FFD11000 FFD11FFF reserved
+FFD10000 FFD10FFF reserved
+FFD0F000 FFD0FFFF isa
+FFD0E000 FFD0EFFF parser
+FFD0D000 FFD0DFFF parser1
+FFD0C000 FFD0CFFF sana
+FFD0B000 FFD0BFFF stream
+FFD0A000 FFD0AFFF async_fifo
+FFD09000 FFD09FFF async_fifo2
+FFD08000 FFD08FFF assist
+FFD07000 FFD07FFF
+FFD06000 FFD06FFF stb
+FFD05000 FFD05FFF aififo
+FFD04000 FFD04FFF reserved
+FFD03000 FFD03FFF reserved
+FFD02000 FFD02FFF reserved
+FFD01000 FFD01FFF reset
+FFD00000 FFD00FFF reserved
+FFC08000 FFCFFFFF reserved
+FFC00000 FFC07FFF gic
+FFB00000 FFBFFFFF gpv
+FF950000 FFAFFFFF reserved
+FF940000 FF94FFFF ge2d
+FF900000 FF93FFFF vpu
+FF80B000 FF8FFFFF reserved
+FF80A000 FF80AFFF ao_mailbox
+FF809000 FF809FFF sar_adc
+FF808000 FF808FFF ir_dec
+FF807000 FF807FFF pwm_ab
+FF806000 FF806FFF i2c_s
+FF805000 FF805FFF i2c_m
+FF804000 FF804FFF uart2
+FF803000 FF803FFF uart
+FF802000 FF802FFF pwm_cd
+FF801000 FF801FFF reserved
+FF800000 FF800FFF rti
+FF664000 FF7FFFFF reserved
+FF663800 FF663FFF
+FF663000 FF6637FF
+FF662000 FF662FFF eqdrc
+FF661C00 FF661FFF resampleA
+FF661800 FF661BFF vad
+FF661400 FF6617FF locker
+FF661000 FF6613FF pdm
+FF660000 FF660FFF audiotop
+FF652000 FF65FFFF reserved
+FF650000 FF651FFF
+FF64E000 FF64FFFF reset_sec
+FF64C000 FF64DFFF eth_phy
+FF64A000 FF64BFFF
+FF648000 FF649FFF pcie_A
+FF646000 FF647FFF pcie_phy
+FF644000 FF645FFF
+FF642000 FF643FFF
+FF640000 FF641FFF pdm
+FF63E000 FF63FFFF dma
+FF63C000 FF63DFFF hiu
+FF63A000 FF63BFFF usbphy21
+FF638000 FF639FFF dmc
+FF636000 FF637FFF usbphy20
+FF635000 FF635FFF reserved
+FF634C00 FF634FFF ts_ddr
+FF634800 FF634BFF ts_pll
+FF634400 FF6347FF periphs_reg
+FF634000 FF6343FF reserved
+FF632000 FF633FFF acodec
+FF630000 FF631FFF efuse
+FF620000 FF62FFFF dos
+FF610000 FF61FFFF wavel
+FF600000 FF60FFFF hdmitx
+FF500000 FF5FFFFF usb0
+FF400000 FF4FFFFF usb1
+FF3F0000 FF3FFFFF eth
+FF140000 FF3EFFFF reserved
+FF100000 FF13FFFF NN
+FF000000 FF0FFFFF reserved
+FE000000 FEFFFFFF ddr_ctrl
+FC000000 FDFFFFFF pcie_axi
+FA000000 FBFFFFFF reserved
+F6000000 F9FFFFFF flash
+F5800000 F5FFFFFF a55_dbg
+0 F57FFFFF ddr
+'''
+
+def find_memory(address):
+    # ff800228
+    for line in memory_maps.split("\n"):
+        if line == "" or line == 'START END REGION (NORMAL)':
+            continue
+        items = line.split(" ")
+        if len(items) >= 3:
+            start, end, name = items[0], items[1], items[2]
+        else:
+            start, end = items[0], items[1]
+            name = f"{start}_UNKNOWN"
+        start = int(start, 16)
+        end = int(end, 16)
+        if address >= start and address <= end:
+            print(f"{hex(start)}|{hex(end)}|{name}")
+            break
+
+def add_memory_maps(em : "GA_Emulator"):
+    for line in memory_maps.split("\n"):
+        if line == "" or line == 'START END REGION (NORMAL)':
+            continue
+        items = line.split(" ")
+        if len(items) >= 3:
+            start, end, name = items[0], items[1], items[2]
+        else:
+            start, end = items[0], items[1]
+            name = f"{start}_UNKNOWN"
+        start = int(start, 16)
+        end = int(end, 16)
+        # info(f"Mapping {name} at {hex(start)} with length: {hex(end - start)}")
+        # Create empty dataset only if length is smaller than 64Kb
+        if end - start > 0x10000:
+            continue
+        data = (end - start) * b"\x00"
+        em.ghidra.add_memory(data, start, False, name, False)

source/bootrom_emulator/amlogic_devices.py

@@ -0,0 +1,256 @@
+from tools import *
+
+class AmlogicDevice:
+    BASE = None
+    SIZE = None
+
+    def __init__(self, em):
+        self.em = em
+
+    def read(self, address, size):
+        raise Exception('must be implemented')
+
+    def write(self, address, size, value):
+        raise Exception('must be implemented')
+
+# //========================================================================
+# //  EFUSE
+# //========================================================================
+# //  APB4_DECODER_NON_SECURE_BASE     32'hFF630000
+# //  APB4_DECODER_SECURE_BASE         32'hFF630000
+
+
+class EfuseDevice(AmlogicDevice):
+    # 0xff630000|0xff631fff|efuse
+    BASE = 0xff630000
+    SIZE = 0x2000
+    NAME = "efuse"
+
+    EFUSE_CLR                                          = (BASE + (0x000 << 2))
+    EFUSE_START                                        = (BASE + (0x001 << 2))
+    EFUSE_WDATA0                                       = (BASE + (0x004 << 2))
+    EFUSE_WDATA1                                       = (BASE + (0x005 << 2))
+    EFUSE_WDATA2                                       = (BASE + (0x006 << 2))
+    EFUSE_WDATA3                                       = (BASE + (0x007 << 2))
+    EFUSE_RDATA0                                       = (BASE + (0x008 << 2))
+    EFUSE_RDATA1                                       = (BASE + (0x009 << 2))
+    EFUSE_RDATA2                                       = (BASE + (0x00a << 2))
+    EFUSE_RDATA3                                       = (BASE + (0x00b << 2))
+    EFUSE_LIC0                                         = (BASE + (0x00c << 2)) # 0xff630030
+    EFUSE_LIC1                                         = (BASE + (0x00d << 2)) # 0xff630034
+    EFUSE_LIC2                                         = (BASE + (0x00e << 2))
+    EFUSE_LIC3                                         = (BASE + (0x00f << 2))
+    KL_START0                                          = (BASE + (0x020 << 2))
+    KL_START1                                          = (BASE + (0x021 << 2))
+    KL_RESP0_0                                         = (BASE + (0x024 << 2))
+    KL_RESP0_1                                         = (BASE + (0x025 << 2))
+    KL_RESP0_2                                         = (BASE + (0x026 << 2))
+    KL_RESP0_3                                         = (BASE + (0x027 << 2))
+    KL_RESP1_0                                         = (BASE + (0x028 << 2))
+    KL_RESP1_1                                         = (BASE + (0x029 << 2))
+    KL_RESP1_2                                         = (BASE + (0x02a << 2))
+    KL_RESP1_3                                         = (BASE + (0x02b << 2))
+    KL_RAM                                             = (BASE + (0x040 << 2))
+    RNG_SEC_CONFIG_REG1                                = (BASE + (0x081 << 2))
+    RNG_SEC_CONFIG_REG2                                = (BASE + (0x082 << 2))
+    RNG_SEC_DATA                                       = (BASE + (0x084 << 2))
+    RNG_SEC_STS                                        = (BASE + (0x085 << 2)) #0xff630214
+    RNG_USR_DATA                                       = (BASE + (0x086 << 2))
+    RNG_USR_STS                                        = (BASE + (0x087 << 2))
+
+    EFUSE_RDY = BASE + 0x214
+
+    def __init__(self, em):
+        super().__init__(em)
+
+    def read(self, address, size):
+        if address == EfuseDevice.EFUSE_RDY:
+            self.em.write_ptr(EfuseDevice.EFUSE_RDY, 0x1)
+    
+    def write(self, address, size, value):
+        self.em.write_ptr(address, value)
+
+
+class UARTDevice(AmlogicDevice):
+    BASE = 0xff803000
+    SIZE = 0x1000
+    NAME = "UART"
+
+    UART_WFIFO = BASE +   (0<<2)
+    UART_RFIFO  = BASE +	(1<<2)
+    UART_MODE   = BASE +	(2<<2)
+    UART_STATUS = BASE + (3<<2)
+    UART_IRQCTL = BASE +	(4<<2)
+    UART_CTRL   = BASE +	(5<<2)
+
+    UART_MODE_MASK_STP_1BIT                     =(0<<16)
+    UART_MODE_MASK_CHAR_8BIT                    =(0<<20)
+    UART_MODE_MASK_TX_EN                        =(1<<12)
+    UART_MODE_MASK_RX_EN                        =(1<<13)
+
+    UART_STAT_MASK_RFIFO_FULL =                (1<<19)
+    UART_STAT_MASK_RFIFO_EMPTY  =               (1<<20)
+    UART_STAT_MASK_TFIFO_FULL                   =(1<<21)
+    UART_STAT_MASK_TFIFO_EMPTY                  =(1<<22)
+
+    UART_MODE_MASK_RST_TX                       =(1<<22)
+    UART_MODE_MASK_RST_RX                       =(1<<23)
+    UART_MODE_MASK_CLR_ERR                      =(1<<24)
+    UART_CTRL_USE_XTAL_CLK			    =BASE + (1<<24)
+    UART_CTRL_USE_NEW_BAUD_RATE		    =BASE + (1<<23)
+
+
+    def __init__(self, em):
+        super().__init__(em)
+        self.send_data = bytearray()
+        self.recv_data = bytearray()
+        self.gsc_ring_buffer_size = 0x1000
+
+    def uart_tx_isfull(self):
+        return self.em.mem_read(self.BASE + self.UART_STATUS) & self.UART_STAT_MASK_TFIFO_FULL
+
+    def uart_rx_isfull(self):
+        return self.em.mem_read(self.BASE + self.UART_STATUS) & self.UART_STAT_MASK_RFIFO_FULL
+
+    def uart_tx_flush(self):
+        #TODO
+        # while (!(readl(P_UART_STATUS(UART_PORT_CONS)) & UART_STAT_MASK_TFIFO_EMPTY))
+		#    ;
+        pass
+
+    def uart_rx_flush():
+        #TODO
+        # while (!(readl(P_UART_STATUS(UART_PORT_CONS)) & UART_STAT_MASK_RFIFO_EMPTY))
+        # 	;
+        pass
+
+
+    def read(self, address, size):
+        if address == UARTDevice.UART_STATUS:
+            if len(self.send_data) != 0 and self.gsc_ring_buffer_size != 0:
+                val = self.em.read_ptr(UARTDevice.UART_STATUS) & ~UARTDevice.UART_STAT_MASK_TFIFO_EMPTY
+                self.em.write_ptr(UARTDevice.UART_STATUS, val)
+            else:
+                val = self.em.read_ptr(UARTDevice.UART_STATUS) | UARTDevice.UART_STAT_MASK_TFIFO_EMPTY
+                self.em.write_ptr(UARTDevice.UART_STATUS, val)
+
+        if address == UARTDevice.UART_RFIFO:
+            self.gsc_ring_buffer_size -= 1
+            byte = self.send_data.pop(0)
+            self.em.write_ptr(UARTDevice.UART_RFIFO, byte)
+
+    def write(self, address, size, value):
+        if address == UARTDevice.UART_WFIFO:
+            self.recv_data.append(value & 0xff)
+        else:
+            self.em.write_ptr(address, value)
+
+    def has_tx(self):
+        return len(self.send_data) != 0
+
+    def put_tx(self, data):
+        self.send_data.extend(data)
+
+    def has_rx(self):
+        return len(self.recv_data) != 0
+
+    def get_rx(self):
+        ret = self.recv_data
+        self.recv_data = bytearray()
+        return ret
+    
+
+class TimerDevice(AmlogicDevice):
+    # https://github.com/hardkernel/u-boot/blob/154ddfc826e72c902232169b676b2a4e59c75171/board/hardkernel/odroidn2/firmware/timing.c#L456
+    BASE = 0xffd0f000
+    SIZE = 0x1000
+    NAME = "isa_timer"
+
+    TIMER_CURRENT_TIME = BASE + 0x188
+
+    def __init__(self, em):
+        super().__init__(em)
+
+    TIMER_CURRENT_TIME2 = BASE + 0x1C
+    TIMER_END_TIME = BASE + 0x38
+    TIMER_WAIT_TIME = BASE + 0x40
+
+    def read(self, address, size):
+        if address == TimerDevice.TIMER_CURRENT_TIME:
+            val = int(time.clock_gettime_ns(0)/1000) & 0xffffffff
+            self.em.write_ptr(TimerDevice.TIMER_CURRENT_TIME, val)
+
+    def write(self, address, size, data):
+        self.em.write_ptr(address, data)
+
+class GPIODevice(AmlogicDevice):
+    #define P_PIN_MUX_REG3		(*((volatile unsigned *)(0xff634400 + (0x2f << 2))))
+    #define P_PIN_MUX_REG4		(*((volatile unsigned *)(0xff634400 + (0x30 << 2))))
+    #define P_PIN_MUX_REG10		(*((volatile unsigned *)(0xff634400 + (0x36 << 2))))
+    BASE = 0xff634400
+    SIZE = 0x1000
+    NAME = "GPIO"
+
+    P_PIN_MUX_REG3		= BASE + (0x2f << 2)
+    P_PIN_MUX_REG4		= BASE + (0x30 << 2)
+    P_PIN_MUX_REG10		= BASE + (0x36 << 2)
+
+    def __init__(self, em):
+        super().__init__(em)
+        self.logger = setup_logger("GPIODevice")
+        self.logger.setLevel(logging.INFO)
+
+    def read(self, address, size):
+        gpio_offset = ((address - GPIODevice.BASE) // 4)
+        self.logger.debug(f'[{hex(self.em.pc)}]|Reading from GPIO {gpio_offset}')
+        
+
+    def write(self, address, size, value):
+        gpio_offset = ((address - GPIODevice.BASE) // 4)
+        self.logger.debug(f'[{hex(self.em.pc)}] | Writing to GPIO {gpio_offset} Address: {hex(address)} Value: {value} Size: {size}')
+        self.em.write_ptr(address, value)
+
+class USBPHYDevice(AmlogicDevice):
+    NAME = "USBPHY"
+    NAME2 = "usbphy21"
+    BASE = 0xff63a000
+    SIZE = 0x2000
+    
+    def __init__(self, em):
+        super().__init__(em)
+
+    def read(self, address, size):
+        pass
+
+    def write(self, address, size, value):
+        self.em.write_ptr(address, value)
+
+class USB1Device(AmlogicDevice):
+    NAME = "USB1"
+    NAME2 = "usbphy21"
+    BASE = 0xff400000
+    SIZE = 1 * MB
+    
+    def __init__(self, em):
+        super().__init__(em)
+        self.logger = setup_logger("USB1")
+        self.logger.setLevel(logging.DEBUG)
+
+    def read(self, address, size):
+        self.logger.debug(f"Address: {hex(address)} size:{hex(size)}")
+        if address == 0xff400040:
+            # self.em.write_ptr(address, 0x4f543fff)
+            # self.em.write_ptr(address, 1)
+            pass
+        elif address == 0xff400014 or address == 0xff400018 or address == 0xff400004:
+            # self.em.write_ptr(address, 1)
+            pass
+        
+
+    def write(self, address, size, value):
+        self.em.write_ptr(address, value)
+
+class WatchdogDevice(AmlogicDevice):
+    # TODO??
+    def __init__(self, em):
+        super().__init__(em)

source/bootrom_emulator/fuzz_output/01/cmdline

@@ -0,0 +1,3 @@
+python3
+fuzzer.py
+@@

source/bootrom_emulator/fuzz_output/01/fuzzer_setup

@@ -0,0 +1,9 @@
+# environment variables:
+AFL_CUSTOM_INFO_PROGRAM=python3
+AFL_CUSTOM_INFO_PROGRAM_ARGV=fuzzer.py @@
+AFL_CUSTOM_INFO_OUT=/fuzz/fuzz_output//01
+AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1
+AFL_TRY_AFFINITY=1
+AFL_SKIP_CPUFREQ=1
+# command line:
+'afl-fuzz' '-U' '-t' '5000' '-o' '/fuzz/fuzz_output/' '-i' '/fuzz/input/' '-M' '01' '--' 'python3' 'fuzzer.py' '@@'