doc: Add intro and boot process docs

doc/build.sh

@@ -1,7 +1,9 @@
 cat <<EOF > tmp_dockerfile
 FROM sphinxdoc/sphinx
-RUN apt-get update -y
-RUN apt-get install -y doxygen
+RUN apt-get update -y && \
+ mkdir -p /usr/share/man/man1/ && \
+ apt-get install -y default-jre && \
+ apt-get install -y doxygen plantuml
 COPY doc/requirements.txt /requirements.txt
 RUN pip3 install -r /requirements.txt
 EOF

doc/source/api-ref/plat.rst

@@ -0,0 +1,28 @@
+:mod:`plat` --- Platform API
+============================
+
+.. module:: plat
+   :synopsis: Platform API
+
+The platform API constitutes the minimum and mandatory functions each platform
+must provide.
+
+The 'plat_init' function in each platform is expected to perform the follwing basic initialization:
+
+- Initialize a watchdog
+- Configure the systick
+- Load and decode system boot reason
+- Initialize debug console
+- Configure the MMU
+
+The 'plat_init' and 'plat_board_init' functions are called early during boot,
+se :ref:`Boot Process` for more details.
+
+----------------------------------------------
+
+Source code: :github-blob:`include/pb/plat.h`
+
+----------------------------------------------
+
+.. doxygenfile:: include/pb/plat.h
+   :project: pb

doc/source/boot_process.rst

@@ -1,12 +1,25 @@
-Boot process
+Boot Process
 ============
 
-.. uml::
+This document describes the main boot flow. The boot process is modular
+and can support many different use cases.
 
-   @startuml
-   user -> (use PlantUML)
+.. uml::
 
-   note left of user
-      Hello!
-   end note
-   @enduml
+    start
+    :Power on reset;
+    :Arch init;
+    :Plat init;
+    :Board init;
+    if (Board init succesful) then (yes)
+        :Boot init;
+        :Board early boot init;
+        if (Board early succesful) then (yes)
+            :asdf;
+        else (no)
+            :Initialize command mode;
+        endif
+    else (no)
+        :Initialize command mode;
+    endif
+    stop

doc/source/conf.py

@@ -59,6 +59,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinxcontrib.plantuml",
+    "sphinx.ext.autosectionlabel",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/index.rst

@@ -1,15 +1,8 @@
-.. punchboot documentation master file, created by
-   sphinx-quickstart on Mon Apr 20 19:08:11 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to punchboot's documentation!
 =====================================
 
 .. toctree::
-   :maxdepth: 2
-   :titlesonly:
-   :hidden:
+   :maxdepth: 3
 
    introduction
    getting_started

doc/source/introduction.rst

@@ -1,4 +1,45 @@
 Introduction
 ============
 
-Welcome to the punchboot documentation.
+Punchboot is a booloader for embedded systems. It has a strong emphasis on
+security and compactness.
+
+The following architectures are supported:
+
+- Armv7a
+- Armv8a
+
+The following SoC's/platform's are supported:
+
+- nxp imx6ul
+- nxp imx8x
+- nxp imx8m
+- qemu virt
+
+License
+-------
+
+Punchboot is premissivily licensed under the BSD 3 licens.
+
+Distinguishing Features
+-----------------------
+
+**Only supports signed payloads**
+    Punchboot only supports signed payloads which reduces the risk for configuration
+    errors and reduces the logic in the boot code.
+
+**Highly configurable**
+    Most features can be enabled or disabled through the Kconfig interface
+
+**Host tooling**
+    Punchboot-tools provides a set of tools and libraries for interacting
+    with the bootloader
+
+    * Punchboot CLI and a C library
+    * Python wrapper
+
+    These can easly be extended to support board/production specific commands.
+
+**Optimized for speed**
+    Most drivers, in particular block device drivers and hashing accelerators
+    use DMA to maximize transfer speed.

include/pb/plat.h

@@ -1,4 +1,6 @@
 /**
+ * \file plat.h
+ *
  * Punch BOOT
  *
  * Copyright (C) 2020 Jonas Blixt <jonpe960@gmail.com>
@@ -13,27 +15,30 @@
 #include <pb/pb.h>
 #include <pb-tools/wire.h>
 
-/* Platform API Calls */
-
 /**
  * Initialize the platform
  *
  * @return PB_OK on success or a negative number
- **/
+ */
 int plat_init(void);
 
+/**
+ * Initialize the board
+ *
+ * @return PB_OK on success or a negative number
+ */
 int plat_board_init(void);
 
 /**
  * Platform specific reset function
- **/
+ */
 void plat_reset(void);
 
 /**
  * Read platform/system tick
  *
  * @return current micro second tick
- **/
+ */
 unsigned int plat_get_us_tick(void);
 
 /**
@@ -45,18 +50,25 @@ void plat_wdog_kick(void);
  * Returns a platform specific boot reason as an integer.
  *
  * @return >= 0 for valid boot reasons or a negative number on error
- *
- **/
+ */
 int plat_boot_reason(void);
 
 /**
  * Returns a platform specific boot reason as an string
  *
  * @return Boot reason string or ""
- *
- **/
+ */
 const char* plat_boot_reason_str(void);
 
+/**
+ * Platform / SoC Unique data. This function is called by the
+ * device_uuid module to generate a device unique identifer
+ *
+ * @param[out] output Unique data output
+ * @param[inout] length Size of output buffer and result length
+ *
+ * @return PB_OK on success or a negative number
+ */
 int plat_get_unique_id(uint8_t *output, size_t *length);
 
 #endif  // INCLUDE_PB_PLAT_H_