Commit f059c965 authored by schneider's avatar schneider
Browse files

fix(docs): minor random updates

parent 1b0ae33a
......@@ -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
......
......@@ -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::
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......@@ -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
......
......@@ -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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment