From f059c9652725b2e96e7137579c2978561e48cc31 Mon Sep 17 00:00:00 2001
From: schneider <schneider@blinkenlichts.net>
Date: Sun, 14 Jul 2019 20:28:34 +0200
Subject: [PATCH] fix(docs): minor random updates
---
Documentation/debugger.rst | 18 +++++++++++++-----
Documentation/epicardium-guide.rst | 10 ++++++----
Documentation/epicardium/overview.rst | 3 ++-
Documentation/how-to-flash.rst | 12 +++++++++++-
Documentation/index.rst | 18 ++++++++++--------
Documentation/pycardium/leds.rst | 4 +++-
Documentation/pycardium/overview.rst | 8 ++++++--
.gdbinit => gdbinit | 0
8 files changed, 51 insertions(+), 22 deletions(-)
rename .gdbinit => gdbinit (100%)
diff --git a/Documentation/debugger.rst b/Documentation/debugger.rst
index 3f1f8bf3..e65b1949 100644
--- a/Documentation/debugger.rst
+++ b/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
diff --git a/Documentation/epicardium-guide.rst b/Documentation/epicardium-guide.rst
index 7073b8c1..fd6d54f1 100644
--- a/Documentation/epicardium-guide.rst
+++ b/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::
diff --git a/Documentation/epicardium/overview.rst b/Documentation/epicardium/overview.rst
index a63bcdac..a253a81f 100644
--- a/Documentation/epicardium/overview.rst
+++ b/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.
diff --git a/Documentation/how-to-flash.rst b/Documentation/how-to-flash.rst
index a0ebbef5..6a67277b 100644
--- a/Documentation/how-to-flash.rst
+++ b/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
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 2363aace..c2f4c57a 100644
--- a/Documentation/index.rst
+++ b/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
+
+
diff --git a/Documentation/pycardium/leds.rst b/Documentation/pycardium/leds.rst
index 17368dde..892fb07c 100644
--- a/Documentation/pycardium/leds.rst
+++ b/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
diff --git a/Documentation/pycardium/overview.rst b/Documentation/pycardium/overview.rst
index d011dbfc..62e4c25f 100644
--- a/Documentation/pycardium/overview.rst
+++ b/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.
diff --git a/.gdbinit b/gdbinit
similarity index 100%
rename from .gdbinit
rename to gdbinit
--
GitLab