Improved doxygen for FFTs

ARM-software · Dec 6, 2024 · f91cb53 · f91cb53
1 parent 4d3e915
commit f91cb53
Show file tree

Hide file tree

Showing 11 changed files with 178 additions and 59 deletions.
diff --git a/Include/dsp/transform_functions.h b/Include/dsp/transform_functions.h
@@ -51,6 +51,41 @@ extern "C"
 
 /**
  * @defgroup groupTransforms Transform Functions
+ * 
+ * CMSIS-DSP provides CFFT and RFFT for different architectures.
+ * The implementation of those transforms may be different for the
+ * different architectures : different algorithms, different capabilities
+ * of the instruction set.
+ * 
+ * All those variants are not giving exactly the same results but they 
+ * are passing the same tests with same SNR checks and same threshold for 
+ * the sample errors.
+ * 
+ * The APIs for the Neon variants are different : some additional
+ * temporary buffers are required.
+ * 
+ * Float16 versions are provided but they are not very accurate and 
+ * should only be used for small FFTs.
+ * 
+ * @par Transform initializations
+ *  
+ *  There are several ways to initialize the transform functions.
+ *  Below explanations are using q15 as example but the same explanations
+ *  apply to other datatypes.
+ *  
+ *  Before Helium and Neon, you can just use a pre-initialized 
+ *  constant data structure and use it in the arm_cfft_... function.
+ *  For instance, &arm_cfft_sR_q15_len256 for a 256 Q15 CFFT.
+ *  
+ *  On Helium and Neon, you *must* use an initialization function. If you know the size of your FFT (or other transform) you can use a specific initialization function for this size only : like arm_cfft_init_256_q15 for a 256 Q15 complex FFT.
+ *  
+ *  By using a specific initialization function, you give an hint to the linker and it will be able to remove all unused initialization tables (some compilation and link flags must be used for the linker to be able to do this optimization. It is compiler dependent).
+ *  
+ *  If you don't know the size you'll need at runtime, you need to use a function like arm_cfft_init_q15. If you use such a function, all the tables for all FFT sizes (up to the CMSIS-DSP maximum of 4096) will be included in the build !
+ *  
+ *  On Neon, there is another possibility. You can use arm_cfft_init_dynamic_q15. This function will allocate a buffer at runtime and compute at runtime all the tables that are required for a specific FFT size. This initialization is also supported by RFFT.
+ *  The computation to initialize all the tables can take lot of cycles
+ *  (since several cos and sin must be computed)
  */
 
 

diff --git a/Ne10/CMSIS_NE10_fft_init.c b/Ne10/CMSIS_NE10_fft_init.c
@@ -953,7 +953,7 @@ arm_cfft_instance_f16 *arm_cfft_init_dynamic_f16(uint32_t fftLen)
 /**
  * @brief      Initialize data structure for a RFFT
  *
- * @param[in]  fftLen  The rfft length
+ * @param[in]  nfft  The rfft length
  *
  * @return     Pointer to the new structure
  * 
@@ -1131,7 +1131,7 @@ arm_rfft_fast_instance_f16 *arm_rfft_fast_init_dynamic_f16 (uint32_t nfft)
 /**
  * @brief      Initialize data structure for a RFFT
  *
- * @param[in]  fftLen  The rfft length
+ * @param[in]  nfft  The rfft length
  *
  * @return     Pointer to the new structure
  * 
@@ -1305,6 +1305,19 @@ arm_rfft_fast_instance_f32 *arm_rfft_fast_init_dynamic_f32 (uint32_t nfft)
   @addtogroup RealFFTQ31
   @{
  */
+/**
+ * @brief      Initialize RFFT Q31 with memory allocation
+ *
+ * @param[in]  nfft  The nfft
+ *
+ * @return     Pointer to RFFT instance Q31
+ * 
+ * @par       This function is only available for Neon
+ *            This function is allocating memory. The
+ *            memory must be released when no more used.
+ *            This function can be used with RFFT lengths
+ *            longer than the ones supported on Cortex-M
+ */
   arm_rfft_instance_q31 *arm_rfft_init_dynamic_q31(uint32_t nfft)
   {
     arm_rfft_instance_q31 *st = NULL;
@@ -1402,6 +1415,20 @@ arm_rfft_fast_instance_f32 *arm_rfft_fast_init_dynamic_f32 (uint32_t nfft)
   @addtogroup RealFFTQ15
   @{
  */
+
+  /**
+   * @brief      Initialize RFFT Q15 with memory allocation
+   *
+   * @param[in]  nfft  The nfft
+   *
+   * @return     Pointer to an RFFT Instance Q15
+   * 
+   * @par       This function is only available for Neon
+ *            This function is allocating memory. The
+ *            memory must be released when no more used.
+ *            This function can be used with RFFT lengths
+ *            longer than the ones supported on Cortex-M
+   */
   arm_rfft_instance_q15 *arm_rfft_init_dynamic_q15(uint32_t nfft)
   {
     arm_rfft_instance_q15* st = NULL;

diff --git a/Source/TransformFunctions/arm_cfft_f16.c b/Source/TransformFunctions/arm_cfft_f16.c
@@ -521,6 +521,25 @@ static void arm_cfft_radix4by2_inverse_f16_mve(const arm_cfft_instance_f16 * S,f
   @param[in]     bitReverseFlag flag that enables / disables bit reversal of output
                    - value = 0: disables bit reversal of output
                    - value = 1: enables bit reversal of output
+
+@par Neon version
+                     The neon version has a different API.
+                     The input and output buffers must be
+                     different.
+                     There is a temporary buffer.
+                     The temporary buffer has same size as
+                     input or output buffer.
+                     The bit reverse flag is not more 
+                     available in Neon version.
+
+  @code
+        void arm_cfft_f16(
+                const arm_cfft_instance_f16 * S,
+                      const float16_t * pIn,
+                      float16_t * pOut,
+                      float16_t * pBuffer, 
+                      uint8_t ifftFlag);
+  @endcode
  */
 
 

diff --git a/Source/TransformFunctions/arm_cfft_f32.c b/Source/TransformFunctions/arm_cfft_f32.c
@@ -702,7 +702,7 @@ extern void arm_bitreversal_32(
                    needed FFTs.</b> Other FFT versions can continue to be initialized as
                    explained below.
   @par
-                   For not MVE versions, pre-initialized data structures containing twiddle factors
+                   For versions not targetting Helium or Neon, pre-initialized data structures containing twiddle factors
                    and bit reversal tables are provided and defined in <code>arm_const_structs.h</code>.  Include
                    this header in your function and then pass one of the constant structures as
                    an argument to arm_cfft_f32.  For example:
@@ -770,7 +770,7 @@ extern void arm_bitreversal_32(
                    Pre-initialized data structures containing twiddle factors and bit reversal
                    tables are provided and defined in <code>arm_const_structs.h</code>.  Include
                    this header in your function and then pass one of the constant structures as
-                   an argument to arm_cfft_q31. For example:
+                   an argument to arm_cfft_q31 (except if you are targetting Helium or Neon). For example:
   @par
                    <code>arm_cfft_q31(arm_cfft_sR_q31_len64, pSrc, 1, 1)</code>
   @par

diff --git a/Source/TransformFunctions/arm_cfft_init_f16.c b/Source/TransformFunctions/arm_cfft_init_f16.c
@@ -155,7 +155,7 @@ arm_status arm_cfft_init_##LEN##_f16(arm_cfft_instance_f16 * S)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -168,7 +168,7 @@ CFFTINIT_F16(4096,4096)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -182,7 +182,7 @@ CFFTINIT_F16(2048,1024)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -196,7 +196,7 @@ CFFTINIT_F16(1024,1024)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -210,7 +210,7 @@ CFFTINIT_F16(512,256)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -224,7 +224,7 @@ CFFTINIT_F16(256,256)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -238,7 +238,7 @@ CFFTINIT_F16(128,64)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -252,7 +252,7 @@ CFFTINIT_F16(64,64)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -266,7 +266,7 @@ CFFTINIT_F16(32,16)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -281,7 +281,7 @@ CFFTINIT_F16(16,16)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
   

diff --git a/Source/TransformFunctions/arm_cfft_init_f32.c b/Source/TransformFunctions/arm_cfft_init_f32.c
@@ -145,7 +145,7 @@ ARM_DSP_ATTRIBUTE arm_status arm_cfft_init_##LEN##_f32(arm_cfft_instance_f32 * S
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -159,7 +159,7 @@ CFFTINIT_F32(4096,4096)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -173,7 +173,7 @@ CFFTINIT_F32(2048,1024)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -187,7 +187,7 @@ CFFTINIT_F32(1024,1024)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -201,7 +201,7 @@ CFFTINIT_F32(512,256)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -215,7 +215,7 @@ CFFTINIT_F32(256,256)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -229,7 +229,7 @@ CFFTINIT_F32(128,64)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -243,7 +243,7 @@ CFFTINIT_F32(64,64)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -257,7 +257,7 @@ CFFTINIT_F32(32,16)
                    - \ref ARM_MATH_SUCCESS        : Operation successful
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
-  @par          Use of this function is mandatory only for the MVE version of the FFT.
+  @par          Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h
  */
@@ -273,7 +273,7 @@ CFFTINIT_F32(16,16)
                    - \ref ARM_MATH_ARGUMENT_ERROR : an error is detected
 
   @par
-                Use of this function is mandatory only for the MVE version of the FFT.
+                Use of this function is mandatory only for the Helium and Neon versions of the FFT.
                 Other versions can still initialize directly the data structure using 
                 variables declared in arm_const_structs.h