mlir/docs/Dialects/TOSA.md

   1 # Tensor Operator Set Architecture (TOSA) Dialect
   2
   3 [TOC]
   4
   5 ## Rationale
   6
   7 The MLIR TOSA dialect implements the [TOSA
   8 specification](https://developer.mlplatform.org/w/tosa/).  This document
   9 describes the decision process for how TOSA expresses operators in
  10 high level dialects.
  11
  12 TOSA was developed after parallel efforts to rationalize the top-down picture
  13 from multiple high-level frameworks, as well as a bottom-up view of different
  14 hardware target concerns (CPU, GPU and NPU), and reflects a set of choices
  15 that attempt to manage both sets of requirements.
  16
  17 ## TOSA and Tensor Level Expressiveness
  18
  19 TOSA endeavors to provide an operator set that tries to fulfil the following
  20 expressiveness goals at the *tensor level of abstraction* :
  21
  22 ### Complete
  23
  24 This is driven by the top-down perspective, needing to express as much of
  25 multiple high level frameworks fully in TOSA, as possible. This was originally
  26 done from an operator frequency analysis done upon dozens of high level
  27 networks in different frameworks, to select the most frequently occurring ones
  28 and establish a common set of tensor-level operators that could express them.
  29
  30 TOSA categorizes its operator set into classes and attempts to address major
  31 functional operations at the tensor level, including compute, reduction,
  32 elementwise transformations, comparison and control flow.
  33
  34 ### Minimal
  35
  36 This takes the bottom-up approach - keep the TOSA operator set minimal in
  37 order to bound the design of hardware, operator kernels, code generation
  38 strategies and associated considerations that effect the executability of TOSA
  39 content.
  40
  41 In this regard TOSA seeks to avoid creating compound operators, instead
  42 leaving it to compiler backend to fuse multiple TOSA ops if required. This
  43 choice also benefits the numerical precision goal, since it is easier to fuse the
  44 numerical functionality of successive operators, than to split the numerical
  45 functionality of a compound operator.
  46
  47 ### Numerical Precision
  48
  49 TOSA began as a means to address operator-level numerical precision for
  50 code generation and hardware development. It therefore incorporates precision
  51 detail into the operator set.
  52
  53 In this regard, TOSA operators are best understood as a combination of the visible
  54 quantization information embedded within an operation, together with the
  55 functional information about how that information is used, as described in the
  56 specification of the operation.
  57
  58 ## TOSA Operator Rationale
  59
  60 The general basis of selection of the operator set that constitutes TOSA is
  61 described in the TOSA specification document  under Section 1.3 Operator
  62 Selection. Explanation of the thinking behind some operators is listed here:
  63
  64 ### COND\_IF and WHILE\_LOOP
  65
  66 Several neural networks express conditional control flow at the tensor level.
  67 A survey of multiple high level frameworks indicated that conditional if and
  68 a loop construct are common in all major frameworks, with some variation.
  69 Since TOSA endeavors to be complete in expressing tensor level functionality
  70 including control flow, it implements these constructs.
  71
  72 The COND\_IF and WHILE\_LOOP operators implement such structured control
  73 flow forms and should be lowerable to corresponding ops in the scf dialect.
  74 Since the dialect seeks to remain isomorphic with an external, serialized form,
  75 the decision was to keep these ops in the dialect (as opposed to deferring
  76 completely to scf), and this may be re-evaluated if this turns out to not yield
  77 the expected value.
  78
  79 ## Using TOSA In A Compiler
  80
  81 The TOSA specification describes each operator in functional detail. It is
  82 expected that compilers that use TOSA will use its builders to construct the
  83 operators so that the quantization information for the operator is correctly
  84 generated.
  85
  86 The functional steps described in the pseudocode of the specification enables
  87 the construction of code generation for that operation, or decisions on the
  88 design of underlying hardware. The functional pseudocode also describes
  89 how the quantization parameters are utilized within the operation.
  90
  91 ### Quantization Parameters in Ops vs Tensors
  92
  93 TOSA uses the quantization parameters embedded in the input and output
  94 tensors to construct the quantization attributes that sit within the operator.
  95 Once these attributes are constructed, the quantization information within
  96 the tensors are no longer necessary for code generation.
  97
  98 This enables the tensors to be subsequently interpreted simply as contiguous
  99 buffers containing raw data, with no 'meta information' in the form of the
 100 quantization_type. Precision related manipulation of the input or output are
 101 instead described by the operator itself which describes, for example, when
 102 the zero point is applied, or when the scale multiplication is done.
 103
 104 However, TOSA does *not* eliminate the existing MLIR QuantOps quantization
 105 type information within the tensors; this leaves the choice of how to handle
 106 quantization information, to later backend code generation steps.
 107
 108 Maintaining the ability to overlap these different representations of
 109 quantization parameters (i.e. tensor-carried vs op-carried) is an important
 110 capability when considering progressive lowering between uses that expect one
 111 scheme vs the other.
 112
 113 ## Operation definitions
 114
 115 [include "Dialects/TosaOps.md"]