MLCE-19: Guidance in subtensor use

Change-Id: I1884408981b5a7b28db1cee7827422b52b72bb41
Reviewed-on: https://eu-gerrit-1.euhpc.arm.com/139344
Tested-by: Jenkins <bsgcomp@arm.com>
Reviewed-by: Matteo Martincigh <matteo.martincigh@arm.com>
Reviewed-by: Anthony Barbier <anthony.barbier@arm.com>

1 files changed, 19 insertions, 0 deletions

diff --git a/docs/01_library.dox b/docs/01_library.dox
index c4edad234d..bd4b300d7d 100644
--- a/docs/01_library.dox
+++ b/docs/01_library.dox
@@ -293,6 +293,25 @@ Here are a couple of examples of how to use the iterators to fill / read tensors
 
 @snippet examples/neon_copy_objects.cpp Copy objects example
 
+@subsection S4_6_5_sub_tensors Sub-tensors
+
+Sub-tensors are aliases to existing Tensors, as a result creating a sub-tensor does not result in any underlying memory allocation.
+
+Sub-tensors can be used to access a sub-set of the parent tensor, something that can be useful in case different operations need to be performed on different parts of a tensor.
+
+Moreover, sub-tensors can be used to perform zero copy tensor concatenation.
+
+The API for creating a sub-tensor is the following:
+@code{.cpp}
+SubTensor(ITensor *parent, const TensorShape &tensor_shape, const Coordinates &coords)
+@endcode
+
+Where \a parent is the parent tensor which we want to create an alias for, \a tensor_shape is the shape of the sub-tensor and \a coords are the starting indexing coordinates of the sub-tensor within the parent tensor.
+
+@note Two sub-tensor concrete classes for different targets are currently supported : @ref CLSubTensor and @ref SubTensor
+
+@warning Limitation of the sub-tensor is that it cannot be extracted spatially, meaning sub-tensors should have the same width and height as the parent tensor. The main reasons for this is the fact that individual kernels might need to operate with a step size that is not a multiple of the sub-tensor spatial dimension. This could lead to elements being overwritten by different kernels operating on different sub-tensors of the same underlying tensor.
+
 @section S4_7_memory_manager MemoryManager
 
 @ref IMemoryManager is a memory managing interface that can be used to reduce the memory requirements of a given pipeline by recycling temporary buffers.