fix(docs): minor random updates

Documentation/debugger.rst

@@ -71,17 +71,25 @@ output:
    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.
+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. Specify ``-x gdbinit`` to use this 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
+   $ arm-none-eabi-gdb -x gdbinit build/hw-tests/hello-world/hello-world.elf
    ...
    (gdb)
 
+.. warning::
+   If you are used to use ``mon reset halt``, be aware that the card10 prototypes
+   do not connect the reset line to the debugger. OpenOCD is configured to only do
+   a soft-reset. This reset only resets the core, but not its peripherals.
+   Our custom ``reset`` sets a special bit in the CPU which also resets the
+   peripherals.
+
 You are now connected to card10 and ready to start debugging!  If card10 is
 still running, stop it using
 

Documentation/epicardium-guide.rst

@@ -29,6 +29,9 @@ like this:
 
 There are a number of rules you should follow when defining new calls:
 
+* Each API call need a unique call number (``API_ROCKET`` in this case).
+  There are no special rules regarding call numbers, choose any number not yet
+  in use.  Call numbers are ``uint32_t`` so you have plenty to choose from.
 * API calls have the prefix ``epic_`` which of course is just an abbreviation
   for *Epicardium*.
 * Only use types from the standard library or types defined (and documented!)
@@ -42,8 +45,6 @@ There are a number of rules you should follow when defining new calls:
   negative values denoting errors) if they are an imperative command or action
   (ref `Kernel Coding Style`_).  If you are reasonably sure your call cannot fail
   or an error is non-recoverable from core 1, return ``void``.
-* There are no special rules regarding call numbers, choose any number not yet
-  in use.  Call numbers are ``uint32_t`` so you have plenty to choose from.
 
 .. _Kernel Coding Style: https://www.kernel.org/doc/html/v5.2/process/coding-style.html#function-return-values-and-names
 
@@ -84,8 +85,9 @@ For the example above, the definition might look like this:
    }
 
 To keep code-style uniform across the project, please format your code using
-``./tools/code-style.sh``.  Note that this is not a definite style, however:
-If something looks better when manually formatted, don't be afraid to do so.
+``./tools/code-style.sh <filename>`` (requires ``clang-format``).  Note that
+this is not a definite style, however: If something looks better when manually
+formatted, don't be afraid to do so.
 
 .. warning::
 

Documentation/epicardium/overview.rst

@@ -2,7 +2,8 @@
 
 Overview
 ========
-Epicardium, the "main" firmware running on core 0, exposes a lot of
+Epicardium, the "main" firmware running on core 0 (more about our dual
+core design can be found :ref:`here <firmware_overview>`), 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.

Documentation/how-to-flash.rst

@@ -41,7 +41,7 @@ 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.
+   the debugger, make sure there is no ``card10.bin`` stored on the device.
    If there is, the bootloader will overwrite whatever you just flashed after
    reboot every time.
 
@@ -50,6 +50,16 @@ 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.
 
+
+.. info::
+   If OpenOCD was able to connect, but GDB gives you an
+   ``Error erasing flash with vFlashErase packet`` error, issue a ``reset``
+   command, quickly followed by a ``load`` command.
+
+   Reason: The Epicardium puts parts of the CPU to sleep and the debugging
+   interface is part of that. After a reset the bootloader starts up
+   and lets OpenOCD/GDB take control again.
+
 .. code-block:: text
 
    (gdb) load

Documentation/index.rst

@@ -24,14 +24,6 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    pycardium/color
    pycardium/leds
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Epicardium API
-
-   epicardium/overview
-   epicardium/api
-   epicardium-guide
-
 .. toctree::
    :maxdepth: 1
    :caption: Firmware
@@ -41,3 +33,13 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    how-to-flash
    debugger
    pycardium-guide
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Epicardium API
+
+   epicardium/overview
+   epicardium/api
+   epicardium-guide
+
+

Documentation/pycardium/leds.rst

@@ -3,7 +3,9 @@
 
 .. py:function:: leds.set(led, color)
 
-   Set one of the card10's RGB LEDs to a certain color::
+   Set one of the card10's RGB LEDs to a certain color.
+
+   Example which sets all LEDs on the top to red:::
 
       import leds, color
 

Documentation/pycardium/overview.rst

@@ -14,12 +14,16 @@ hacking!
    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.
+   This means, you can only interact with Python through the REPL console 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
 
+   In other words: It is currently not possible to execute Python code
+   from .py files on the filesystem. You have to test new modules using the
+   serial console.
+
 .. todo::
 
    Getting Started Guide for people interested in writing Python code.