Skip to content

Commit e742f3c

Browse files
dzakharJaccovG
dzakhar
authored and
JaccovG
committed
Restructured documentation
* Revision history for draft version was removed. Minor typos in the pooling and convolution description * Debug modes description is actualized * Doc: Getting started part has been actualized a little * MLI ReST restructured documentation
1 parent a9dd4dd commit e742f3c

File tree

148 files changed

+3963
-4002
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

148 files changed

+3963
-4002
lines changed

‎doc/documents/mli_api_desc/arithmetic_details.rst‎ renamed to ‎doc/documents/MLI_FP_data_format/MLI_FP_data_format.rst‎

Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,13 @@
1-
Arithmetic Details
2-
------------------
1+
.. _mli_fpd_fmt:
2+
3+
MLI Fixed-Point Data Format
4+
---------------------------
35

46
The MLI Library is targeting ARCv2DSP based platform and implies
57
efficient usage of its DSP Features. For this reason, there is some
68
specificity of basic data types and arithmetical operations using it
79
in comparison with operations using float-point values.
810

9-
.. _mli_fpd_fmt:
10-
11-
MLI Fixed-Point Data Format
12-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
13-
1411
Default MLI Fixed-point data format (represented by tensors of
1512
``MLI_EL_FX_8`` and ``MLI_EL_FX_16`` element types) reflects general signed
1613
values interpreted by typical Q notation [1,2]. The following
@@ -23,14 +20,23 @@ MLI Fixed-Point Data Format
2320
non-sign bits are assumed to hold an integer part.
2421

2522
.. note::
26-
For more information regarding Q notation, see entries [1] & [2] of :ref:`refs`.
27-
23+
For more information regarding Q notation, see
24+
25+
- `Q Notation`_
26+
27+
- `Q Notation tips and tricks`_
28+
29+
.. _Q notation: https://en.wikipedia.org/wiki/Q_(number_format)
30+
31+
.. _Q Notation tips and tricks: http://x86asm.net/articles/fixed-point-arithmetic-and-tricks/
32+
33+
..
2834
2935
Data storage
30-
^^^^^^^^^^^^
36+
~~~~~~~~~~~~
3137

3238
The container of the tensor’s values is always signed two’s
33-
complemented integer numbers: 8 bit for ``MLI_EL_FX_8`` (also referred to as ``fx8``) and
39+
complemented integer numbers: 8 bit for ``MLI_EL_FX_8`` (also referred to as ``fx8``) and
3440
16 bit for ``MLI_EL_FX_16`` (also referred to as ``fx16``). ``mli_tensor`` keeps only number
3541
of fractional bits (see ``fx.frac_bits`` in :ref:`mli_el_prm_u`),
3642
which corresponds to the second designation above.
@@ -82,7 +88,7 @@ Data storage
8288
.. _op_fx_val:
8389

8490
Operations on FX values
85-
^^^^^^^^^^^^^^^^^^^^^^^
91+
~~~~~~~~~~~~~~~~~~~~~~~
8692

8793
Arithmetical operations are actually performed on signed integers
8894
according to the rules for two’s complemented integer numbers. Q
@@ -92,7 +98,7 @@ Operations on FX values
9298
.. _data_fmt_conv:
9399

94100
Data Format Conversion
95-
''''''''''''''''''''''
101+
^^^^^^^^^^^^^^^^^^^^^^
96102

97103
Conversion between real values and fx value might be performed
98104
according to the following formula:
@@ -163,15 +169,15 @@ Where:
163169
``Round(0x24>>(4–1)) = Round(0x24>>3) = (0x24 + (1<<(3-1))) >> 3 = 0x28>>3 = 0x5 in Q.1(2.5)``
164170

165171
Addition and Subtraction
166-
''''''''''''''''''''''''
172+
^^^^^^^^^^^^^^^^^^^^^^^^
167173

168174
In fixed point arithmetic, addition and subtraction are performed as
169175
they are for general integer values but only when the input values
170176
are in the same format. Otherwise, ensure that you perform conversion
171177
to bring the input values into the same format before operation.
172178

173179
Multiplication
174-
''''''''''''''
180+
^^^^^^^^^^^^^^
175181

176182
For multiplication input operands do not have to be of the same
177183
format. The width of the integer part of the result is the sum of
@@ -203,7 +209,7 @@ Multiplication
203209
result.
204210

205211
Division
206-
''''''''
212+
^^^^^^^^
207213

208214
For division, input operands also do not have to be of the same
209215
format. The result has a format containing the difference of bits in
@@ -214,8 +220,6 @@ Division
214220
- For a dividend ``x`` in Q16.16 format and a divisor y in Q7.10 format,
215221
the format of the result ``x/y`` is Q(16-7).(16-10), or Q9.6 format.
216222

217-
\
218-
219223
- For a dividend ``x`` in Q7.8 format and a divisor y in Q3.12 format, the
220224
format of the result ``x/y`` is in Q4.-4 format.
221225

@@ -229,7 +233,7 @@ Division
229233
significant bits) is required.
230234

231235
Accumulation
232-
''''''''''''
236+
^^^^^^^^^^^^
233237

234238
Even single addition might result in overflow if all bits of operands
235239
are used and both of them hold the maximum (or minimum) values. It
@@ -258,14 +262,14 @@ Accumulation
258262
operation.
259263

260264
ARCv2DSP Implementation Specifics
261-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
265+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
262266

263267
The MLI Library is designed keeping performance in mind as one of the
264268
main goals. This section deals with manual model adaptation of MLI
265269
library.
266270

267271
Bias for MAC-based Kernels
268-
''''''''''''''''''''''''''
272+
^^^^^^^^^^^^^^^^^^^^^^^^^^
269273

270274
MAC based kernels (convolutions, fully connected, recurrent, etc)
271275
typically use several input tensors including input feature map,
@@ -285,7 +289,7 @@ Bias for MAC-based Kernels
285289
must be less or equal to 10 (since 7+3=10) for correct bias.
286290

287291
Configurability of Output Tensors Fractional Bits
288-
''''''''''''''''''''''''''''''''''''''''''''''''''
292+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
289293

290294
Not all primitives provide possibility to configure output tensor
291295
format – some of them derive it based on inputs or used algorithm,
@@ -311,7 +315,7 @@ Configurability of Output Tensors Fractional Bits
311315
Output configurability is specified in description for each primitive.
312316

313317
Quantization: Influence of Accumulator Bit Depth
314-
''''''''''''''''''''''''''''''''''''''''''''''''
318+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
315319

316320
The MLI Library applies neither saturation nor post-multiplication
317321
shift with rounding in accumulation. Saturation is performed only for

‎doc/documents/MLI_helpers/MLI_helpers.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _mli_helpers:
2+
3+
MLI helpers
4+
===========
5+
6+
This is a set of utility functions for getting information from data
7+
structures and performing various operations on it.
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Contents:
12+
13+
get_basic_elem_size.rst
14+
count_no_elements.rst
15+
point_to_sub_tensor.rst
16+
convert_tensor.rst

‎doc/documents/MLI_helpers/convert_tensor.rst‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
.. _conv_tensor:
2+
3+
Convert Tensor
4+
~~~~~~~~~~~~~~
5+
6+
This function copies elements from input tensor to output with data
7+
conversion according to the output tensor type parameters.
8+
9+
For example, the function can:
10+
11+
- convert data according to new element type: ``fx16`` to ``fx8`` and backward
12+
13+
- change data according to new data parameter: increase/decrease the
14+
number of fractional bits while keeping the same element type for
15+
FX data
16+
17+
..
18+
19+
Conversion is performed using
20+
21+
- rounding when the number of significant bits increases.
22+
23+
- saturation when the number of significant bits decreases.
24+
25+
..
26+
27+
This operation does not change tensor shape. It copies it from input
28+
to output.
29+
30+
Kernel can perform in-place computation, but only for conversions
31+
without increasing data size, so that that it does not lead to
32+
undefined behavior. Therefore, output and input might point to exactly the
33+
same memory (but without shift) except ``fx8`` to ``fx16`` conversion.
34+
In-place computation might affect performance for some platforms.
35+
36+
.. _api-18:
37+
38+
API
39+
^^^
40+
41+
+-----------------------+-----------------------+----------------------------------------------+
42+
| **Prototype** |.. code:: c |
43+
| | |
44+
| | mli_status mli_hlp_convert_tensor(mli_tensor *in, mli_tensor *out); |
45+
| | |
46+
+-----------------------+-----------------------+----------------------------------------------+
47+
| **Parameters** | ``in`` | [IN] Pointer to input |
48+
| | | tensor |
49+
+-----------------------+-----------------------+----------------------------------------------+
50+
| | ``start_dim`` | [OUT] Pointer to |
51+
| | | output tensor |
52+
+-----------------------+-----------------------+----------------------------------------------+
53+
| **Returns** | ``status code`` | |
54+
+-----------------------+-----------------------+----------------------------------------------+
55+
56+
.. _conditions-for-applying-the-function-7:
57+
58+
Conditions for Applying the Function
59+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
60+
61+
- Input must be a valid tensor (see :ref:`mli_tns_struct`).
62+
63+
- Before processing the output tensor must contain a valid pointer to a
64+
buffer with sufficient capacity enough for storing the result
65+
(that is, the total amount of elements in input tensor).
66+
67+
- The output tensor also must contain valid element type and its
68+
parameter (``el_params.fx.frac_bits``)
69+
70+
- Before processing, the output tensor does not have to contain valid
71+
shape and rank - they are copied from input tensor.
72+

‎doc/documents/MLI_helpers/count_no_elements.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
.. _count_no_elem:
2+
3+
Count Number of Elements
4+
~~~~~~~~~~~~~~~~~~~~~~~~~
5+
6+
Function counts the number of elements in a tensor starting from the
7+
provided dimension number (dimension numbering starts from 0):
8+
9+
.. math:: num\_ of\_ elements = shape\lbrack start\_ dim\rbrack\ *shape\lbrack start\_ dim + 1\rbrack*\ldots*shape\lbrack last\_ dim\rbrack
10+
11+
..
12+
13+
Where:
14+
15+
``num_of_elements`` - Number of accounting elements
16+
17+
``shape`` - Shape of tensor
18+
19+
``start_dim`` – Start dimension for counting
20+
21+
``last_dim`` - Last dimension of tensor (tensor rank-1)
22+
23+
Function calculates total number of elements in case
24+
``start_dim = 0``. Function returns 0 if conditions listed
25+
in the following API are violated.
26+
27+
.. _api-16:
28+
29+
API
30+
^^^
31+
32+
+-----------------------+-----------------------+-------------------------------------------------+
33+
| **Prototype** |.. code:: c |
34+
| | |
35+
| | uint32_t mli_hlp_count_elem_num(mli_tensor *in, uint32_t start_dim) |
36+
+-----------------------+-----------------------+-------------------------------------------------+
37+
| **Parameters** | ``in`` | [IN] Pointer to input tensor |
38+
+-----------------------+-----------------------+-------------------------------------------------+
39+
| | ``start_dim`` | [IN] Start dimension for counting |
40+
+-----------------------+-----------------------+-------------------------------------------------+
41+
| **Returns** | ``Number of elements``| |
42+
+-----------------------+-----------------------+-------------------------------------------------+
43+
44+
.. _conditions-for-applying-the-function-5:
45+
46+
Conditions for Applying the Function
47+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
48+
49+
- Input must contain valid rank (less then ``MLI_MAX_RANK``).
50+
51+
- ``start_dim`` must be less than or equal to input rank

‎doc/documents/MLI_helpers/get_basic_elem_size.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. _get_elm_size:
2+
3+
Get Basic Element Size
4+
~~~~~~~~~~~~~~~~~~~~~~
5+
6+
This function returns size of tensor basic element in bytes. It
7+
returns 0 if conditions listed the following API are violated.
8+
9+
.. _api-15:
10+
11+
API
12+
^^^
13+
14+
+-----------------------+-----------------------+-----------------------+
15+
| |.. code:: c |
16+
| | |
17+
| **Prototype** | uint32_t mli_hlp_count_elem_num |
18+
| | (mli_tensor *in) |
19+
| | |
20+
+-----------------------+-----------------------+-----------------------+
21+
| | | |
22+
| **Parameters** | ``in`` | [IN] Pointer to input |
23+
| | | tensor |
24+
+-----------------------+-----------------------+-----------------------+
25+
| **Returns** | Size of basic element |
26+
| | in bytes |
27+
+-----------------------+-----------------------+-----------------------+
28+
29+
.. _conditions-for-applying-the-function-4:
30+
31+
Conditions for Applying the Function
32+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
33+
34+
The function must point to the tensor of supported element type (see
35+
:ref:`mli_elm_enum`).
36+

0 commit comments

Comments
 (0)