From 9cd56629baabcda88f51d2e1ade9e959d0c906aa Mon Sep 17 00:00:00 2001
From: Rahix <rahix@rahix.de>
Date: Sun, 28 Jul 2019 00:27:12 +0200
Subject: [PATCH] docs: Update a few pieces of outdated information
- The bootloader will now write files immediately, you
no longer need to make sure you eject properly.
- *cardium is called l0dables and will definitely
happen!
- External flash is now available from Pycardium
Signed-off-by: Rahix <rahix@rahix.de>
---
Documentation/epicardium-guide.rst | 4 ++--
Documentation/epicardium/api.rst | 2 ++
Documentation/how-to-build.rst | 19 +++++++++++++++----
Documentation/how-to-flash.rst | 14 +++++---------
Documentation/overview.rst | 15 ++++++++-------
Documentation/pycardium-guide.rst | 10 +++-------
6 files changed, 35 insertions(+), 29 deletions(-)
diff --git a/Documentation/epicardium-guide.rst b/Documentation/epicardium-guide.rst
index 7a5492144..b478645c3 100644
--- a/Documentation/epicardium-guide.rst
+++ b/Documentation/epicardium-guide.rst
@@ -93,8 +93,8 @@ formatted, don't be afraid to do so.
.. warning::
- When writing you calls, **never** make assumptions about which FreeRTOS task
- you are running in. While all calls from core 1 will end up in the
+ When writing your calls, **never** make assumptions about which FreeRTOS
+ task you are running in. While all calls from core 1 will end up in the
"Dispatcher" task, other FreeRTOS tasks might might call your code at any
time just as well.
diff --git a/Documentation/epicardium/api.rst b/Documentation/epicardium/api.rst
index 4f40a79a2..e0f18ac6e 100644
--- a/Documentation/epicardium/api.rst
+++ b/Documentation/epicardium/api.rst
@@ -1,3 +1,5 @@
+.. _epicardium_api:
+
Epicardium API
==============
diff --git a/Documentation/how-to-build.rst b/Documentation/how-to-build.rst
index d5771751b..8a3e14dea 100644
--- a/Documentation/how-to-build.rst
+++ b/Documentation/how-to-build.rst
@@ -9,17 +9,28 @@ Dependencies
* **gcc**, **binutils** & **newlib** for ``arm-none-eabi``: The packages have
slightly different names on different distros.
- - Ubuntu / Debian: ``apt install gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi``
- - Arch: ``pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib``
+ - Ubuntu / Debian:
+
+ .. code-block:: shell-session
+
+ apt install gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi
+
+ - Arch:
+
+ .. code-block:: shell-session
+
+ pacman -S 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.
-* **ninja**: Needed for meson.
+* **ninja**: Needed for meson. If you install meson via *pip*, you need to
+ install ninja manually as well:
+
- Ubuntu / Debian: ``apt install ninja-build``
- Arch: ``pacman -S ninja``
* **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``.
- - Ubuntu / Debian: ``apt install 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
diff --git a/Documentation/how-to-flash.rst b/Documentation/how-to-flash.rst
index a4c61f49d..5be7bb068 100644
--- a/Documentation/how-to-flash.rst
+++ b/Documentation/how-to-flash.rst
@@ -18,22 +18,18 @@ If you did everything correctly, the bootloader will display:
.. code-block:: text
Bootloader
- Jul 12 2019
+ Jul 28 2019
USB activated.
- Waiting.
+ Ready.
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.
+The bootloader will then display ``Writing.`` in red while it is actually
+writing the file to external flash. Please wait until it displays ``Ready.``
+again before resetting card10 by pressing the power button again.
Flash Using Debugger
--------------------
diff --git a/Documentation/overview.rst b/Documentation/overview.rst
index 1da823e22..f1ea1ebb1 100644
--- a/Documentation/overview.rst
+++ b/Documentation/overview.rst
@@ -45,15 +45,16 @@ Pycardium is our MicroPython fork. Its purpose is to make it as easy as
possible to interact with card10. If you are interested in working on
Pycardium, take a look at the :ref:`pycardium_guide` guide.
-\*cardium
----------
-.. warning::
+L0dables
+--------
+Next to Pycardium, other bare-metal code can also run on core 1. For example,
+a Rustcardium or C-cardium. These l0dables must be compiled using our special
+linker script and should link against the api-caller library so they can
+interface with the :ref:`epicardium_api`.
- 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.
+.. todo::
-Next to Pycardium, other bare-metal code can also run on core 1. For example,
-a Rustcardium or Cccardium.
+ Provide more details how this works
Program Flow Diagram
--------------------
diff --git a/Documentation/pycardium-guide.rst b/Documentation/pycardium-guide.rst
index 3a8fcaba8..21b0c15e2 100644
--- a/Documentation/pycardium-guide.rst
+++ b/Documentation/pycardium-guide.rst
@@ -40,13 +40,9 @@ the output of
ls -lh build/pycardium/*@@frozen.c@*/
If your module contains some kind of big lookup-table or data-block, consider
-pushing that into external flash.
-
-.. todo::
-
- External flash is not yet accessible by Pycardium (ref `#11`_).
-
- .. _#11: https://git.card10.badge.events.ccc.de/card10/firmware/issues/11
+pushing that into external flash. You can then read the data using standard
+Python ``open()`` and if you need to decode it, use the ``ustruct`` or ``ujson``
+module.
Creating a new C module
-----------------------
--
GitLab