Skip to content

Commit 79100ff

Browse files
dzakhardzakhar
committed
[DOCS] Unblock create_subtensor section in the utility chapter
1 parent e5a30b1 commit 79100ff

File tree

1 file changed

+73
-71
lines changed

1 file changed

+73
-71
lines changed

‎doc/documents/utility_functions/util_help_func.rst‎

Lines changed: 73 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,7 @@ getting information from data structures and performing various operations on th
1616

1717
- :ref:`get_zero_offset_val`
1818

19-
..
20-
- :ref:`point_sub_tensor`
19+
- :ref:`create_sub_tensor`
2120

2221
- :ref:`num_of_accu_bits`
2322

@@ -224,88 +223,91 @@ Conditions:
224223

225224
- ``in`` must contain a valid data format
226225
- zero_idx must be less or equal to number of zero offset values in the tensor
227-
228-
.. _point_sub_tensor:
229226

230-
..
231-
Point to Sub-Tensor
232-
~~~~~~~~~~~~~~~~~~~
233227

234-
.. warning::
228+
.. _create_sub_tensor:
235229

236-
The interface of this function is subject to change. Avoid using it.
230+
Create Subtensor
231+
~~~~~~~~~~~~~~~~~~~
237232

238-
..
233+
This function points to sub tensors in the input tensor. This function can
234+
be considered as indexing in a multidimensional array without copying or
235+
used to create a slice/fragment of the input tensor without copying the data.
239236

240-
This function points to sub tensors in the input tensor. This function can
241-
be considered as indexing in a multidimensional array without copying or
242-
used to create a slice/fragment of the input tensor without copying the data.
237+
For example, given a HWC tensor, this function could be used to create a HWC
238+
tensor for the top half of the HW image for all channels.
243239

244-
For example, given a HWC tensor, this function could be used to create a HWC
245-
tensor for the top half of the HW image for all channels.
240+
The function prototype:
246241

247-
The configuration struct is defined as follows and the fields are explained in
248-
Table :ref:`t_mli_sub_tensor_cfg_desc`.
242+
.. code:: c
249243
250-
.. code:: c
244+
mli_status mli_hlp_create_subtensor(
245+
const mli_tensor *in,
246+
const mli_subtensor_cfg *cfg,
247+
mli_tensor *out);
248+
..
249+
250+
The configuration struct is defined as follows and the fields are explained in
251+
Table :ref:`t_mli_sub_tensor_cfg_desc`.
252+
253+
.. code:: c
251254
252-
typedef struct {
255+
typedef struct {
253256
uint32_t offset[MLI_MAX_RANK];
254257
uint32_t size[MLI_MAX_RANK];
255258
uint32_t sub_tensor_rank;
256-
} mli_sub_tensor_cfg;
257-
..
258-
259-
.. _t_mli_sub_tensor_cfg_desc:
260-
.. table:: mli_sub_tensor_cfg Structure Field Description
261-
:align: center
262-
:widths: auto
263-
264-
+---------------------+----------------+---------------------------------------------------------+
265-
| **Field Name** | **Type** | Description |
266-
+=====================+================+=========================================================+
267-
| | | Start coordinate in the input tensor. Values must |
268-
| ``offset`` | ``uint32_t[]`` | be smaller than the shape of the input tensor. Size |
269-
| | | of the array must be equal to the rank of the input |
270-
| | | tensor. |
271-
+---------------------+----------------+---------------------------------------------------------+
272-
| | | Size of the sub tensor in elements per dimension: |
273-
| ``size`` | ``uint32_t[]`` | |
274-
| | | Restrictions: Size[d] + offset[d] <= input->shape[d] |
275-
+---------------------+----------------+---------------------------------------------------------+
276-
| | | Rank of the sub tensor that is produced. Must be |
277-
| | | smaller or equal to the rank of the input tensor. If |
278-
| ``sub_tensor_rank`` | ``uint32_t`` | the ``sub_tensor_rank`` is smaller than the input rank, |
279-
| | | the dimensions with a size of 1 is removed in the |
280-
| | | output shape starting from the first dimension until |
281-
| | | the requested ``sub_tensor_rank`` value is reached. |
282-
+---------------------+----------------+---------------------------------------------------------+
283-
..
284-
285-
This function computes the new data pointer based on the offset vector and it sets
286-
the shape of the output tensor according to the size vector. The ``mem_stride`` fields
287-
are copied from the input to the output, so after this operation, the output tensor might
288-
not be a contiguous block of data.
289-
290-
The function also reduces the rank of the output tensor if requested by the
291-
configuration. Only the dimensions with a size of 1 can be removed. Data format and
292-
quantization parameters are copied from the input to the output tensor.
293-
294-
The capacity field of the output is the input capacity decremented with the same
295-
value as that used to increment the data pointer.
296-
297-
The function prototype:
298-
299-
.. code:: c
300-
301-
mli_status mli_hlp_subtensor(
302-
const mli_tensor *in,
303-
const mli_subtensor_cfg *cfg,
304-
mli_tensor *out);
305-
..
259+
} mli_sub_tensor_cfg;
260+
..
261+
262+
.. _t_mli_sub_tensor_cfg_desc:
263+
.. table:: mli_sub_tensor_cfg Structure Field Description
264+
:align: center
265+
:widths: auto
306266

307-
Depending on the debug level (see section :ref:`err_codes`), this function performs a parameter
308-
check and returns the result as an ``mli_status`` code as described in section :ref:`kernl_sp_conf`.
267+
+---------------------+----------------+---------------------------------------------------------+
268+
| **Field Name** | **Type** | Description |
269+
+=====================+================+=========================================================+
270+
| | | Start coordinate in the input tensor. Values must |
271+
| ``offset`` | ``uint32_t[]`` | be smaller than the shape of the input tensor. Size |
272+
| | | of the array must be equal to the rank of the input |
273+
| | | tensor. |
274+
+---------------------+----------------+---------------------------------------------------------+
275+
| | | Size of the sub tensor in elements per dimension: |
276+
| ``size`` | ``uint32_t[]`` | |
277+
| | | Restrictions: size[d] + offset[d] <= input->shape[d] |
278+
+---------------------+----------------+---------------------------------------------------------+
279+
| | | Rank of the sub tensor that is produced. Must be |
280+
| | | smaller or equal to the rank of the input tensor. If |
281+
| ``sub_tensor_rank`` | ``uint32_t`` | the ``sub_tensor_rank`` is smaller than the input rank, |
282+
| | | the dimensions with a size of 1 is removed in the |
283+
| | | output shape starting from the first dimension until |
284+
| | | the requested ``sub_tensor_rank`` value is reached. |
285+
+---------------------+----------------+---------------------------------------------------------+
286+
..
287+
288+
This function computes the new data pointer based on the offset vector and it sets
289+
the shape of the output tensor according to the size vector. The ``mem_stride`` fields
290+
are copied from the input to the output, so after this operation, the output tensor might
291+
not be a contiguous block of data.
292+
293+
The function also reduces the rank of the output tensor if requested by the
294+
configuration. Only the dimensions with a size of 1 can be removed. Data format and
295+
quantization parameters are copied from the input to the output tensor.
296+
297+
The capacity field of the output is the input capacity decremented with the same
298+
value as that used to increment the data pointer.
299+
300+
301+
302+
Conditions:
303+
304+
- ``in`` tensor must be valid
305+
- ``cfg`` structure fields must be aligned with ``in`` tensor shape (see :ref:`t_mli_sub_tensor_cfg_desc`)
306+
- ``out`` must point to a tensor structure. It will be completely filled by the function.
307+
308+
309+
Depending on the debug level (see section :ref:`err_codes`), this function performs a parameter
310+
check and returns the result as an ``mli_status`` code as described in section :ref:`kernl_sp_conf`.
309311

310312

311313
.. _num_of_accu_bits:

0 commit comments

Comments
 (0)