diff --git a/Documentation/epicardium-guide.rst b/Documentation/epicardium-guide.rst index 7a549214442083b5a033b25ac84331fbda1a470f..b478645c3c01d6010e9540046b15d3cc834f0ef9 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 4f40a79a26b7eacb2735233fdf5581db82bc1afc..e0f18ac6e55b154e8c7a103533b2fe31480e1230 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 d5771751b5eadd34eeef9836e160d376a84fe441..8a3e14deaf25068b514ebda9e10e715e6a7f54cc 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 a4c61f49dfc9c03ebd79abc1340149428eda4f34..5be7bb06833f91b4051897bca46d2d36610481ad 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 1da823e22a1f7b62b7c20420d45d072b8f83ced5..f1ea1ebb19bcdc44e36dac0b06d9270b2ef2b868 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 3a8fcaba87314aa2b4b4350f6a34578431914765..21b0c15e205c5d65559108fb9997d74d18d4ab1a 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 -----------------------