Keith SmithThe Primitives Library Introduction ------------ The purpose of the primitives library is to give the freerdp code easy access to *run-time* optimization via SIMD operations. When the library is initialized, dynamic checks of processor features are run (such as the support of SSE3 or Neon), and entrypoints are linked to through function pointers to provide the fastest possible operations. All routines offer generic C alternatives as fallbacks. Run-time optimization has the advantage of allowing a single executable to run fast on multiple platforms with different SIMD capabilities. Use In Code ----------- A singleton pointing to a structure containing the function pointers is accessed through primitives_get(). The function pointers can then be used from that structure, e.g. primitives_t *prims = primitives_get(); prims->shiftC_16s(buffer, shifts, buffer, 256); Of course, there is some overhead in calling through the function pointer and setting up the SIMD operations, so it would be counterproductive to call the primitives library for very small operation, e.g. initializing an array of eight values to a constant. The primitives library is intended for larger-scale operations, e.g. arrays of size 64 and larger. Initialization and Cleanup -------------------------- Library initialization is done the first time primitives_init() is called or the first time primitives_get() is used. Cleanup (if any) is done by primitives_deinit(). Intel Integrated Performance Primitives (IPP) --------------------------------------------- If freerdp is compiled with IPP support (-DWITH_IPP=ON), the IPP function calls will be used (where available) to fill the function pointers. Where possible, function names and parameter lists match IPP format so that the IPP functions can be plugged into the function pointers without a wrapper layer. Use of IPP is completely optional, and in many cases the SSE operations in the primitives library itself are faster or similar in performance. Coverage -------- The primitives library is not meant to be comprehensive, offering entrypoints for every operation and operand type. Instead, the coverage is focused on operations known to be performance bottlenecks in the code. For instance, 16-bit signed operations are used widely in the RemoteFX software, so you'll find 16s versions of several operations, but there is no attempt to provide (unused) copies of the same code for 8u, 16u, 32s, etc. New Optimizations ----------------- As the need arises, new optimizations can be added to the library, including NEON, AVX, and perhaps OpenCL or other SIMD implementations. The CPU feature detection is done in winpr/sysinfo. Adding Entrypoints ------------------ As the need for new operations or operands arises, new entrypoints can be added. 1) Function prototypes and pointers are added to include/freerdp/primitives.h 2) New module initialization and cleanup function prototypes are added to prim_internal.h and called in primitives.c (primitives_init() and primitives_deinit()). 3) Operation names and parameter lists should be compatible with the IPP. IPP manuals are available online at software.intel.com. 4) A generic C entrypoint must be available as a fallback. 5) prim_templates.h contains macro-based templates for simple operations, such as applying a single SSE operation to arrays of data. The template functions can frequently be used to extend the operations without writing a lot of new code. Cache Management ---------------- I haven't found a lot of speed improvement by attempting prefetch, and in fact it seems to have a negative impact in some cases. Done correctly perhaps the routines could be further accelerated by proper use of prefetch, fences, etc. Testing ------- In the test subdirectory is an executable (prim_test) that tests both functionality and speed of primitives library operations. Any new modules should be added to that test, following the conventions already established in that directory. The program can be executed on various target hardware to compare generic C, optimized, and IPP performance with various array sizes.