zdsp: macros-based utilities

[josuah]

This adds a macro implementation of basic fixed-point operations.

The short-term goal was to implement this:

• drivers: video: sw_generator: Hue Saturation Brightness controls #79458

This could be interesting for implementing drivers that feature some light computation on scalars, for which a DSP library would be an overkill, and which might not be available in all platforms the driver covers.

This also helps with the current DSP libraries by being usable in const expressions, i.e. initialize tables of data:

#define COEF(x) SUBq7(Q7f(1.0), Q7f(x / 3.141592653589793))
const q7_t coefficients[] = { COEF(1.32), COEF(1.42), COEF(0.8), COEF(0.33), COEF(0.23) };

Or be intervleaved with the current ZDSP library

q15_t array[32];

[... ZDSP computations]

array[0] = Q15f(0.1);
array[31] = Q15f(0.1);

Unsolved questions:

• Does it make sense to have it there? Or to implement it that way?
• Is the naming suitable? i.e. Q15_ADD is more verbose.
• Should rounding be implemented?
• Should overflow be checked? I.e. on MAP_VALUE()

Todo:

• Add tests for the fixed-point library.
• Add documentation for the fixed-point library.

[bjarki-andreasen]

MAP may be a non optimal fit here, since maps map any input to any output, possibly in both directions, and even mapping 1 to many values :)

0 -> 100
3 -> 67
5 -> 45
7 -> (3, 5)
...

while scaling "linearly" maps an input to an output, you even hint at this in the brief :)

#define SCALE_VALUE(...)

would be better fitting IMO.

[josuah]

Absolutely, I could not find the best word and picked the same as Arduino library.

I am tempted to use SCALE(): as out of the 5 pages of search results, it shew-up 5 times with that same meaning (1 2 3 4 5)

[bjarki-andreasen]

Please add a unit test to validate the macros :)

[josuah]

Since it is to be included right next to a CMSIS-based library, it makes sense that it gives the exact same results...
I could try an unoptimized (or rather only compiler-optimized) zdsp back-end using it.
This would allow testing and check that the same results are obtained by running the same tests suite.

I am still working on the <zephyr/dsp/macros.h> own unit tests.
Grateful for the feedback!

[josuah]

Force-push:

• Add full documentation
• Add partial tests (WIP)

[josuah]

Force-push:

• Tests for Q7 that pass
• Doc fixes
• Removing the % operator as hard to define "remainder" of a float division

[github-actions]

This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time.

[josuah]

I still wish to build some C "fallback" back-end for ZDSP (i.e. for RISC-V) and other utilities, and would pick-up this PR again when having more time for it.