294 lines · plain
1==================2Matrix Types3==================4 5.. contents::6 :local:7 8.. _matrixtypes:9 10Clang provides a C/C++ language extension that allows users to directly express11fixed-size 2-dimensional matrices as language values and perform arithmetic on12them.13 14This feature is currently experimental, and both its design and its15implementation are in flux.16 17Draft Specification18===================19 20Matrix Type21-----------22 23A matrix type is a scalar type with an underlying *element type*, a constant24number of *rows*, and a constant number of *columns*. Matrix types with the same25element type, rows, and columns are the same type. A value of a matrix type26includes storage for ``rows * columns`` values of the *element type*. The27internal layout, overall size and alignment are implementation-defined.28 29The maximum of the product of the number of rows and columns is30implementation-defined. If that implementation-defined limit is exceeded, the31program is ill-formed.32 33Currently, the element type of a matrix is only permitted to be one of the34following types:35 36* an integer type (as in C23 6.2.5p22), but excluding enumerated types, ``bool``,37 and ``_BitInt`` types whose width is not a power of 2;38* the standard floating types ``float`` or ``double``;39* a half-precision floating point type, if one is supported on the target.40 41Other types may be supported in the future.42 43Matrix Type Attribute44---------------------45 46Matrix types can be declared by adding the ``matrix_type`` attribute to the47declaration of a *typedef* (or a C++ alias declaration). The underlying type48of the *typedef* must be a valid matrix element type. The49attribute takes two arguments, both of which must be integer constant50expressions that evaluate to a value greater than zero. The first specifies the51number of rows, and the second specifies the number of columns. The underlying52type of the *typedef* becomes a matrix type with the given dimensions and an53element type of the former underlying type.54 55If a declaration of a *typedef-name* has a ``matrix_type`` attribute, then all56declarations of that *typedef-name* shall have a matrix_type attribute with the57same element type, number of rows, and number of columns.58 59Standard Conversions60--------------------61 62The standard conversions are extended as follows. Note that these conversions63are intentionally not listed as satisfying the constraints for assignment,64which is to say, they are only permitted as explicit casts, not as implicit65conversions.66 67A value of matrix type can be converted to another matrix type if the number of68rows and columns are the same and the value's elements can be converted to the69element type of the result type. The result is a matrix where each element is70the converted corresponding element.71 72A value of any real type (as in C23 6.2.5p14) can be converted to a matrix type73if it can be converted to the element type of the matrix. The result is a74matrix where all elements are the converted original value.75 76If the number of rows or columns differ between the original and resulting77type, the program is ill-formed.78 79 80Arithmetic Conversions81----------------------82 83The usual arithmetic conversions are extended as follows.84 85Insert at the start:86 87* If both operands are of matrix type, no arithmetic conversion is performed.88* If one operand is of matrix type and the other operand is of a real type,89 convert the real type operand to the matrix type90 according to the standard conversion rules.91 92Matrix Type Element Access Operator93-----------------------------------94 95An expression of the form ``E1 [E2] [E3]``, where ``E1`` has matrix type ``cv96M``, is a matrix element access expression. Let ``T`` be the element type97of ``M``, and let ``R`` and ``C`` be the number of rows and columns in ``M``98respectively. The index expressions shall have integral or unscoped99enumeration type and shall not be uses of the comma operator unless100parenthesized. The first index expression shall evaluate to a101non-negative value less than ``R``, and the second index expression shall102evaluate to a non-negative value less than ``C``, or else the expression has103undefined behavior. If ``E1`` is a prvalue, the result is a prvalue with type104``T`` and is the value of the element at the given row and column in the matrix.105Otherwise, the result is a glvalue with type ``cv T`` and with the same value106category as ``E1`` which refers to the element at the given row and column in107the matrix.108 109Programs containing a single subscript expression into a matrix are ill-formed.110 111**Note**: We considered providing an expression of the form112``postfix-expression [expression]`` to access columns of a matrix. We think113that such an expression would be problematic once both column and row major114matrixes are supported: depending on the memory layout, either accessing columns115or rows can be done efficiently, but not both. Instead, we propose to provide116builtins to extract rows and columns from a matrix. This makes the operations117more explicit.118 119Matrix Type Binary Operators120----------------------------121 122Given two matrixes, the ``+`` and ``-`` operators perform element-wise addition123and subtraction, while the ``*`` operator performs matrix multiplication.124``+``, ``-``, ``*``, and ``/`` can also be used with a matrix and a scalar125value, applying the operation to each element of the matrix.126 127Earlier versions of this extension did not support division by a scalar.128You can test for the availability of this feature with129``__has_extension(matrix_types_scalar_division)``.130 131For the expression ``M1 BIN_OP M2`` where132 133* ``BIN_OP`` is one of ``+`` or ``-``, one of ``M1`` and ``M2`` is of matrix134 type, and the other is of matrix type or real type; or135* ``BIN_OP`` is ``*``, one of ``M1`` and ``M2`` is of matrix type, and the136 other is of a real type; or137* ``BIN_OP`` is ``/``, ``M1`` is of matrix type, and ``M2`` is of a real type:138 139* The usual arithmetic conversions are applied to ``M1`` and ``M2``. [ Note: if ``M1`` or140 ``M2`` are of a real type, they are broadcast to matrices here. — end note ]141* ``M1`` and ``M2`` shall be of the same matrix type.142* The result is equivalent to Res in the following where col is the number of143 columns and row is the number of rows in the matrix type:144 145.. code-block:: c++146 147 decltype(M1) Res;148 for (int C = 0; C < col; ++C)149 for (int R = 0; R < row; ++R)150 Res[R][C] = M1[R][C] BIN_OP M2[R][C];151 152Given the expression ``M1 * M2`` where ``M1`` and ``M2`` are of matrix type:153 154* The usual arithmetic conversions are applied to ``M1`` and ``M2``.155* The type of ``M1`` shall have the same number of columns as the type of ``M2`` has156 rows. The element types of ``M1`` and ``M2`` shall be the same type.157* The resulting type, ``MTy``, is a matrix type with the common element type,158 the number of rows of ``M1`` and the number of columns of ``M2``.159* The result is equivalent to ``Res`` in the following where ``EltTy`` is the160 element type of ``MTy``, ``col`` is the number of columns, ``row`` is the161 number of rows in ``MTy`` and ``inner`` is the number of columns of ``M1``:162 163.. code-block:: c++164 165 MTy Res;166 for (int C = 0; C < col; ++C) {167 for (int R = 0; R < row; ++R) {168 EltTy Elt = 0;169 for (int K = 0; K < inner; ++K) {170 Elt += M1[R][K] * M2[K][C];171 }172 Res[R][C] = Elt;173 }174 175All operations on matrix types match the behavior of the element type with176respect to signed overflows.177 178With respect to floating-point contraction, rounding and environment rules,179operations on matrix types match the behavior of the elementwise operations180in the corresponding expansions provided above.181 182Operations on floating-point matrices have the same rounding and floating-point183environment behavior as ordinary floating-point operations in the expression's184context. For the purposes of floating-point contraction, all calculations done185as part of a matrix operation are considered intermediate operations, and their186results need not be rounded to the format of the element type until the final187result in the containing expression. This is subject to the normal restrictions188on contraction, such as ``#pragma STDC FP_CONTRACT``.189 190For the ``+=``, ``-=`` and ``*=`` operators the semantics match their expanded191variants.192 193Matrix Type Builtin Operations194------------------------------195 196Each matrix type supports a collection of builtin expressions that look like197function calls but do not form an overload set. Here they are described as198function declarations with rules for how to construct the argument list types199and return type and the library description elements from200[library.description.structure.specifications]/3 in the C++ standard.201 202Definitions:203 204* *M*, *M1*, *M2*, *M3* - Matrix types205* *T* - Element type206* *row*, *col* - Row and column arguments respectively.207 208 209``M2 __builtin_matrix_transpose(M1 matrix)``210 211**Remarks**: The return type is a cv-unqualified matrix type that has the same212element type as ``M1`` and has the same number of rows as ``M1`` has columns and213the same number of columns as ``M1`` has rows.214 215**Returns**: A matrix ``Res`` equivalent to the code below, where ``col`` refers to the216number of columns of ``M``, and ``row`` to the number of rows of ``M``.217 218**Effects**: Equivalent to:219 220.. code-block:: c++221 222 M Res;223 for (int C = 0; C < col; ++C)224 for (int R = 0; R < row; ++R)225 Res[C][R] = matrix[R][C];226 227 228``M __builtin_matrix_column_major_load(T *ptr, size_t row, size_t col, size_t columnStride)``229 230**Mandates**: ``row`` and ``col`` shall be integral constants greater than 0.231 232**Preconditions**: ``columnStride`` is greater than or equal to ``row``.233 234**Remarks**: The return type is a cv-unqualified matrix type with an element235type of the cv-unqualified version of ``T`` and a number of rows and columns equal236to ``row`` and ``col`` respectively. The parameter ``columnStride`` is optional237and if omitted ``row`` is used as ``columnStride``.238 239**Returns**: A matrix ``Res`` equivalent to:240 241.. code-block:: c++242 243 M Res;244 for (size_t C = 0; C < col; ++C) {245 for (size_t R = 0; R < row; ++K)246 Res[R][C] = ptr[R];247 ptr += columnStride248 }249 250 251``void __builtin_matrix_column_major_store(M matrix, T *ptr, size_t columnStride)``252 253**Preconditions**: ``columnStride`` is greater than or equal to the number of rows in ``M``.254 255**Remarks**: The type ``T`` is the const-unqualified version of the matrix256argument’s element type. The parameter ``columnStride`` is optional and if257omitted, the number of rows of ``M`` is used as ``columnStride``.258 259**Effects**: Equivalent to:260 261.. code-block:: c++262 263 for (size_t C = 0; C < columns in M; ++C) {264 for (size_t R = 0; R < rows in M; ++K)265 ptr[R] = matrix[R][C];266 ptr += columnStride267 }268 269 270TODOs271-----272 273TODO: Does it make sense to allow M::element_type, M::rows, and M::columns274where M is a matrix type? We don’t support this anywhere else, but it’s275convenient. The alternative is using template deduction to extract this276information. Also add spelling for C.277 278Future Work: Initialization syntax.279 280 281Decisions for the Implementation in Clang282=========================================283 284This section details decisions taken for the implementation in Clang and is not285part of the draft specification.286 287The elements of a value of a matrix type are laid out in column-major order288without padding.289 290We propose to provide a Clang option to override this behavior and allow291contraction of those operations (e.g. *-ffp-contract=matrix*).292 293TODO: Specify how matrix values are passed to functions.294