[Discuss-gnuradio] volk work update - automatic alignment and custom dispatchers

[Josh Blum]

Greetings VOLK enthusiasts,

The last remaining frontier for VOLK development: Dealing automatically
with buffer alignment, head cases, and tail cases. Here is my attempt...
All work can be found on the volk_work branch of my github
https://github.com/guruofquality/gnuradio/tree/volk_work

---------------------------------------------------------------------------
-- Combining unaligned and aligned kernels
---------------------------------------------------------------------------
So, A VOLK kernel is a computational function with one or more
implementations of this function. Each implementation has a unique name
and requirements for SIMD instructions sets and alignment. Currently,
most VOLK kernels are actually split into two kernels, one called
aligned and the other called unaligned... based on the ability for an
implementation to handle randomly aligned pointers, or not.

One of the things this branch does is combine those two separate kernels
into one. What was bar_u.h and bar_a.h becomes bar.h. Here is the break
down:

1) A kernel is now completely in one file, not two. After-all, its
conceptually really just *one* kernel. Doing so lets us take advantage
of potential common code. For example, we were copying the generic C
implementation of the kernel and copying it twice or bar_a and bar_u.

2) The API need not be broken. Since the build system has a concept of
implementations that do and do not require alignment, it can still
provide separate function pointers for specifically aligned and
unaligned implementations. So kernel bar.h provides bar() which is new;
and the familiar bar_a(), and bar_u()

3) The build system can automatically dispatch based on alignment. If
all of the pointers are on alignment boundaries, bar() will call
bar_a(), otherwise, bar() will call bar_u(). Doing this, I was able to
remove all of the conditional dispatching based on alignment inside of
the various gnuradio work functions that were calling into volk. In
other words, VOLK itself does the dirty work.

4) No tedious code shuffling required. This handy python script converts
and combines all the old implementations automatically!
https://github.com/guruofquality/gnuradio/blob/volk_work/volk/convert_kernels.py

---------------------------------------------------------------------------
-- Custom dispatchers
---------------------------------------------------------------------------
Now that unaligned and aligned kernels are conceptually together, the
user can also implement custom dispatchers for a kernel within the same
space as the kernel implementations.

Why write a dispatcher? Well, the automatic behaviour has limitations.
For example, suppose that one of the pointers is an accumulator and you
dont care about its alignment constraints.

A custom dispatcher also means that the user can now implement head and
tail cases. Head cases mean that we can attempt to recover alignment
when starting with unaligned pointers. And tail cases means that the
kernel implementations themselves dont have to copy-paste the generic
implementation to deal with remainder num_points.

The following README contains two working examples of custom
dispatchers:
https://github.com/guruofquality/gnuradio/blob/volk_work/volk/kernels/README.txt

---------------------------------------------------------------------------
-- GNU Radio considerations
---------------------------------------------------------------------------
The VOLK changes should be API compatible, so we could change nothing.

Usage of volk in work functions - with these changes its no longer
necessary to perform the dispatching inside of the work function. This
should be conceptually appealing at the very least.

Usage of set_alignment_multiple - I suspect that we would still want the
re-alignment aspect of this setting. That is, after handling an edge
case, the scheduler tries to get back to a state of buffer alignment.

On the other hand, if the author of the kernel writes a custom
dispatcher that handles the head case, then there is nothing to gain by
manipulating the scheduler in this way.

Note: ignore the changes to gnuradio (outside of volk) on the volk_work
branch. Those changes should be obviously, left to be decided.

---------------------------------------------------------------------------
As always, feedback is welcome!

-josh