doc: Write lots of docs

Signed-off-by: Rahix <rahix@rahix.de>

Documentation/debugger.rst

+.. _debugger:
+
+Debugger
+========
+If you have one of our debuggers for card10, this page details how you can use
+it.  The debugger looks like either one in the following pictures:
+
+.. todo::
+
+   Debugger Picture
+
+OpenOCD
+-------
+For debugging card10, you need our `own fork`_ of OpenOCD.  It contains a patch
+which allows flashing both flash-banks instead of just one.  Install it using
+the following commands:
+
+.. _own fork: https://git.card10.badge.events.ccc.de/card10/openocd
+
+.. code-block:: shell-session
+
+   $ git clone https://git.card10.badge.events.ccc.de/card10/openocd.git
+   $ cd openocd
+
+   $ git submodule update --init
+   $ ./bootstrap
+   $ ./configure --disable-werror
+   $ make -j8
+
+Make sure ``CMSIS-DAP Compliant Debugger`` is set to **yes (auto)** after
+running ``./configure`` (if it is not, you might need to install libusb).  If
+you get errors making the documentation you can ``touch doc/openocd.info`` to
+skip it and continue with ``make``.
+
+Please run ``make install`` after removing any already installed OpenOCD
+version. Otherwise please always specify the full path to OpenOCD (the binary
+is under ``src/openocd``).
+
+GDB (``arm-none-eabi-gdb``)
+---------------------------
+Apart from OpenOCD you also need ``arm-none-eabi-gdb``.  You should install
+that package from your distros repositories:
+
+* Ubuntu: ``gdb-arm-none-eabi``
+* Arch: ``arm-none-eabi-gdb``
+
+Debugging
+---------
+First of all, you need to connect your debugger and card10.  There are three
+connections that you need (take a look at the above diagram for more info):
+
+* ``HDK``: This connection provides debugging (SWD) and UART.
+* ``DEV``: This connection provides power (battery charger) and the native USB
+  connection (bootloader).
+* ``USB-C``: Connect the proved USB-C cable with the side which has the blue
+  dot, so the blue dots have the same side.
+
+Run OpenOCD from the ``openocd/scripts`` directory in the firmware repository.
+Call it as ``openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg``.  If
+the debugger and card10 are connected correctly, you should see the following
+output:
+
+.. code-block:: shell-session
+
+   $ openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg
+   Info : CMSIS-DAP: SWD  Supported
+   Info : CMSIS-DAP: FW Version = 1.0
+   Info : CMSIS-DAP: Interface Initialised (SWD)
+   Info : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
+   Info : CMSIS-DAP: Interface ready
+   Info : clock speed 2000 kHz
+   Info : SWD DPIDR 0x2ba01477
+   Info : max32xxx.cpu: hardware has 6 breakpoints, 4 watchpoints
+   Info : Listening on port 3333 for gdb connections
+
+Next, start *gdb* in parallel and connect it to OpenOCD.  You can do this easily
+if you run gdb from the firmware repository root where we have provided a
+``.gdbinit`` file.  Apart from automatically connecting to OpenOCD, this script
+file also defines a ``reset`` command to soft-reset card10.
+
+.. code-block:: shell-session
+
+   $ arm-none-eabi-gdb build/hw-tests/hello-world/hello-world.elf
+   ...
+   (gdb)
+
+You are now connected to card10 and ready to start debugging!  If card10 is
+still running, stop it using
+
+.. code-block:: text
+
+   (gdb) mon reset halt
+
+Following that, you can debug as you would normally.

Documentation/epicardium/api.rst

@@ -5,8 +5,17 @@ Epicardium API
 
    .. warning::
 
-      This version of the documentation was built without
-      `Hawkmoth <https://github.com/jnikula/hawkmoth>`_ available.  This means,
-      no documentation for the Epicardium API was generated.
+      This version of the documentation was built without `Hawkmoth`_ working
+      (most likely python3-clang was not installed).  This means, no
+      documentation for the Epicardium API was generated.
+
+   .. _Hawkmoth: https://github.com/jnikula/hawkmoth
+
+This page details all available *Epicardium API* functions.  All these
+functions are defined in
+
+.. code-block:: c++
+
+   #include "epicardium.h"
 
 .. c:autodoc:: epicardium/epicardium.h

Documentation/epicardium/intro.rst

-Epicardium Intro
-================
-Epicardium is the main component of the firmware.  It runs on core0 and is
-based on FreeRTOS.  Epicardium provides an API to a payload running on the
-other core which exposes most functionality.
-
-API Design
-----------
-.. note::
-
-   This is the current design.  We might adjust it in the future to allow for
-   more performance in cases where this approach is too slow.
-
-The API is strictly synchroneous.  This means, an API call looks exactly the
-same as calling any other function.  Internally, the call will wake up
-Epicardium and dispatch the call.  Once the call has finished, it will return a
-result.
-
-
-API Conventions
----------------
-The API functions follow the kernel convention of either returning a boolean if
-the function is a predicate or returning a success integer (with negative
-values denoting errors) if it is an action or imperative command.  To quote:
-
-      **16) Function return values and names**
-
-      Functions can return values of many different kinds, and one of the
-      most common is a value indicating whether the function succeeded or
-      failed.  Such a value can be represented as an error-code integer
-      (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
-      non-zero = success).
-
-      Mixing up these two sorts of representations is a fertile source of
-      difficult-to-find bugs.  If the C language included a strong distinction
-      between integers and booleans then the compiler would find these mistakes
-      for us... but it doesn't.  To help prevent such bugs, always follow this
-      convention:
-
-      .. code-block:: text
-
-              If the name of a function is an action or an imperative command,
-              the function should return an error-code integer.  If the name
-              is a predicate, the function should return a "succeeded" boolean.
-
-      For example, ``add work`` is a command, and the add_work() function returns 0
-      for success or -EBUSY for failure.  In the same way, ``PCI device present`` is
-      a predicate, and the pci_dev_present() function returns 1 if it succeeds in
-      finding a matching device or 0 if it doesn't.

Documentation/epicardium/overview.rst

+Overview
+========
+Epicardium, the "main" firmware running on core 0, exposes a lot of
+functionality to user-code via the so-called *Epicardium API*.  This API
+consists of a number of calls that can be issued by core 1 using an
+auto-generated library.
+
+API Design
+----------
+.. note::
+
+   This is the current design.  We might adjust it in the future to allow for
+   more performance in cases where this approach is too slow.  This will most
+   likely be the addition of some form of asynchroneous calls.
+
+The API is strictly synchroneous.  This means, an API call looks exactly the
+same as calling any other function.  Internally, the call will wake up
+Epicardium and there the call will be dispatched.  It will then block until
+Epicardium finished executing the call and return whatever the call has as a
+return value.  In code:
+
+.. code-block:: c++
+
+   #include "epicardium.h"
+
+   int main(void)
+   {
+   	/* ... */
+
+   	/* Call the API to write to UART. */
+   	epic_uart_write_str("Hello from core 1!\r\n", 20);
+
+   	/*
+   	 * Call the API to receive a byte from UART.
+   	 * This will block until at least one character is received.
+   	 */
+   	char chr = epic_uart_read_chr();
+
+   	/* ... */
+   }
+
+Internals
+---------
+In most cases, you won't need to care about the actual implementation of the
+API as it is well hidden inside the auto-generated library.  If you want to
+know anyway, here is a rough overview:
+
+The current design is based around a shared memory region, the semaphore
+peripherals provided by MAX32666, and the SEV/WFE mechanism.  When issuing a
+call, this is what happens:
+
+.. image:: ../static/synchroneous-api-call.svg
+
+There is one important thing to note here:  Right now, the API is only ever
+polled for new calls from Epicardium inside the idle task.  This means, that if
+it is busy with other things, the API will have the least priority.  For now,
+this has not been an issue as Epicardium is sleeping most of the time anyway.
+If it becomes one in the future we will have to introduce another
+synchronization point.

Documentation/how-to-build.rst

+How To Build
+============
+If you just want to write MicroPython code for card10, you probably **won't**
+need to build the firmware yourself.  This page is for people who want to work
+on the underlying firmware itself.
+
+Dependencies
+------------
+* **gcc**, **binutils** & **newlib** for ``arm-none-eabi``:  The packages have
+  slightly different names on different distros.
+
+  - Ubuntu: ``gcc-arm-none-eabi``, ``binutils-arm-none-eabi``, ``libnewlib-arm-none-eabi``
+  - Arch: ``arm-none-eabi-gcc``, ``arm-none-eabi-binutils``, ``arm-none-eabi-newlib``
+  - Alternative: Download `ARM's GNU toolchain`_.  **TODO**
+* **python3**:  For meson and various scripts needed for building.
+* **meson** (>0.43.0):  Unfortunately most distros only have very old versions
+  of meson in their repositories.  Instead, you'll probably save yourself a lot
+  of headaches by installing meson from ``pip3 install --user meson``.
+* **python3-crc16**: Install with ``pip3 install --user crc16``.
+
+.. _ARM's GNU toolchain: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
+
+Building
+--------
+Build using the following two commands:
+
+.. code-block:: shell-session
+
+   $ ./bootstrap.sh
+   $ ninja -C build/
+
+``bootstrap.sh`` initializes git submodules and runs *meson*.  Afterwards you
+can build with *ninja*.
+
+.. note::
+
+   Our build-system contains a few workarounds around short-comings in meson.
+   These workarounds might break on some setups which we did not yet test.  If
+   this is the case for you, please open an issue in our `issue tracker`_!
+
+.. _issue tracker: https://git.card10.badge.events.ccc.de/card10/firmware/issues
+
+If ninja succeeds, the binaries are in ``build/``.  They are available in two
+formats:  As an ``.elf`` which can be flashed using a debugger and as a
+``.bin`` which can be loaded using the provided bootloader.  Here is a list of
+the binaries:
+
+- ``build/bootloader/bootloader.elf``: Our bootloader.  It should already be on
+  your card10.  The bootloader can only be flashed using a debugger.
+- ``build/pycardium/pycardium_epicardium.bin``: The entire firmware in one ``.bin``.
+- ``build/epicardium/epicardium.elf``: The core 0 part of the firmware, called Epicardium.
+- ``build/pycardium/pycardium.elf``: Our MicroPython port, the core 1 part of the firmware.

Documentation/how-to-flash.rst

+How To Flash
+============
+Depending on whether you have a debugger or not, you have to use a different
+method of flashing:
+
+Flash Without Debugger
+----------------------
+If you do not have a debugger, you have to update the firmware using our
+bootloader.  To do so, you need to reboot card10 while keeping the buttom on
+the bottom right pressed.  Rebooting is done by either short pressing the power
+button (top left) while you have a working firmware, or turning the card10 off
+completely (by pressing the power button for 8 seconds) and then starting it again.
+
+.. todo::
+
+   Image showing the location of the buttons
+
+If you did everything correctly, the bootloader will display:
+
+.. code-block:: text
+
+   Bootloader
+   Jul 12 2019
+   USB activated.
+    Waiting.
+
+On your host, you should now see an 8MB flash-device appear.  You can now drop
+the firmware's ``.bin`` (from ``build/pycardium/pycardium_epicardium.bin`` in
+most cases) into this flash-storage.  You **must** call the file ``card10.bin``
+for the bootloader to use it.
+
+Afterwards **eject** the flash device and reboot card10.  You should now see
+your new firmware boot up!
+
+.. warning::
+
+   **You must EJECT the flash device!**  ``umount`` & ``sync`` is **not**
+   enough and will result in the bootloader not loading the new binary.
+
+Flash Using Debugger
+--------------------
+
+.. warning::
+
+   With the current version of the bootloader, before attempting to flash using
+   the debugger, make sure there is not ``card10.bin`` stored on the device.
+   If there is, the bootloader will overwrite whatever you just flashed after
+   reboot every time.
+
+First, setup everything as explained on the :ref:`debugger` page.  Following
+that and after connecting to card10, you can flash your binary using the
+``load`` command.  After loading, you need to use ``reset`` to reboot card10
+using your new firmware.
+
+.. code-block:: text
+
+   (gdb) load
+   Loading section .text, size 0x12514 lma 0x10010000
+   Loading section .ARM.exidx, size 0x8 lma 0x10022514
+   Loading section .data, size 0x8d8 lma 0x1002251c
+   Start address 0x10012160, load size 77300
+   Transfer rate: 19 KB/sec, 11042 bytes/write.
+   (gdb)

Documentation/index.rst

 card10 firmware docs
 ====================
 
-This is the API documentation for card10's default firmware.
+**Dear traveller,**
 
-Overview
---------
+these transcripts describe how you can write code for your card10.  This
+includes the Python modules that are available but also documentation of the
+lower level firmware components.
 
-The design roughly looks like this:
+If you want to write Python code for card10, you will want to take a look at
+the :ref:`pycardium_index` docs.  If you are interested in writing applications
+in other languages, you'll probably want to interface with
+:ref:`epicardium_api_index` directly.
 
-.. image:: static/overview.svg
+Last but not least, if you want to start hacking the lower-level firmware, the
+:ref:`firmware_index` section of these docs is a good starting place.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Epicardium
-
-   epicardium/intro
-   epicardium/api
 
+.. _pycardium_index:
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Pycardium
 
-   pycardium/intro
+   pycardium/overview
    pycardium/color
    pycardium/leds
+
+.. _epicardium_api_index:
+.. toctree::
+   :maxdepth: 1
+   :caption: Epicardium API
+
+   epicardium/overview
+   epicardium/api
+
+.. _firmware_index:
+.. toctree::
+   :maxdepth: 1
+   :caption: Firmware
+
+   overview
+   how-to-build
+   how-to-flash
+   debugger

Documentation/overview.rst

+Overview
+========
+To make the most of card10's dual-core processor, its firmware will have been
+divided into two parts: The "main" firmware running on core 0 which will have
+been called *Epicardium* and the "user-code" running on core 1.  In most cases
+this will have been *Pycardium*, our MicroPython port.
+
+.. image:: ./static/overview.svg
+
+Epicardium
+----------
+Epicardium is based on `FreeRTOS`_.  There are a number of tasks that will have
+been keeping card10 running.  These are:
+
+* **Dispatcher**:  The dispatcher task handles API calls from core 1.
+* **PMIC**:  The power manager task checks the battery level and other interesting
+  statistics that can be gathered from our power manager IC (MAX77650).
+* **Serial**:  Handles serial communication via *UART*, *CDC ACM* and possibly
+  Bluetooth.
+
+.. todo::
+
+   The following tasks have not yet been implemented/are currently in the works:
+
+   - **Bluetooth**: The bluetooth stack
+   - **Payload Controller**: Control what is running on core 1
+
+.. _FreeRTOS: https://www.freertos.org/
+
+Pycardium
+---------
+Pycardium is our MicroPython fork.  Its purpose is to make it as easy as
+possible to interact with card10.
+
+\*cardium
+---------
+.. warning::
+
+   We have not yet been able to determine if card10 will have had the abilities
+   described in this section.  And if yes, how they will have been implemented.
+
+Next to Pycardium, other bare-metal code can also run on core 1.  For example,
+a Rustcardium or Cccardium.

Documentation/pycardium/intro.rst

-Pycardium Intro
-===============
-Pycardium is a core1 payload based on MicroPython.  It can interface with
-card10 using the Epicardium API, which is wrapped in a bunch of python modules.
-Pycardium also contains a number of Python stdlib modules.  To see the full
-list, type:
-
-.. code-block:: python
-
-   help("modules")
-
-
-The following pages detail card10 specific modules.

Documentation/pycardium/overview.rst

+Overview
+========
+Pycardium is what we call our MicroPython port for card10.  For the most part,
+it will behave like a normal MicroPython, enhanced by a few modules to
+interface with card10's hardware.  We have also included modules from Python's
+standard library so you have lots of familiar functionality at hand to start
+hacking!
+
+.. note::
+
+   Right now, MicroPython is only available via the serial console.  card10
+   makes its console available as a CDC ACM device via USB or, if you have a
+   debugger, on the debugging serial port.
+
+   This means, you can only interact with Python through a REPL for now.
+   However, this will soon change, once `#10`_ and `#11`_ are implemented.
+
+   .. _#10: https://git.card10.badge.events.ccc.de/card10/firmware/issues/10
+   .. _#11: https://git.card10.badge.events.ccc.de/card10/firmware/issues/11
+
+.. todo::
+
+   Getting Started Guide for people interested in writing Python code.

Documentation/static/overview.svg

@@ -148,15 +148,15 @@
      inkscape:pageopacity="0"
      inkscape:pageshadow="2"
      inkscape:zoom="1.4"
-     inkscape:cx="374.3184"
+     inkscape:cx="254.67554"
      inkscape:cy="190.35742"
      inkscape:document-units="mm"
-     inkscape:current-layer="g6159"
+     inkscape:current-layer="g8661"
      showgrid="false"
      inkscape:pagecheckerboard="true"
      inkscape:window-width="1920"
      inkscape:window-height="1020"
-     inkscape:window-x="1920"
+     inkscape:window-x="0"
      inkscape:window-y="0"
      inkscape:window-maximized="1"
      fit-margin-top="0"
@@ -301,20 +301,20 @@
              xlink:title="Epicardium">
             <text
                xml:space="preserve"
-               style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#0000ee;fill-opacity:1;stroke:none;stroke-width:0.26458332;"
+               style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#0000ee;fill-opacity:1;stroke:none;stroke-width:0.26458332"
                x="40.307911"
                y="111.83552"
                id="text6791"><tspan
                  sodipodi:role="line"
                  x="40.307911"
                  y="111.83552"
-                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.26458332;fill:#0000ee;fill-opacity:1;"
-                 id="tspan6793">epicardium</tspan><tspan
+                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;font-family:monospace;-inkscape-font-specification:monospace;fill:#0000ee;fill-opacity:1;stroke-width:0.26458332"
+                 id="tspan6793">Epicardium</tspan><tspan
                  sodipodi:role="line"
                  x="40.307911"
                  y="119.77302"
-                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.58611107px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.26458332;fill:#0000ee;fill-opacity:1;"
-                 id="tspan1028">(core0)</tspan></text>
+                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.58611107px;font-family:monospace;-inkscape-font-specification:monospace;fill:#0000ee;fill-opacity:1;stroke-width:0.26458332"
+                 id="tspan1028">(core 0)</tspan></text>
           </a>
         </g>
         <g
@@ -393,7 +393,7 @@
              xlink:title="Pycardium">
             <text
                xml:space="preserve"
-               style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#0000ee;fill-opacity:1;stroke:none;stroke-width:0.26458332;"
+               style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#0000ee;fill-opacity:1;stroke:none;stroke-width:0.26458332"
                x="147.18329"
                y="111.80997"
                id="text6799"><tspan
@@ -401,12 +401,12 @@
                  id="tspan6797"
                  x="147.18329"
                  y="111.80997"
-                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.26458332;fill:#0000ee;fill-opacity:1;">pycardium</tspan><tspan
+                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.3499999px;font-family:monospace;-inkscape-font-specification:monospace;fill:#0000ee;fill-opacity:1;stroke-width:0.26458332">Pycardium</tspan><tspan
                  sodipodi:role="line"
                  x="147.18329"
                  y="119.74747"
-                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.58611107px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.26458332;fill:#0000ee;fill-opacity:1;"
-                 id="tspan1032">(core1)</tspan></text>
+                 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.58611107px;font-family:monospace;-inkscape-font-specification:monospace;fill:#0000ee;fill-opacity:1;stroke-width:0.26458332"
+                 id="tspan1032">(core 1)</tspan></text>
           </a>
         </g>
       </g>
@@ -420,7 +420,7 @@
            style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46666622px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.26458332"
            y="84.910851"
            x="104.47012"
-           sodipodi:role="line">max32665</tspan></text>
+           sodipodi:role="line">MAX32666</tspan></text>
       <path
          style="display:inline;fill:none;stroke:#b7b7b7;stroke-width:3.5999999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleOutS)"
          d="M 19.222455,122.34974 H 10.72299 v 46.42197 h 23.044261"
@@ -456,6 +456,17 @@
              x="63.567005"
              sodipodi:role="line">Core</tspan></text>
       </g>
+      <text
+         xml:space="preserve"
+         style="font-style:normal;font-weight:normal;font-size:3.52777767px;line-height:1.25;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332"
+         x="161.65434"
+         y="102.35806"
+         id="text4680"><tspan
+           sodipodi:role="line"
+           id="tspan4678"
+           x="162.2159"
+           y="102.35806"
+           style="stroke-width:0.26458332"> </tspan></text>
     </g>
   </g>
 </svg>