Skip to content
Snippets Groups Projects
Rahix's avatar
rahix authored
In the current firmware, different locking mechanisms a littered around
the code-base.  Among them are bare FreeRTOS mutexes and the hw-locks.
The callers for these often specify timeouts but don't make much effort
in A) picking robust values for the timeout and B) recovering gracefully
from a timeout happening.  Most of the time, we return -EBUSY to _Python
code_.  This is really really bad API design.  The firmware needs to
have enough integrity to ensure these situations can't ever occur.

To combat this, add a new locking primitive: The `struct mutex`.  The
intention is to replace all other locking and synchronization APIs with
this one.  This will provide one central place to debug any sort of
locking issues.

The `struct mutex` API is based on a few assumptions about locking.
Those are detailed in `Documentation/epicardium/mutex.rst`, which is
part of this commit.  The most important one is:

    Locking can **never** fail.

By requiring this to be true, we eliminate the need for drivers to
contain (often incorrect) logic for dealing with locking fails.  This
should drastically improve the stability of the firmware in regards to
lock-related bugs.

This commit does not introduce any functional changes yet.

Signed-off-by: default avatarRahix <rahix@rahix.de>
9a5a46cd
History

card10 firmware docs

Dear traveller,

these transcripts describe how you can write code for your card10. This includes the Python modules that are available but also documentation of the lower level firmware components.

If you want to write Python code for card10, you will want to take a look at the :ref:`Pycardium <pycardium_overview>` docs. If you are interested in writing applications in other languages, you'll probably want to interface with :ref:`Epicardium API <epicardium_api_overview>` directly.

Last but not least, if you want to start hacking the lower-level firmware, the :ref:`Firmware <firmware_overview>` section of these docs is a good starting place.

Indices and tables

  • :ref:`genindex`
  • :ref:`modindex`
  • :ref:`search`