Added notes on CMSIS optimization for FloatArray

giuliomoro · giuliomoro · commit 647f87a68bab · 2015-07-31T19:23:02.000+01:00
diff --git a/LibSource/FloatArray.cpp b/LibSource/FloatArray.cpp
@@ -4,6 +4,7 @@
 #include <string.h>
 
 void FloatArray::getMin(float* value, int* index){
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   unsigned long idx;
   arm_min_f32(data, size, value, &idx);
@@ -24,19 +25,22 @@ void FloatArray::getMin(float* value, int* index){
 float FloatArray::getMinValue(){
   float value;
   int index;
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   getMin(&value, &index);
   return value;
 }
 
 int FloatArray::getMinIndex(){
   float value;
   int index;
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   getMin(&value, &index);
   return index;
 }
 
 void FloatArray::getMax(float* value, int* index){
   ASSERT(size>0, "Wrong size");
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX 
   unsigned long idx;
   arm_max_f32(data, size, value, &idx);
@@ -57,20 +61,23 @@ void FloatArray::getMax(float* value, int* index){
 float FloatArray::getMaxValue(){
   float value;
   int index;
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   getMax(&value, &index);
   return value;
 }
 
 int FloatArray::getMaxIndex(){
   float value;
   int index;
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   getMax(&value, &index);
   return index;
 }
 
 void FloatArray::rectify(FloatArray& destination){ //this is actually "copy data with rectifify"
   int minSize= min(size,destination.getSize()); //TODO: shall we take this out and allow it to segfault?
-#ifdef ARM_CORTEX  
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
+#ifdef ARM_CORTEX   
   arm_abs_f32( (float*)data, (float*)destination, size);
 #else
   for(int n=0; n<minSize; n++){
@@ -80,6 +87,7 @@ void FloatArray::rectify(FloatArray& destination){ //this is actually "copy data
 }
 
 void FloatArray::rectify(){//in place
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   rectify(*this);
 }
 
@@ -104,7 +112,7 @@ void FloatArray::reverse(){//in place
 void FloatArray::reciprocal(FloatArray& destination){
   float* data = getData();
   for(int n=0; n<getSize(); n++)
-    destination[n] = 1/data[n];
+    destination[n] = 1.0f/data[n];
 }
 
 void FloatArray::reciprocal(){//in place
@@ -113,6 +121,7 @@ void FloatArray::reciprocal(){//in place
 
 float FloatArray::getRms(){
   float result;
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX  
   arm_rms_f32 (data, size, &result);
 #else
@@ -128,6 +137,7 @@ float FloatArray::getRms(){
 
 float FloatArray::getMean(){
   float result;
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX  
   arm_mean_f32 (data, size, &result);
 #else
@@ -142,6 +152,7 @@ float FloatArray::getMean(){
 
 float FloatArray::getPower(){
   float result;
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX  
   arm_power_f32 (data, size, &result);
 #else
@@ -156,6 +167,7 @@ float FloatArray::getPower(){
 
 float FloatArray::getStandardDeviation(){
   float result;
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX  
   arm_std_f32 (data, size, &result);
 #else
@@ -166,6 +178,7 @@ float FloatArray::getStandardDeviation(){
 
 float FloatArray::getVariance(){
   float result;
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX  
   arm_var_f32(data, size, &result);
 #else
@@ -179,6 +192,7 @@ float FloatArray::getVariance(){
   return result;
 }
 void FloatArray::scale(float factor, FloatArray destination){//supports in-place
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX  
   arm_scale_f32(data, factor, destination, size);
 #else
@@ -189,6 +203,7 @@ void FloatArray::scale(float factor, FloatArray destination){//supports in-place
 }
 
 void FloatArray::scale(float factor){
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   scale(factor, *this);
 }
 void FloatArray::clip(){
@@ -216,15 +231,18 @@ FloatArray FloatArray::subArray(int offset, int length){
 }
 
 void FloatArray::copyTo(FloatArray destination){
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   copyTo(destination, min(size, destination.getSize()));
 }
 
 void FloatArray::copyFrom(FloatArray source){
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   copyFrom(source, min(size, source.getSize()));
 }
 
 void FloatArray::copyTo(float* other, int length){
   ASSERT(size >= length, "Array too small");
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   arm_copy_f32(data, other, length);
 #else
@@ -234,6 +252,7 @@ void FloatArray::copyTo(float* other, int length){
 
 void FloatArray::copyFrom(float* other, int length){
   ASSERT(size >= length, "Array too small");
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   arm_copy_f32(other, data, length);
 #else
@@ -244,6 +263,7 @@ void FloatArray::copyFrom(float* other, int length){
 void FloatArray::insert(FloatArray source, int sourceOffset, int destinationOffset, int samples){
   ASSERT(size >= destinationOffset+samples, "Array too small");
   ASSERT(source.size >= sourceOffset+samples, "Array too small");
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   arm_copy_f32(source.data+sourceOffset, data+destinationOffset, samples);  
 #else
@@ -252,6 +272,7 @@ void FloatArray::insert(FloatArray source, int sourceOffset, int destinationOffs
 }
 
 void FloatArray::insert(FloatArray source, int destinationOffset, int samples){
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   insert(source, 0, destinationOffset, samples);
 }
 
@@ -261,6 +282,7 @@ void FloatArray::move(int fromIndex, int toIndex, int samples){
 }
 
 void FloatArray::setAll(float value){
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   arm_fill_f32(value, data, size);
 #else
@@ -272,6 +294,7 @@ void FloatArray::setAll(float value){
 
 void FloatArray::add(FloatArray operand2, FloatArray destination){ //allows in-place
   ASSERT(operand2.size == size &&  destination.size==size, "Arrays must be same size");
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   /* despite not explicitely documented in the CMSIS documentation,
       this has been tested to behave properly even when pSrcA==pDst
@@ -286,18 +309,20 @@ void FloatArray::add(FloatArray operand2, FloatArray destination){ //allows in-p
 }
 
 void FloatArray::add(FloatArray operand2){ //in-place
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   add(operand2, *this);
 }
 
 void FloatArray::add(float scalar){
   for(int n=0; n<size; n++){
-   data[n]+=scalar;
+    data[n]+=scalar;
   } 
 }
 
 void FloatArray::subtract(FloatArray operand2, FloatArray destination){ //allows in-place
   ASSERT(operand2.size == size && destination.size==size, "Arrays must be same size");
-  #ifdef ARM_CORTEX
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
+#ifdef ARM_CORTEX
   /* despite not explicitely documented in the CMSIS documentation,
       this has been tested to behave properly even when pSrcA==pDst
       void 	arm_sub_f32 (float32_t *pSrcA, float32_t *pSrcB, float32_t *pDst, uint32_t blockSize)
@@ -311,6 +336,7 @@ void FloatArray::subtract(FloatArray operand2, FloatArray destination){ //allows
 }
 
 void FloatArray::subtract(FloatArray operand2){ //in-place
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   subtract(operand2, *this);
 }
 
@@ -322,7 +348,8 @@ void FloatArray::subtract(float scalar){
 
 void FloatArray::multiply(FloatArray operand2, FloatArray destination){ //allows in-place
   ASSERT(operand2.size == size &&  destination.size==size, "Arrays must be same size");
-  #ifdef ARM_CORTEX
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
+#ifdef ARM_CORTEX
   /* despite not explicitely documented in the CMSIS documentation,
       this has been tested to behave properly even when pSrcA==pDst
       void 	arm_mult_f32 (float32_t *pSrcA, float32_t *pSrcB, float32_t *pDst, uint32_t blockSize)
@@ -337,6 +364,7 @@ void FloatArray::multiply(FloatArray operand2, FloatArray destination){ //allows
 }
 
 void FloatArray::multiply(FloatArray operand2){ //in-place
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   multiply(operand2, *this);
 }
 
@@ -347,7 +375,8 @@ void FloatArray::multiply(float scalar){
 }
 
 void FloatArray::negate(FloatArray& destination){//allows in-place
-  #ifdef ARM_CORTEX
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
+#ifdef ARM_CORTEX
   arm_negate_f32(data, destination.getData(), size); 
   #else
   for(int n=0; n<size; n++){
@@ -356,6 +385,7 @@ void FloatArray::negate(FloatArray& destination){//allows in-place
   #endif /* ARM_CORTEX */
 }
 void FloatArray::negate(){
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   negate(*this);
 }
 
@@ -375,6 +405,7 @@ void FloatArray::noise(float min, float max){
 
 void FloatArray::convolve(FloatArray operand2, FloatArray destination){
   ASSERT(destination.size >= size + operand2.size -1, "Destination array too small");
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   arm_conv_f32(data, size, operand2.data, operand2.size, destination);
 #else
@@ -393,6 +424,7 @@ void FloatArray::convolve(FloatArray operand2, FloatArray destination){
 
 void FloatArray::convolve(FloatArray operand2, FloatArray destination, int offset, int samples){
   ASSERT(destination.size >= size + operand2.size -1, "Destination array too small"); //TODO: change this condition to the actual size being written(will be samples+ tail)
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   //TODO: I suspect a bug in arm_conv_partial_f32
   //it seems that destination[n] is left unchanged for n<offset
@@ -420,10 +452,12 @@ void FloatArray::convolve(FloatArray operand2, FloatArray destination, int offse
 
 void FloatArray::correlate(FloatArray operand2, FloatArray destination){ 
   destination.setAll(0);
+  /// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
   correlateInitialized(operand2, destination);
 }
 void FloatArray::correlateInitialized(FloatArray operand2, FloatArray destination){
   ASSERT(destination.size >= size+operand2.size-1, "Destination array too small"); //TODO: change CMSIS docs, which state a different size
+/// @note When built for ARM Cortex-M processor series, this method uses the optimized <a href="http://www.keil.com/pack/doc/CMSIS/General/html/index.html">CMSIS library</a>
 #ifdef ARM_CORTEX
   arm_correlate_f32(data, size, operand2.data, operand2.size, destination);
 #else
diff --git a/LibSource/FloatArray.h b/LibSource/FloatArray.h
@@ -36,20 +36,21 @@ class FloatArray {
    * Get the minimum value in the array and its index
    * @param[out] value will be set to the minimum value after the call
    * @param[out] index will be set to the index of the minimum value after the call
+   * 
    */
   void getMin(float* value, int* index);
   
   /**
    * Get the maximum value in the array and its index
    * @param[out] value will be set to the maximum value after the call
    * @param[out] index will be set to the index of the maximum value after the call
-   */
+  */
   void getMax(float* value, int* index);
   
   /**
    * Get the minimum value in the array
    * @return the minimum value contained in the array
-   */
+  */
   float getMinValue();
   
   /**
@@ -282,7 +283,7 @@ class FloatArray {
    * @param[out] destination the destination array.
    * @param[in] offset first output sample to compute
    * @param[in] samples number of samples to compute
-   * @note **destination[n]** is left unchanged for n<offset and the result is stored from destination[offset] onwards
+   * @remarks **destination[n]** is left unchanged for n<offset and the result is stored from destination[offset] onwards
    * that is, in the same position where they would be if a full convolution was performed.
   */
   void convolve(FloatArray operand2, FloatArray destination, int offset, int samples);
@@ -300,7 +301,7 @@ class FloatArray {
    * Sets **destination** to the correlation of *this* array and **operand2**.
    * @param[in] operand2 the second operand for the correlation
    * @param[out] destination array. It must have a minimum size of 2*max(srcALen, srcBLen)-1
-   * @note It is the same as correlate(), but destination must have been initialized to 0 in advance. 
+   * @remarks It is the same as correlate(), but destination must have been initialized to 0 in advance. 
   */
   void correlateInitialized(FloatArray operand2, FloatArray destination);
 
@@ -317,10 +318,10 @@ class FloatArray {
    * @param[in] offset the first element of the subset.
    * @param[in] length the number of elments in the new FloatArray.
    * @return the newly created FloatArray.
-   * @note no memory is allocated by this method. The memory is still shared with the original array.
+   * @remarks no memory is allocated by this method. The memory is still shared with the original array.
    * The memory should not be de-allocated elsewhere (e.g.: by calling FloatArray::destroy() on the original FloatArray) 
    * as long as the FloatArray returned by this method is still in use.
-   * @note Calling FloatArray::destroy() on a FloatArray instance created wit this method will cause an exception.
+   * @remarks Calling FloatArray::destroy() on a FloatArray instance created wit this method will cause an exception.
   */
   FloatArray subArray(int offset, int length);
   
@@ -377,7 +378,7 @@ class FloatArray {
    * @param[in] fromIndex the first element to copy
    * @param[in] toIndex the destination of the first element
    * @param[in] length the number of elements to copy
-   * @note this method uses *memmove()* so that the source memory and the destination memory can overlap. As a consequence it might have slow performances.
+   * @remarks this method uses *memmove()* so that the source memory and the destination memory can overlap. As a consequence it might have slow performances.
   */
   void move(int fromIndex, int toIndex, int length);
   
@@ -446,15 +447,15 @@ class FloatArray {
    * Allocates size*sizeof(float) bytes of memory and returns a FloatArray that points to it.
    * @param size the size of the new FloatArray.
    * @return a FloatArray which **data** point to the newly allocated memory and **size** is initialized to the proper value.
-   * @note a FloatArray created with this method has to be destroyed invoking the FloatArray::destroy() method.
+   * @remarks a FloatArray created with this method has to be destroyed invoking the FloatArray::destroy() method.
   */
   static FloatArray create(int size);
   
   /**
    * Destroys a FloatArray created with the create() method.
    * @param array the FloatArray to be destroyed.
-   * @note the FloatArray object passed as an argument should not be used again after invoking this method.
-   * @note a FloatArray object that has not been created by the FloatArray::create() method might cause an exception if passed as an argument to this method.
+   * @remarks the FloatArray object passed as an argument should not be used again after invoking this method.
+   * @remarks a FloatArray object that has not been created by the FloatArray::create() method might cause an exception if passed as an argument to this method.
   */
   static void destroy(FloatArray array);
 };
