Merge 'Documentation: get rid of jailbreak, document alternatives'

See merge request card10/firmware!294

Documentation/card10-cfg.rst

+.. _card10_cfg:
+
+card10.cfg
+==========
+
+Certain high-level settings can be configured using a filed named ``card10.cfg``.  It is accessed from the :ref:`usb_file_transfer` of the bootloader.  Once you are in this mode and have mounted the badge's flash device, you can either create or update a file named ``card10.cfg``.
+
+The file is in the well-known INI-style format, with one setting per line. For instance, if there were an option called ``answer_to_life``, you could set it by writing the following line in the ``card10.cfg`` file:
+
+.. code-block:: text
+
+   answer_to_life = 42
+
+Don't forget to unmount the filesystem before rebooting your badge after changing any setting.
+
+Syntax and Types
+----------------
+
+Lines that start with a ``#`` character are ignored.
+
+Any other line will have the overall syntax of ``option_name = option_value``, with spaces around the ``=`` character optional.
+
+Option names are internal to card10 and described below. Each option has a defined type.
+
+========= ===========
+Type name Description
+========= ===========
+Boolean   A true/false value. ``1`` or ``true`` is true, ``0`` or ``false`` is false. Example: ``foo = true``.
+String    An unquoted string value of maximum 20 bytes. Values longer than 20 bytes are trimmed. Example: ``foo = bar``.
+Integer   A signed 32-bit integer in base 10. Example: ``foo = 42`` or ``bar = -1337``.
+Float     A single-precision (32-bit) floating-point number in base 10. Example: ``foo = 13.37``.
+========= ===========
+
+Supported options
+-----------------
+
+=============== ========== ===========
+Option name     Type       Description
+=============== ========== ===========
+``execute_elf`` Boolean    Allow running of binary :ref:`l0dables`. These files can be nefarious, so this option is off by default.
+=============== ========== ===========

Documentation/how-to-build.rst

@@ -107,7 +107,6 @@ firmware features:
   info related to BLE.
 - ``-Ddebug_core1=true``: Enable the core 1 SWD lines which are exposed on the
   SAO connector.  Only use this if you have a debugger which is modified for core 1.
-- ``-Djailbreak_card10=true``: Enable execution of .elf l0dables on core 1.
 
 .. warning::
 

Documentation/how-to-flash.rst

@@ -5,27 +5,14 @@ method of flashing:
 
 Flash Without Debugger
 ----------------------
-If you do not have a debugger, you have to update the firmware using our
-bootloader.  To do so, you need to reboot card10 while keeping the buttom on
-the bottom right pressed.  Rebooting is done by either short pressing the power
-button (top left) while you have a working firmware, or turning the card10 off
-completely (by pressing the power button for 8 seconds) and then starting it again.
-
-.. image:: static/bootloader-buttons.png
-
-If you did everything correctly, the bootloader will display:
 
-.. code-block:: text
-
-   Bootloader
-   Jul 28 2019
-   USB activated.
-   Ready.
+If you do not have a debugger, you have to update the firmware using our
+bootloader by going into :ref:`usb_file_transfer`.
 
-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.
+After you get your badge into :ref:`usb_file_transfer`, you can 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.
 
 The bootloader will then display ``Writing.`` in red while it is actually
 writing the file to external flash.  Please wait until it displays ``Ready.``

Documentation/index.rst

@@ -45,6 +45,8 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    :caption: Firmware
 
    overview
+   card10-cfg
+   usb-file-transfer
    how-to-build
    how-to-flash
    debugger

Documentation/overview.rst

@@ -55,25 +55,28 @@ you should probably read the :ref:`epicardium_api_guide` guide.
 
 Pycardium
 ---------
+
 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.
 
-L0dables
+.. _l0dables:
+
+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`.
-Note: this feature is disabled by default and has to be enabled at build time.
-To do this, run ``bootstrap.sh`` with the option ``-Djailbreak_card10=true``
-and rebuild the firmware as described in :ref:`how_to_build`.
 
-.. _Rustcardium: https://git.card10.badge.events.ccc.de/astro/rust-card10
+Note: this feature is disabled by default and has to be enabled in :ref:`card10_cfg`. A :ref:`card10_cfg` file dropped into the :ref:`usb_file_transfer` of the badge containing ``execute_elf = true`` is enough.
+
+l0dables are currently built within the source tree of the main repository. See ``l0dables/blinky`` for an example of a hello-world-like program. Within those programs, you can access the :ref:`epicardium_api` to control the hardware and behaviour of the badge.
 
-.. todo::
+Once you have a built ELF file, you can drop it into the FAT filesystem of the flash (eg. via :ref:`usb_file_transfer`) and it will be available from the menu program of the badge.
 
-   Provide more details how this works
+.. _Rustcardium: https://git.card10.badge.events.ccc.de/astro/rust-card10
 
 Program Flow Diagram
 --------------------

Documentation/usb-file-transfer.rst

+.. _usb_file_transfer:
+
+USB File Transfer
+=================
+
+The card10 badge bootloader offers a USB Mass Storage mode to access its 8MB external flash.
+
+This flash contains a FAT32 filesystem and files on it will be visible to software running on the badge.
+
+Getting to the USB mode
+-----------------------
+
+To get to the USB mode, you will need to boot the badge while keeping the bottom-right button pressed.
+
+.. image:: static/bootloader-buttons.png
+
+1. If the badge is on, hold the top-left (power) button until the sleep screen appears, then release.
+2. Start holding the bottom-right button.
+3. Quickly press and release the top-left (power) button to turn the badge on.
+4. Your badge should now be in file transfer mode, and you can then release the bottom-right button.
+
+If you succesfully got into USB File Transfer mode, the screen will display its version and notify about the USB mode by displaying ``USB activated. Ready.``. If you connect the badge via USB to your computer, it should now detect 8MB of flash storage that you can mount in the same way as a pendrive.
+
+This pendrive can contain multiple files with different functions, some of them outlined here:
+
+============== ========
+File name      Function
+============== ========
+``card10.bin`` Firmware update file for the badge. If this file is present, the bootloader will perform an internal update to boot from this firmware file, then it will be deleted.
+``main.py``    This file contains the default `application` to be run on power on.
+``menu.py``    This file contains the default `menu` to be run when the power button is short-pressed.
+``*.py``       These are application files written in (Micro)Python that can be run from the menu.
+``*.elf``      These are :ref:`l0dables` that can be run from the menu.
+============== ========
+
+Updating files and rebooting
+----------------------------
+
+No matter which file you are writing, the bootloader will display a red ``Writing`` status message while write operations are pending. Please wait until it displays ``Ready`` again before resetting the badge by pressing the power button again.
+

tools/make-release.sh

@@ -52,11 +52,11 @@ fi
 release_dir="release-$version"
 mkdir "$release_dir"
 
-message "Building (non-jailbreak) release version ..."
+message "Building release version ..."
 ./bootstrap.sh
 ninja -C build/
 
-message "Creating (non-jailbreak) release archive ..."
+message "Creating release archive ..."
 mkdir "$release_dir/$release_name"
 cp -r -t "$release_dir/$release_name" preload/*
 cp build/pycardium/pycardium_epicardium.bin "$release_dir/$release_name/card10.bin"
@@ -66,20 +66,5 @@ cp build/pycardium/pycardium_epicardium.bin "$release_dir/$release_name/card10.b
 mkdir "$release_dir/elfs"
 cp -t "$release_dir/elfs" build/epicardium/epicardium.elf build/pycardium/pycardium.elf build/bootloader/bootloader.elf
 
-message "Building (jailbreak) release version ..."
-./bootstrap.sh -Djailbreak_card10=true
-ninja -C build/
-
-message "Creating (jailbreak) release archive ..."
-mkdir "$release_dir/$release_name-jailbreak"
-cp -r -t "$release_dir/$release_name-jailbreak" preload/*
-cp build/pycardium/pycardium_epicardium.bin "$release_dir/$release_name-jailbreak/card10.bin"
-( cd "$release_dir"; zip -r "$release_name-jailbreak"{.zip,}; )
-
-# Copy ELFs
-mkdir "$release_dir/elfs-jailbreak"
-cp -t "$release_dir/elfs-jailbreak" build/epicardium/epicardium.elf build/pycardium/pycardium.elf
-
 message "Done!"
-echo "Archive (non-jailbreak): $release_dir/$release_name.zip"
-echo "Archive (jailbreak):     $release_dir/$release_name-jailbreak.zip"
+echo "Archive: $release_dir/$release_name.zip"