From d4790a3806d7983e0a6ab07a1c604d08860c23ea Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 6 Mar 2024 08:04:24 +0000 Subject: [PATCH] Update documentation for branch main --- main/dsppp_guidelines.html | 8 +++++++- main/dsppp_memory_allocator.html | 2 +- main/dsppp_memory_static_dynamic.html | 10 +++++----- main/dsppp_template.html | 1 + main/dsppp_vector.html | 2 +- main/dsppp_vector_example.html | 6 +++--- main/footer.js | 4 ++-- version.js | 2 +- 8 files changed, 21 insertions(+), 14 deletions(-) diff --git a/main/dsppp_guidelines.html b/main/dsppp_guidelines.html index c6f82d17..a8756b80 100644 --- a/main/dsppp_guidelines.html +++ b/main/dsppp_guidelines.html @@ -131,7 +131,13 @@
Guidelines
-

+

If you use dynamic objects in your algorithms and some temporaries need to be allocated, they'll generally be allocated through a malloc since the size is not known at build time. It can be an issue:

+
    +
  • Cost of the memory allocation
    • +
  • Fragmentations
    • +
+

If you need to allocate those temporaries very often then it may be better to write the algorithm in such a way that the temporary can be reused between different calls.

+

The function implementing your algorithm would have additional arguments for the temporary matrixes and vectors required in the algorithm.

diff --git a/main/dsppp_memory_allocator.html b/main/dsppp_memory_allocator.html index e9bb5751..d13d2e19 100644 --- a/main/dsppp_memory_allocator.html +++ b/main/dsppp_memory_allocator.html @@ -140,7 +140,7 @@
template<int> typename Allocator = TMP_ALLOC>
struct Vector:Vector_Base<P>

It means that by default the memory allocator is TMP_ALLOC.

-

This TMP_ALLOC #define can be changed if you define it before including any header from the library.

+

This TMP_ALLOC is a #define and can be changed if you define it before including any header from the library.

An allocator should implement a template like:

template<int L>
struct malloc_allocator {
diff --git a/main/dsppp_memory_static_dynamic.html b/main/dsppp_memory_static_dynamic.html index 64b838b2..7d9db22f 100644 --- a/main/dsppp_memory_static_dynamic.html +++ b/main/dsppp_memory_static_dynamic.html @@ -133,19 +133,19 @@

As we have seen in the previous sections, there are two kind of vectors:

    -
  • Vector<T> with a dimension know at runtime
    • +
  • Vector<T> with a dimension known at runtime
  • Vector<T,NB> with a dimension known at build time
-

The former vectors are called "dynamic" ins this library. The later are called "static".

+

The former vectors are called "dynamic" in this library. The later are called "static".

This naming "static" / "dynamic" is referring to the dimension. With "dynamic" vectors the same code can, at runtime, create vectors of different length based on a runtime length.

With "static" vectors : the length is fixed at build time and will never change at runtime.

-

Note that the library also have "static" / "dynamic" matrixes. So, we are going to use "objects" to cover both cases

+

Note that the library also have "static" / "dynamic" matrixes. So, we are going to use the name "object" to cover both cases in the below explanations.

Static objects

The advantage of static objects is that the dimension is known at build time. The compiler can thus generate an algorithm that is specialized for those dimensions and thus more efficient.

With static objects it is also possible to use different memory allocator with better performances and determinism.

-

But, with static objects, objects of different dimension are considered as different types. The compiler will generate different implementation so it will have an impact on the code dimension.

-

If you need lots of objects of different dimensions, or if the dimensions are nort known at build time, then you need to use dynamic object

+

But, with static objects, objects of different dimension are considered as different types. The compiler will generate different implementation so it will have an impact on the code size.

+

If you need lots of objects of different dimensions, or if the dimensions are not known at build time, then you need to use dynamic object

Dynamic objects

With dynamic objects, the dimension is know at runtime. So object of different dimensions have the same datatype and the compiler is generating only one implementation for all those objects. It cannot generate specialized implementations based on the dimension. It is better for code size, but the implementations will be less efficient.

diff --git a/main/dsppp_template.html b/main/dsppp_template.html index 5688f76f..feb35340 100644 --- a/main/dsppp_template.html +++ b/main/dsppp_template.html @@ -147,6 +147,7 @@

And if the function is used with a float64_t *, the compiler would generate code for a function using float64_t.

The generic arm_add source code is a template used to generate different implementations. It is like a code generator.

And if the compiler is unable to generate an implementation because the type variable T is replaced by a type with no addition operator, then it would be detected by the compiler.

+

Note that in C++, you can also use overloading of functions. They'll use the same name (but different arguments) but they won't share the same source code.

Templates for datatypes

C++ templates also apply to structs and classes.

diff --git a/main/dsppp_vector.html b/main/dsppp_vector.html index ea6a9aba..de982cd2 100644 --- a/main/dsppp_vector.html +++ b/main/dsppp_vector.html @@ -177,7 +177,7 @@

It is advised to always use the copy operator (even with normal vectors).

Virtual vectors can have a stride:

d.sub<2>(1) = 0.0f;
-

This line sets the odd elements of the vector to 0.0f. It is creating a vvirtual vector with stride 2 and starting at index 1 of first vector.

+

This line sets the odd elements of the vector to 0.0f. It is creating a virtual vector with stride 2 and starting at index 1 of first vector.

Then, all elements of this virtual vector are set to 0.0f.

The sub API is:

template<int S=1>
diff --git a/main/dsppp_vector_example.html b/main/dsppp_vector_example.html index 65f2e47c..87921901 100644 --- a/main/dsppp_vector_example.html +++ b/main/dsppp_vector_example.html @@ -148,11 +148,11 @@

Include the headers

The headers are not yet part of the CMSIS-DSP packs since they are experimental. You can get them from the CMSIS-DSP github

-
#include <memory_pool>
-
#include <matrix>
+
#include <dsppp/memory_pool>
+
#include <dsppp/matrix>
using namespace arm_cmsis_dsp;
-

If fixed point datatypes are required, #include <fixed_point> should be used before <matrix>

+

If fixed point datatypes are required, #include <dsppp/fixed_point> should be used before <dsppp/matrix>

Fixed point requires the use of CMSIS-DSP.

Creation of the vectors

diff --git a/main/footer.js b/main/footer.js index fd430f17..32f54110 100644 --- a/main/footer.js +++ b/main/footer.js @@ -1,7 +1,7 @@ function writeHeader() { - document.write('Version 1.15.1-dev32'); + document.write('Version 1.15.1-dev33'); }; function writeFooter() { - document.write('Generated on Wed Mar 6 2024 07:10:14 for CMSIS-DSP 1.15.1-dev32+g1bd68d7. Copyright © 2024 Arm Limited (or its affiliates). All rights reserved.'); + document.write('Generated on Wed Mar 6 2024 08:04:00 for CMSIS-DSP 1.15.1-dev33+ga4e82f8. Copyright © 2024 Arm Limited (or its affiliates). All rights reserved.'); }; diff --git a/version.js b/version.js index 1f29b6ab..eadd5bbd 100644 --- a/version.js +++ b/version.js @@ -1,6 +1,6 @@ //--- list of versions --- const versions = { - "main": "1.15.1-dev32", + "main": "1.15.1-dev33", "latest": "1.15.0", "v1.14.4": "1.14.4", "v1.14.3": "1.14.3",