1================== 2Matrix Types 3================== 4 5.. contents:: 6 :local: 7 8.. _matrixtypes: 9 10Clang provides a C/C++ language extension that allows users to directly express 11fixed-size 2-dimensional matrices as language values and perform arithmetic on 12them. 13 14This feature is currently experimental, and both its design and its 15implementation are in flux. 16 17Draft Specification 18=================== 19 20Matrix Type 21----------- 22 23A matrix type is a scalar type with an underlying *element type*, a constant 24number of *rows*, and a constant number of *columns*. Matrix types with the same 25element type, rows, and columns are the same type. A value of a matrix type 26includes storage for ``rows * columns`` values of the *element type*. The 27internal layout, overall size and alignment are implementation-defined. 28 29The maximum of the product of the number of rows and columns is 30implementation-defined. If that implementation-defined limit is exceeded, the 31program is ill-formed. 32 33Currently, the element type of a matrix is only permitted to be one of the 34following types: 35 36* an integer type (as in C2x 6.2.5p19), but excluding enumerated types and ``_Bool`` 37* the standard floating types ``float`` or ``double`` 38* a half-precision floating point type, if one is supported on the target 39 40Other types may be supported in the future. 41 42Matrix Type Attribute 43--------------------- 44 45Matrix types can be declared by adding the ``matrix_type`` attribute to the 46declaration of a *typedef* (or a C++ alias declaration). The underlying type 47of the *typedef* must be a valid matrix element type. The 48attribute takes two arguments, both of which must be integer constant 49expressions that evaluate to a value greater than zero. The first specifies the 50number of rows, and the second specifies the number of columns. The underlying 51type of the *typedef* becomes a matrix type with the given dimensions and an 52element type of the former underlying type. 53 54If a declaration of a *typedef-name* has a ``matrix_type`` attribute, then all 55declaration of that *typedef-name* shall have a matrix_type attribute with the 56same element type, number of rows, and number of columns. 57 58Standard Conversions 59-------------------- 60 61The standard conversions are extended as follows. Note that these conversions 62are intentionally not listed as satisfying the constraints for assignment, 63which is to say, they are only permitted as explicit casts, not as implicit 64conversions. 65 66A value of matrix type can be converted to another matrix type if the number of 67rows and columns are the same and the value's elements can be converted to the 68element type of the result type. The result is a matrix where each element is 69the converted corresponding element. 70 71A value of any real type (as in C2x 6.2.5p17) can be converted to a matrix type 72if it can be converted to the element type of the matrix. The result is a 73matrix where all elements are the converted original value. 74 75If the number of rows or columns differ between the original and resulting 76type, the program is ill-formed. 77 78 79Arithmetic Conversions 80---------------------- 81 82The usual arithmetic conversions are extended as follows. 83 84Insert at the start: 85 86* If both operands are of matrix type, no arithmetic conversion is performed. 87* If one operand is of matrix type and the other operand is of a real type, 88 convert the real type operand to the matrix type 89 according to the standard conversion rules. 90 91Matrix Type Element Access Operator 92----------------------------------- 93 94An expression of the form ``E1 [E2] [E3]``, where ``E1`` has matrix type ``cv 95M``, is a matrix element access expression. Let ``T`` be the element type 96of ``M``, and let ``R`` and ``C`` be the number of rows and columns in ``M`` 97respectively. The index expressions shall have integral or unscoped 98enumeration type and shall not be uses of the comma operator unless 99parenthesized. The first index expression shall evaluate to a 100non-negative value less than ``R``, and the second index expression shall 101evaluate to a non-negative value less than ``C``, or else the expression has 102undefined behavior. If ``E1`` is a prvalue, the result is a prvalue with type 103``T`` and is the value of the element at the given row and column in the matrix. 104Otherwise, the result is a glvalue with type ``cv T`` and with the same value 105category as ``E1`` which refers to the element at the given row and column in 106the matrix. 107 108Programs containing a single subscript expression into a matrix are ill-formed. 109 110**Note**: We considered providing an expression of the form 111``postfix-expression [expression]`` to access columns of a matrix. We think 112that such an expression would be problematic once both column and row major 113matrixes are supported: depending on the memory layout, either accessing columns 114or rows can be done efficiently, but not both. Instead, we propose to provide 115builtins to extract rows and columns from a matrix. This makes the operations 116more explicit. 117 118Matrix Type Binary Operators 119---------------------------- 120 121Each matrix type supports the following binary operators: ``+``, ``-`` and ``*``. The ``*`` 122operator provides matrix multiplication, while ``+`` and ``-`` are performed 123element-wise. There are also scalar versions of the operators, which take a 124matrix type and the matrix element type. The operation is applied to all 125elements of the matrix using the scalar value. 126 127For ``BIN_OP`` in ``+``, ``-``, ``*`` given the expression ``M1 BIN_OP M2`` where 128at least one of ``M1`` or ``M2`` is of matrix type and, for `*`, the other is of 129a real type: 130 131* The usual arithmetic conversions are applied to ``M1`` and ``M2``. [ Note: if ``M1`` or 132 ``M2`` are of a real type, they are broadcast to matrices here. — end note ] 133* ``M1`` and ``M2`` shall be of the same matrix type. 134* The result is equivalent to Res in the following where col is the number of 135 columns and row is the number of rows in the matrix type: 136 137.. code-block:: c++ 138 139 decltype(M1) Res; 140 for (int C = 0; C < col; ++C) 141 for (int R = 0; R < row; ++R) 142 Res[R][C] = M1[R][C] BIN_OP M2[R][C]; 143 144Given the expression ``M1 * M2`` where ``M1`` and ``M2`` are of matrix type: 145 146* The usual arithmetic conversions are applied to ``M1`` and ``M2``. 147* The type of ``M1`` shall have the same number of columns as the type of ``M2`` has 148 rows. The element types of ``M1`` and ``M2`` shall be the same type. 149* The resulting type, ``MTy``, is a matrix type with the common element type, 150 the number of rows of ``M1`` and the number of columns of ``M2``. 151* The result is equivalent to ``Res`` in the following where ``EltTy`` is the 152 element type of ``MTy``, ``col`` is the number of columns, ``row`` is the 153 number of rows in ``MTy`` and ``inner`` is the number of columns of ``M1``: 154 155.. code-block:: c++ 156 157 MTy Res; 158 for (int C = 0; C < col; ++C) { 159 for (int R = 0; R < row; ++R) { 160 EltTy Elt = 0; 161 for (int K = 0; K < inner; ++K) { 162 Elt += M1[R][K] * M2[K][C]; 163 } 164 Res[R][C] = Elt; 165 } 166 167All operations on matrix types match the behavior of the element type with 168respect to signed overflows. 169 170With respect to floating-point contraction, rounding and environment rules, 171operations on matrix types match the behavior of the elementwise operations 172in the corresponding expansions provided above. 173 174Operations on floating-point matrices have the same rounding and floating-point 175environment behavior as ordinary floating-point operations in the expression's 176context. For the purposes of floating-point contraction, all calculations done 177as part of a matrix operation are considered intermediate operations, and their 178results need not be rounded to the format of the element type until the final 179result in the containing expression. This is subject to the normal restrictions 180on contraction, such as ``#pragma STDC FP_CONTRACT``. 181 182For the ``+=``, ``-=`` and ``*=`` operators the semantics match their expanded 183variants. 184 185Matrix Type Builtin Operations 186------------------------------ 187 188Each matrix type supports a collection of builtin expressions that look like 189function calls but do not form an overload set. Here they are described as 190function declarations with rules for how to construct the argument list types 191and return type and the library description elements from 192[library.description.structure.specifications]/3 in the C++ standard. 193 194Definitions: 195 196* *M*, *M1*, *M2*, *M3* - Matrix types 197* *T* - Element type 198* *row*, *col* - Row and column arguments respectively. 199 200 201``M2 __builtin_matrix_transpose(M1 matrix)`` 202 203**Remarks**: The return type is a cv-unqualified matrix type that has the same 204element type as ``M1`` and has the the same number of rows as ``M1`` has columns and 205the same number of columns as ``M1`` has rows. 206 207**Returns**: A matrix ``Res`` equivalent to the code below, where ``col`` refers to the 208number of columns of ``M``, and ``row`` to the number of rows of ``M``. 209 210**Effects**: Equivalent to: 211 212.. code-block:: c++ 213 214 M Res; 215 for (int C = 0; C < col; ++C) 216 for (int R = 0; R < row; ++R) 217 Res[C][R] = matrix[R][C]; 218 219 220``M __builtin_matrix_column_major_load(T *ptr, size_t row, size_t col, size_t columnStride)`` 221 222**Mandates**: ``row`` and ``col`` shall be integral constants greater than 0. 223 224**Preconditions**: ``columnStride`` is greater than or equal to ``row``. 225 226**Remarks**: The return type is a cv-unqualified matrix type with an element 227type of the cv-unqualified version of ``T`` and a number of rows and columns equal 228to ``row`` and ``col`` respectively. The parameter ``columnStride`` is optional 229and if omitted ``row`` is used as ``columnStride``. 230 231**Returns**: A matrix ``Res`` equivalent to: 232 233.. code-block:: c++ 234 235 M Res; 236 for (size_t C = 0; C < col; ++C) { 237 for (size_t R = 0; R < row; ++K) 238 Res[R][C] = ptr[R]; 239 ptr += columnStride 240 } 241 242 243``void __builtin_matrix_column_major_store(M matrix, T *ptr, size_t columnStride)`` 244 245**Preconditions**: ``columnStride`` is greater than or equal to the number of rows in ``M``. 246 247**Remarks**: The type ``T`` is the const-unqualified version of the matrix 248argument’s element type. The parameter ``columnStride`` is optional and if 249omitted, the number of rows of ``M`` is used as ``columnStride``. 250 251**Effects**: Equivalent to: 252 253.. code-block:: c++ 254 255 for (size_t C = 0; C < columns in M; ++C) { 256 for (size_t R = 0; R < rows in M; ++K) 257 ptr[R] = matrix[R][C]; 258 ptr += columnStride 259 } 260 261 262TODOs 263----- 264 265TODO: Does it make sense to allow M::element_type, M::rows, and M::columns 266where M is a matrix type? We don’t support this anywhere else, but it’s 267convenient. The alternative is using template deduction to extract this 268information. Also add spelling for C. 269 270Future Work: Initialization syntax. 271 272 273Decisions for the Implementation in Clang 274========================================= 275 276This section details decisions taken for the implementation in Clang and is not 277part of the draft specification. 278 279The elements of a value of a matrix type are laid out in column-major order 280without padding. 281 282We propose to provide a Clang option to override this behavior and allow 283contraction of those operations (e.g. *-ffp-contract=matrix*). 284 285TODO: Specify how matrix values are passed to functions. 286