ghf/fructose

🌽 Simple sugar for microcontrollers in unapologetic C++17 🍯

fructose's Issues

Add fixed-capacity circular buffer

Add a data structure primitive that performs non-blocking FIFO access to a fixed circular buffer.

To avoid template instantiation code size overhead, this should provide raw byte access (or perhaps equal-sized chunks) as views into the internal storage.

This will be used as the backing buffer for the dispatch queue (#5) and data queue (#8), which are multiple-producer, single-consumer abstractions in this system. As such, it needs to be safe to write from privileged interrupts, DMA, and regular threads. To enable multiple producers, writers write in two stages:

1. Attempt to allocate storage for the element to be written. This will move a writer-visible pointer that reduces the empty space of the buffer. This can fail if there's not enough space remaining.
2. Commit the element to make it visible for reading (move a reader-visible pointer).

There's no requirement that the caller had actually written any data to the buffer between these two calls, nor will the buffer perform any implicit copying. This allows for e.g. DMA copying.

The dispatch queue use case requires that writers be able to allocate a contiguous range of bytes, so it needs to return both the desired buffer that was allocated and if the writer pointer had wrapped, the "garbage" bytes that were allocated at the end of the circular buffer.

So the final interface might look something like:

• AllocateBack
• AllocateContiguousBack
• CommitBack
• PeekFront
• PopFront

Logging API

Create a logging API that can defer the formatting and transmission of logs. It should have all the usual features:

• levels
• file name and line number
• tags?

Asynchronous dispatch loop

Create a dispatch queue that executes tasks by order of their deadlines.

Add assertions to [base] utilities

When #1 is usable, add runtime checks to all the integer math utilities.

Runtime checks

The code needs a runtime condition-checking facility like assert or CHECK/DCHECK. Requirements for the assert call:

1. Have at least two compile-time levels (e.g. one for debug builds and one that's always built).
2. Configurable such that it can make no library calls.
3. Allow a custom message to be attached to check failures (but configurable output w.r.t. requirement 2).

Would be nice:

1. Ergonomic, short invocation for very simple conditions e.g. CHECK(pointer);
2. Failure message can formatted. The formatter/output needs to be configurable and allow lossless forwarding of formatter arguments (e.g. not through varargs). Formatting should be performed lazily (only when check is enabled and fails).
3. Does not raise "unused variable" warnings when disabled.
4. Allows for "breaking" any attached debugger upon failure.

Looking at third party libraries:

• https://github.com/foonathan/debug_assert has DEBUG_ASSERT(1 + 1 == 2, my_module{}); as the most basic invocation (the tag looks to be bending over backwards to avoid relying on macro definitions), which is pretty verbose, and it also always calls std::abort, which might be OK but isn't ideal.
• https://github.com/emilk/loguru looks like like relies on way too many host calls for output, timing, etc. I'd probably be OK with using it directly in host-side code.
• https://github.com/wc-duck/dbgtools/blob/master/include/dbgtools/assert.h looks to be the closest I've seen, but it pushes the formatter arguments through varargs and defines ASSERT and VERIFY in macro name space.
• https://github.com/gpakosz/PPK_ASSERT looks configurable enough to do the job, except for varargs again. The default handler is pretty excessive, with the asking for user feedback, per-assertion disabling, exceptions, etc.

Configuration variable for host build

So far, all code has been written to run on a host AMD64 workstation under unit testing and not for a microcontroller target.

Any code that uses this assumption should be marked by a switch somewhere so that this is behavior that isn't painful to strip out when porting. This might just be a preprocessor macro, or it might be combined with selecting which source files get built, but it should be visible to the code.

Visibility to the code is important for behaviors that rely on host libraries and/or feature, e.g. where logs should be output by default.

Refactor MapRange

MapRange, the [base] utility for linearly mapping ranges, usually has fixed input and output ranges and deadband. That means that its repeated invocation performs a lot of redundant work and is not too readable (because it requires six arguments).

Split the API into a precompute step that creates a "range mapper" and an evaluate step that does the mapping. The construction of the mapper should hoist the precompute math like making the scaling ratio (including a ratio simplification using std::gcd), and should be constexpr friendly so that the mapper can be created at compile time if the scaling is already known.

Additionally, it might be nice to split the input and output types so the invocation requires less casting. This might lead to additional enhancements like supporting floating-point types.

Finally, range mapping needs tests.

Add FIFO data queue

Add a queue of equal-sized objects that allows non-blocking multi-producer, single-consumer FIFO access to underlying fixed storage.

Writing (pushing) new objects can be performed by regular threads, privileged interrupts, and DMA access. An example writer that needs to be supported would be an ADC sampling group that writes the same series of samples repeatedly into a fixed circular buffer, raising an interrupt with each series. The interrupt does not write data to the buffer, but it does tell the queue that data has been written.

This needs to support element types that are not power-of-two sizes, which probably constrains the byte size of the buffer to be an integer multiple of element size.

Time and duration representations

Need to define types for representing points in time and durations of time. Options:

• Custom route like Fructose v1
• std::chrono route, which involves defining a Clock and probably new types for time_point and duration (to use 32-bit types). The helpers might be reusable for constants.