[clfft] 63/128: Precallback documentation in mainpage.h
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Oct 22 14:54:39 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to branch master
in repository clfft.
commit 9f7f15bf7425cf15b79effb841eb7b27dc3fa250
Author: Pradeep <pradeep.rao at amd.com>
Date: Thu Sep 10 10:06:30 2015 +0530
Precallback documentation in mainpage.h
---
src/library/mainpage.h | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 98 insertions(+)
diff --git a/src/library/mainpage.h b/src/library/mainpage.h
index 1624d72..268da3b 100644
--- a/src/library/mainpage.h
+++ b/src/library/mainpage.h
@@ -559,4 +559,102 @@ FFT features of this library.
@image html realfft_expl_07.jpg "2D FFT - Real to Hermitian In Place"
@image html realfft_expl_08.jpg "2D FFT - Real to Hermitian, Example"
+ at section Callbacks clFFT Callbacks
+
+Callback feature of clFFT provides ability to do custom processing when reading input data or when writing output data. There are 2 types of callback, Pre-callback and Post-callback. Pre-callback invokes user callback function to do custom preprocessing of input data before FFT is executed. Post-callback invokes user callback function to do custom post-processing of output data after FFT is executed. The intent is to avoid additional kernels and kernel launches to carry out the pre/post [...]
+
+The current release of clFFT includes Pre-callback feature. Post-callback will be supported in a future release.
+
+ at subsection CallbackWorkflow Callback Workflow
+
+The workflow for callback is as below
+
+<ol>
+ <li> User registers the callback function with library by passing the OpenCL inline function as a string
+ <li> User initializes other standard FFT parameters
+ <li> User invokes Bake Plan step
+ <li> Library inserts the callback code into main FFT kernel during bake plan and compiles it. If the registered callback function does not adhere to required function prototype, the compilation fails and is reported to the user
+ <li> User invokes Execute FFT
+</ol>
+
+The caller is responsible to provide a string-ified callback function that matches the function prototype based on the type of callback(pre/post), type of transform(real/complex) and whether LDS is used. The bake plan step does the function prototype checking.
+
+ at subsection CallbackFunctionPrototype Callback Function Prototypes
+
+clFFT expects the callback function to be of a specific prototype depending on the type of callback(pre/post), type of transform(real/complex) and whether LDS is used. These are as following.
+
+ at subsubsection PrecallbackProtyotype Pre-callback Prototypes
+
+ FFT Type | Prototype
+---------------------------------------- | -------------
+C2C/C2R – Interleaved Single Precision | \c Without \c LDS <br />float2 <precallback_func> ( __global void *input, uint inoffset, __global void *userdata) <br /> \c With \c LDS <br />float2 <precallback_func> ( __global void *input, uint inoffset, __global void *userdata, __local void *localmem)
+C2C/C2R – Interleaved Double Precision | \c Without \c LDS <br />double2 <precallback_func> ( __global void *input, uint inoffset, __global void *userdata) <br /> \c With \c LDS <br />double2 <precallback_func> ( __global void *input, uint inoffset, __global void *userdata, __local void *localmem)
+C2C – Planar Single Precision | \c Without \c LDS <br />float2 <precallback_func> ( __global void *inputRe, __global void *inputIm, uint inoffset, __global void *userdata)<br /> \c With \c LDS <br />float2 <precallback_func> ( __global void *inputRe, __global void *inputIm, int inoffset, __global void *userdata, __local void *localmem)
+C2C – Planar Double Precision | \c Without \c LDS <br />double2 <precallback_func> ( __global void *inputRe, __global void *inputIm, uint inoffset, __global void *userdata)<br /> \c With \c LDS <br />double2 <precallback_func> ( __global void *inputRe, __global void *inputIm, uint inoffset, __global void *userdata, __local void *localmem)
+R2C Single Precision | \c Without \c LDS <br />float <precallback_func> ( __global void *input, uint inoffset, __global void *userdata)<br /> \c With \c LDS <br />float <precallback_func> ( __global void *input, uint inoffset, __global void *userdata, __local void *localmem)
+R2C Double Precision | \c Without \c LDS <br />double <precallback_func> ( __global void *input, uint inoffset, __global void *userdata)<br /> \c With \c LDS <br />double <precallback_func> ( __global void *input, uint inoffset, __global void *userdata, __local void *localmem)
+
+
+Parameters
+<ul>
+ <li> \c input : Start pointer of the input buffer for R2C and Interleaved C2C/C2R transforms
+ <li> \c inputRe : Start pointer of the “Real” input buffer for Planar C2C transforms
+ <li> \c inputIm : Start pointer of the “Imaginary” part input buffer for Planar C2C transforms
+ <li> \c inoffset : Offset of the input buffer from the start
+ <li> \c userdata : Buffer containing optional caller specified data
+ <li> \c localmem : Pointer to local memory. This memory is allocated by library based on the size specified by user and subject to local memory availability
+</ul>
+
+For Planar C2C, the return type of callback is a vector (float2/double2) whose elements contain the result for Real and Imaginary as computed in the callback
+
+ at subsubsection SamplePrecallbackCode Sample Pre-Callback Code
+
+ at code
+//**************************************************************************
+//* Step 1 : Store the callback function in a string
+//**************************************************************************
+const char* precallbackstr = “float2 mulval(__global void* in,
+ uint inoffset,
+ __global void* userdata,
+ __local void* localmem)
+ {
+ int scalar = *((__global int*)userdata + offset);
+ float2 ret = *((__global float2*)(float2) + offset) * scalar;
+ return ret;
+ }”;
+
+
+//**************************************************************************
+//* Step 2 : Initialize arguments if any required by the callback
+//**************************************************************************
+int h_userdata[N] = { };
+cl_mem userdata = clCreateBuffer(context, CL_MEM_READ_ONLY | CL_MEM_COPY_HOST_PTR, sizeof(int) * N, (void*)h_userdata, NULL);
+
+
+//**************************************************************************
+//* Step 3 : Register the callback
+//**************************************************************************
+
+status = clFFTSetPlanCallback(plan_handle, "mulval", precallbackstr, NULL, 0, PRECALLBACK, userdata);
+
+
+//**************************************************************************
+//* Step 4 : Bake plan and enqueue transform
+//**************************************************************************
+status = clfftBakePlan( plan_handle, 1, &queue, NULL, NULL );
+
+status = clfftEnqueueTransform( plan_handle, dir, 1, &queue, 0, NULL, &outEvent,
+ &input_buffers[ 0 ], buffersOut, clMedBuffer );
+ at endcode
+
+ at subsection CallbackConsiderations Callback Considerations
+
+<ol>
+ <li> The caller is responsible to provide a callback function in string form that matches the function prototype based on the type of callback(pre/post), type of transform(real/complex) and whether LDS is used
+ <li> Library supports only element-wise update corresponding to the offset passed to the callback function
+ <li> Callback function can request for local memory for its own use. If the requested amount of local memory is available on the device, clFFT will pass a pointer to it when it invokes the callback function
+ <li> clFFT may invoke FFT kernels several times depending on the input parameters. But the pre-callback function provided by caller, will be invoked only once for each point in the input
+ <li> If clFFT is implementing a given FFT in multiple phases, it will only call the pre-callback function from the first phase kernel
+</ol>
+
*/
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/clfft.git
More information about the debian-science-commits
mailing list