[Matrix] Add draft specification for matrix support in Clang.

[fhahn]

Summary

This patch documents the planned matrix support in Clang, based on the
draft specification discussed on cfe-dev in the 'Matrix Support in
Clang' thread.

Latest draft spec sent to cfe-dev: http://lists.llvm.org/pipermail/cfe-dev/2020-February/064742.html
Discussion thread January: http://lists.llvm.org/pipermail/cfe-dev/2020-January/064206.html
Discussion thread March: http://lists.llvm.org/pipermail/cfe-dev/2020-March/064834.html

[fhahn]

Update according to comments on cfe-dev.

[fhahn]

Update arithmetic conversion rules after recent discussion on cfe-dev.

[fhahn]

Specify that standard conversion rules do not apply to assignments for matrix types.

[fhahn]

Update standard conversion wording as suggested by @rjmccall

[SjoerdMeijer]

clang/docs/MatrixSupport.rst

254 ↗

(On Diff #255341)

Hi Florian, just reading this for the first time, this is cool stuff, and just a drive-by comment:

this section, Example, looks like a good candidate to be moved to the "Matrixes" section in
clang/docs/LanguageExtensions.rst. This is Clang/LLVM specific, may not be that relevant for a language draft spec? But anyway, it may also be some of the user-facing examples missing in the language extension doc.

[fhahn]

clang/docs/MatrixSupport.rst

254 ↗

(On Diff #255341)

Ah yes, it seems like the LLVM IR lowering does not fit either here or in LanguageExtensions. It might be good to move the example to LanguageExtnesions though.

[rjmccall]

Scanned through the first bit.

clang/docs/LanguageExtensions.rst

500

This should include just a bit more detail about the extension. I would suggest:

Clang supports matrix types as an experimental extension. See :refmatrices` for more details.

clang/docs/MatrixSupport.rst

3 ↗

(On Diff #255341)

This extension should be called something like "Matrices" or "Matrix Types". The "X Support" name makes it sound like it's a support layer for some external technology.

12 ↗

(On Diff #255341)

1. "Clang provides a C/C++ language extension that allows users to directly express fixed-size matrices as language values and perform arithmetic on them."

2. This document *is* the specification, there's nothing to cross-reference it.

14 ↗

(On Diff #255341)

"This feature is currently experimental, and both its design and its implementation are in flux."

30 ↗

(On Diff #255341)

You can assume the existence of a hypothetical external language specification for GNU attribute syntax, so these starting paragraphs whittle down to:

Matrix types can be declared by adding the matrix_type attribute to the declaration of a typedef (or a C++ alias declaration). The underlying type of the typedef must be an unqualified integer or floating-point type. The attribute takes two arguments, both of which must be integer constant expressions that evaluate to a value greater than zero. The first specifies the number of rows, and the second specifies the number of columns. The underlying type of the typedef becomes a matrix type with the given dimensions and an element type of the former underlying type.

The paragraph about redeclarations is good.

48 ↗

(On Diff #255341)

I would put this first before getting into the spelling. You can also put the stuff about implementation limits on dimensions in here.

55 ↗

(On Diff #255341)

Do you actually want to guarantee this layout in the language specification? I would just say that a matrix includes storage for rows * columns elements but that the interior layout and overall size and alignment are implementation-defined.

57 ↗

(On Diff #255341)

These are both important to include, but they're unrelated and shouldn't be in the same sentence.

64 ↗

(On Diff #255341)

That doesn't belong in a language specification, but you could reasonably add a non-normative section at the end about the decisions that Clang currently makes for things like size, alignment, internal layout, and argument/result conventions.

106 ↗

(On Diff #255341)

It would be better to say explicitly that "The index expressions shall..."

110 ↗

(On Diff #255341)

I'd put all this like:

An expression of the form `E1 [E2] [E3], where E1 has matrix type cv M, is a matrix element access expression. Let T be the element type of M, and let R and C be the number of rows and columns in M respectively. The index expressions shall have integral or unscoped enumeration type and shall not be uses of the comma operator unless parenthesized. The first index expression shall evaluate to a non-negative value less than R, and the second index expression shall evaluate to a non-negative value less than C, or else the expression has undefined behavior. If E1 is a prvalue, the result is a prvalue with type T and is the value of the element at the given row and column in the matrix. Otherwise, the result is a glvalue with type cv T and with the same value category as E1` which refers to the element at the given row and column in the matrix.

118 ↗

(On Diff #255341)

You should add a normative paragraph saying that a program is ill-formed if it insufficiently subscripts into a matrix.

[fhahn]

Address @rjmccall comments.

In D76612#1975719, @rjmccall wrote:

Scanned through the first bit.

Thanks a lot! I hope I managed to address the comments adequately.

clang/docs/MatrixSupport.rst

3 ↗

(On Diff #255341)

I changed it to "Matrix Types"

[fhahn]

clang/docs/MatrixSupport.rst

30 ↗

(On Diff #255341)

Thanks, that helps to simplify this section a lot.

48 ↗

(On Diff #255341)

Sounds good! Moved.

57 ↗

(On Diff #255341)

I moved the scalar type bit to the first sentence and move the part about the alignment to a separate sentence stating that the layout overall size and alignment are implementation defined.

64 ↗

(On Diff #255341)

I've added a new Decisions for the Implementation in Clang section

110 ↗

(On Diff #255341)

Updated, thanks.

118 ↗

(On Diff #255341)

I added the following

Programs containing a single subscript expression into a matrix are ill-formed.

[rjmccall]

Reading through the rest of the spec.

clang/docs/LanguageExtensions.rst

500

If we're calling the extension "matrix types", that should be reflected in this section name and in the file name.

clang/docs/MatrixSupport.rst

28 ↗

(On Diff #257025)

No need to italicize "element type" the second time.

The italics introduce a term, so consider italicizing "rows" and "columns" as well in the first sentence.

39 ↗

(On Diff #257025)

Maybe break the TODOs here into their own sections, which would come much later.

70 ↗

(On Diff #257025)

I don't think you need to list out the kinds of promotion and conversion here, and it doesn't make sense to define the "resulting type" this way when it's really a parameter. I'd just say:

A value of matrix type can be converted to another matrix type if the number of rows and columns are the size and the value's elements can be converted to the element type of the result type. The result is a matrix where each element is the converted corresponding element.

A value of non-matrix type can be converted to a matrix type if it can be converted to the element type of the matrix. The result is a matrix where all elements are the converted original value.

126 ↗

(On Diff #257025)

I don't think this paragraph adds anything, and the restriction is kindof weird — it's just a restriction on when to consider applying these rules, rather than a restriction with absolute significance.

Also, "arithmetic type" includes unscoped enumeration types in both C and C++.

129 ↗

(On Diff #257025)

Here I think you can say "where at least one of M1 or M2 is of matrix type and, for *, the other is of arithmetic type".

I think you'll need to separately describe the restrictions on +=, -=, and *=, but you should be able to say that the semantics are as if for the expansion.

176 ↗

(On Diff #257025)

"builtin" should be capitalized here.

211 ↗

(On Diff #257025)

This name sounds like it's loading a column, when I think you're saying that the memory has to be in column-major order.

I would call stride something like columnStride to make it clear that it's the stride between columns, as opposed to a stride between the elements within a column, which is also something that's theoretically interesting.

Should stride be an optional argument to make it easier to write the (I expect) common case where the matrix is dense?

[fhahn]

Address latest comments, thanks again!

[fhahn]

clang/docs/MatrixSupport.rst

39 ↗

(On Diff #257025)

Done, I've moved the TODOs to a TODO section just after the builtins section.

70 ↗

(On Diff #257025)

I've kept the first paragraph (including the exclusion of assignment) and replaced the second with your suggestion.

129 ↗

(On Diff #257025)

I added the following at the end of the section

For the `+=, -= and *=` operators the semantics match their expanded variants.

211 ↗

(On Diff #257025)

This name sounds like it's loading a column, when I think you're saying that the memory has to be in column-major order.

Yes that is correct. Maybe __builtin_matrix_columnwise_load would be slightly better?

Should stride be an optional argument to make it easier to write the (I expect) common case where the matrix is dense?

Yes that would be very convenient, especially now that casting between element wise pointers and matrixes is not allowed. I've added a sentence to the remarks for both the load and store builtins.

[rjmccall]

clang/docs/MatrixSupport.rst

211 ↗

(On Diff #257025)

Yes that is correct. Maybe __builtin_matrix_columnwise_load would be slightly better?

The term of art is "column-major"; I don't think avoiding an "extra word" is a good enough reason to invent something else. __builtin_matrix_column_major_load sounds fine to me.

clang/docs/MatrixTypes.rst

80

You should standardize on one term and then be clear what you mean by it. Here you're saying "integer or floating point type", but elsewhere you use "arithmetic type". Unfortunately, the standard terms mean somewhat different things in different standards: "integer" includes enums in C but not in C++, "arithmetic" doesn't include complex types in C++ (although it does by extension in Clang), etc. I think for operands you probably want arithmetic types in the real domain (which in Clang is isRealType()). However, you'll want to use a narrower term for the restriction on element types because Clang does support fixed-point types, but you probably don't want to support matrices of them quite yet (and you may not want to allow matrices of bools, either).

Also, your description of the scalar conversions no longer promotes them to matrix type.

124

They also have to have the same element types, right? So they have to be the same types?

139

Same point about element types.

142

The easier way to put this now is that it's a matrix type whose element type is the common element type, but with the number of rows of M1 and the number of columns of M2.

153

inner is not defined.

165

This is about rounding, not rounding "errors".

The definition of matrix multiply you've written it above would actually permit an FMA under C's default rules.

More broadly, I think you need to define how the FP contraction and environment rules affect matrix arithmetic expressions. If FP contraction is enabled, can S * M1 + M2 perform elementwise FMAs?

[fhahn]

Address latest comments, thanks!

[fhahn]

clang/docs/MatrixTypes.rst

80

You should standardize on one term and then be clear what you mean by it. Here you're saying "integer or floating point type", but elsewhere you use "arithmetic type". Unfortunately, the standard terms mean somewhat different things in different standards: "integer" includes enums in C but not in C++, "arithmetic" doesn't include complex types in C++ (although it does by extension in Clang), etc. I think for operands you probably want arithmetic types in the real domain (which in Clang is isRealType()). However, you'll want to use a narrower term for the restriction on element types because Clang does support fixed-point types, but you probably don't want to support matrices of them quite yet (and you may not want to allow matrices of bools, either).

I've added the following to the Matrix Type section:
A *matrix element type* must be a real type (as in C99 6.2.5p17) excluding enumeration types or an implementation-defined half-precision floating point type, otherwise the program is ill-formed.

Other places are updated to use a valid matrix element type instead.

I think we explicitly want to allow half-precision types (like __fp16 and Float16 in Clang). I think by referring to real type as in the C99 spec, we naturally exclude Clang's fixed-point types and bool, right?

Also, your description of the scalar conversions no longer promotes them to matrix type.

Right, I think we can just refer to the standard conversion rules here, as in

If one operand is of matrix type and the other operand is of a valid matrix element type, convert the non-matrix type operand to the matrix type according to the standard conversion rules.

124

Yes, for 2 operands of a matrix type, they should be the same types now. Changed to M1 and M2 shall be of the same matrix type.

139

Added

The element types of `M1 and M2` shall be the same type

142

Replaced with

The resulting type, MTy, is a matrix type with the common element type, the number of rows of M1 and the number of columns of M2.

153

Should be something like and inner is the number of columns of M1``

165

This is about rounding, not rounding "errors".

Fixed.

The definition of matrix multiply you've written it above would actually permit an FMA under C's default rules.

The goal of the wording it to match the existing behavior for the expanded version for compatibility reasons.I think Clang currently does not emit FMAs without contraction explicitly enabled, but GCC emits FMAs without contraction explicitly enabled for something like A * B + C. I think the current wording allows for both, following the reasoning for both Clang's and GCC's current behavior for the single element case.

More broadly, I think you need to define how the FP contraction and environment rules affect matrix arithmetic expressions. If FP contraction is enabled, can S * M1 + M2 perform elementwise FMAs?

FP contraction and environment rules should match the corresponding expansions. So with fp-contraction enabled, S * M1 + M2. I re-worded the paragraph and hopefully it is clearer now:

With respect to floating-point contraction, rounding and environment rules, operations on matrix types match the behavior of the elementwise operations in the corresponding expansions provided above.

I've moved the part of the clang option to the Decision for the Implementation in Clang section.

[fhahn]

Rename builtin_matrix_columnwise_{load,store} => builtin_matrix_column_major_{load,store}

[SjoerdMeijer]

clang/docs/MatrixTypes.rst

13

Would it be good to set expectations here or in the section below: define that we're talking about 2-dimensional m × n matrices?

26

typo: ype -> type

28

above you're using *element type* and here *matrix element type*. Since hopefully we're talking about the same things, "matrix *element type*" would be more consistent.

But this is just a nit, my main question is about the types:
why not e.g. define this to be the C11 types, that include _FloatN types, so that we can include N=16? Or is this intentionally omitted? I haven't even checked if this is supported in the architecture extension, but might make sense? And also, an element type cannot be an integer type?

[fhahn]

Fix typo, remove a 2 places where underlying element type was used, move C portion of the example to LanguageExtensions.rst, drop the rest of the example.
:

[fhahn]

clang/docs/MatrixTypes.rst

13

I've changed it to fixed-size 2-dimensional matrices. I think the type definition below should be already clear enough about being 2 dimensional.

28

above you're using *element type* and here *matrix element type*. Since hopefully we're talking about the same things, "matrix *element type*" would be more consistent.

Yes it is referring to the same thing. I had a look at most uses, and in most cases element type is used to refer to the element type of a given matrix type. In that context it seems a bit verbose to use matrix element type, although I am more than happy to change that if it helps with clarifying things.

I intentionally used matrix element type in Arithmetic Conversions, because there it is standing on its own and refers exactly to the set of types defined as valid matrix element types here.

why not e.g. define this to be the C11 types, that include _FloatN types, so that we can include N=16? Or is this intentionally omitted? I haven't even checked if this is supported in the architecture extension, but might make sense?

I couldn't find any reference to _FloatN types in the C11 draft version I checked. Do you by any chance have a reference to the _FloatN types?

And also, an element type cannot be an integer type?

The current definition should include it (real types include integer and real floating point types according to C99 6.2.5p17). I don't think there is any reason to exclude them I think.

[fhahn]

Drop another instance of underlying element type.

[SjoerdMeijer]

clang/docs/MatrixTypes.rst

28

why not e.g. define this to be the C11 types, that include _FloatN types, so that we can include N=16? Or is this intentionally omitted? I haven't even checked if this is supported in the architecture extension, but might make sense?

I couldn't find any reference to _FloatN types in the C11 draft version I checked. Do you by any chance have a reference to the _FloatN types?

Sorry, I was a bit imprecise here, it's an extension of C11: ISO/IEC TS 18661-3:2015.
My thinking was it would be cool to support the "proper" half-precision type. I thought about this, because of "or an implementation-defined half-precision" mentioned just below here, of which probably __fp16 is an example. If you refer to the C99 types, you probably don't even need to mention this (although it won't do any harm)?

And also, an element type cannot be an integer type?

The current definition should include it (real types include integer and real floating point types according to C99 6.2.5p17). I don't think there is any reason to exclude them I think.

Ok, cheers, wrote this from memory (forgot this), and didn't check the standard.

[fhahn]

clang/docs/MatrixTypes.rst

28

Sorry, I was a bit imprecise here, it's an extension of C11: ISO/IEC TS 18661-3:2015.
My thinking was it would be cool to support the "proper" half-precision type. I thought about this, because of "or an implementation-defined half-precision" mentioned just below here, of which probably __fp16 is an example. If you refer to the C99 types, you probably don't even need to mention this (although it won't do any harm)?

I am not sure what the exact wording should be, but the intention is to include both __fp16 and _Float16. I was hoping that would be covered as is, but I would be happy to clarify (unfortunately it is not entirely clear to me how to best word this)

[rjmccall]

clang/docs/MatrixTypes.rst

80

I think we explicitly want to allow half-precision types (like __fp16 and Float16 in Clang). I think by referring to real type as in the C99 spec, we naturally exclude Clang's fixed-point types and bool, right?

C says:

The integer and real floating types are collectively called *real types*.

The type char, the signed and unsigned integer types, and the enumerated types are collectively called *integer types*.

The standard and extended unsigned integer types are collectively called *unsigned integer types*.

The type _Bool and the unsigned integer types that correspond to the standard signed integer types are the *standard unsigned integer types*.

Embedded C (TR 18037) says:

Clause 6.2.5 - Types, paragraph 17: change last sentence as follows.

Integer, fixed-point and real floating types are collectively called *real types*.

So you'll have to explicitly exclude enumerated types, _Bool, and the fixed-point types.

[SjoerdMeijer]

clang/docs/MatrixTypes.rst

28

Ah, okay, I got it. How about a simple enumeration, e.g.:

A *matrix element type* must be a C99 real type, excluding enumeration types, the C11 ISO/IEC TS 18661 _Float16 type, the ARM ACLE __fp16 type, or an implementation-defined half-precision floating point type, otherwise the program is ill-formed.

30

Now I am wondering if this requires some explanations on binary operations for these implemenation-defined types? For example, for __fp16 and matrices with this __fp16 element type, I assume arithmetic is performed in at least the (single) floating-point precision. So I guess in section "Arithmetic Conversions" a rule needs to be added that the conversion of these implementation defined types need to performed?

[fhahn]

Update list of types excluded from real types, thanks!

clang/docs/MatrixTypes.rst

28

Given that there are a few different half-precision floating point types with various levels of support in different compilers, I would prefer not to explicitly list them at the moment, while making it clear that they can also be supported. AFAIK there's work in progress to add Bfloat support to clang and I think we also would want to support that type in the future.

30

I don't think we need to specifically discuss the implementation defined types here, as the conversions and binary operator definitions are framed in terms of the existing rules for the element types used. I am potentially missing something, but with the current wording the conversions for __fp16 would use the conversion rules for that type and the binary operators would use the arithmetic rules for it.

80

Ah thanks, I missed TR 18037. Sorry about that! I've updated the wording as suggested.

[rjmccall]

clang/docs/MatrixTypes.rst

30

Yeah, for the scalar conversions / scalar operands, you should just say that the source has to be a real type and not otherwise restrict it. All of those types should already be convertible to any matrix element type.

[fhahn]

Update wording to allow any real type for scalar -> matrix conversion and scalar,matrix binary ops.

[fhahn]

clang/docs/MatrixTypes.rst

30

Thanks, I've updated the wording to ensure the scalar values are of a real type in the scalar -> matrix conversion and scalar, matrix binary operator contexts. I hope that is enough to clarify things.

[rjmccall]

clang/docs/LanguageExtensions.rst

511

This is kindof an unnecessarily unreadable example. I know you haven't decided on calling convention treatment yet, but maybe the leading example could be just a little ahead of the implementation and just take the matrices as arguments and then return the result.

clang/docs/MatrixTypes.rst

30

This would be clearer as something like:

Currently, the element type of a matrix is only permitted to be one of the following types:

• an integer type (as in C2x 6.2.5p19), but excluding enumerated types and _Bool
• a standard floating type (as in C2x 6.2.5p10)
• a half-precision floating point type, if one is supported on the target

Other types may be supported in the future.

Although I don't know if you actually want to unconditionally support long double; you might just want to say "the standard floating types float and double".

63

s/size/same/

67

"A value of any real type (as in C2x 6.2.5p17) can be converted..."

168

The expansions have a lot of statement boundaries that contraction wouldn't be allowed across. I'd suggest saying something like:

Operations on floating-point matrices have the same rounding and floating-point environment behavior as ordinary floating-point operations in the expression's context. For the purposes of floating-point contraction, all calculations done as part of a matrix operation are considered intermediate operations, and their results need not be rounded to the format of the element type until the final result in the containing expression. This is subject to the normal restrictions on contraction, such as #pragma STDC FP_CONTRACT.

217

"omitted".

I would expect these operands to have type either size_t or ptrdiff_t. Of course it only really matters for columnStride.

[fhahn]

Update wordings as suggested, thanks!

clang/docs/LanguageExtensions.rst

511

I wasn't sure if that would be fine, but it indeed makes things much more readable. Updated.

clang/docs/MatrixTypes.rst

30

That's much better, thanks! I've also applied your suggestion to exclude long double for now.

168

Updated, thanks!

217

"omitted".

Done, thanks!

I would expect these operands to have type either size_t or ptrdiff_t. Of course it only really matters for columnStride.

Yes, I update them to size_t. This should give the implementations the most freedom with respect to choosing the implementation defined limits of rows/columns. size_t also makes the most sense for the stride I think, as it is required to be >= the number of rows in the matrix.

[fhahn]

ping.

@rjmccall & @SjoerdMeijer thanks for all the comments. I hope they are no addressed adequately.

[rjmccall]

LGTM with one very minor fix.

clang/docs/LanguageExtensions.rst

511

Extra space after the +.

[fhahn]

Thanks, I plan to submit this on Monday and then make sure the patches on the clang side align with the draft.

[fhahn]

Mark as accepted to make Phabricator/arc happy

clang/docs/LanguageExtensions.rst

 =========================
 Clang Language Extensions
 =========================
 
 .. contents::
    :local:
    :depth: 1
 
 .. toctree::
    :hidden:
 
    ObjectiveCLiterals
    BlockLanguageSpec
    Block-ABI-Apple
    AutomaticReferenceCounting
+   MatrixTypes
 
 Introduction
 ============
 
 This document describes the language extensions provided by Clang.  In addition
 to the language extensions listed here, Clang aims to support a broad range of
 GCC extensions.  Please see the `GCC manual
 <https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on

 
 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
 
 .. [#] unary operator ! is not implemented, however && and || are.
 .. [#] While OpenCL and GCC vectors both implement the comparison operator(?:) as a
   'select', they operate somewhat differently. OpenCL selects based on signedness of
   the condition operands, but GCC vectors use normal bool conversions (that is, != 0).
 
+Matrix Types
+============
+
+Clang provides an extension for matrix types, which is currently being
+implemented. See :ref:`the draft specification <matrixtypes>` for more details.
+
+For example, the code below uses the matrix types extension to multiply two 4x4
+float matrices and add the result to a third 4x4 matrix.
+
+.. code-block:: c++
+
+  typedef float m4x4_t __attribute__((matrix_type(4, 4)));
+
+  m4x4_t f(m4x4_t a, m4x4_t b, m4x4_t c) {
+    return a + b * c;
+  }
+
+
 Half-Precision Floating Point
 =============================
 
 Clang supports two half-precision (16-bit) floating point types: ``__fp16`` and
 ``_Float16``.  These types are supported in all language modes.
 
 ``__fp16`` is supported on every target, as it is purely a storage format; see below.
 ``_Float16`` is currently only supported on the following targets, with further

clang/docs/MatrixTypes.rst

+==================
+Matrix Types
+==================
+
+.. contents::
+   :local:
+
+.. _matrixtypes:
+
+Clang provides a C/C++ language extension that allows users to directly express
+fixed-size 2-dimensional matrices as language values and perform arithmetic on
+them.
+
+This feature is currently experimental, and both its design and its
+implementation are in flux.
+
+Draft Specification
+===================
+
+Matrix Type
+-----------
+
+A matrix type is a scalar type with an underlying *element type*, a constant
+number of *rows*, and a constant number of *columns*. Matrix types with the same
+element type, rows, and columns are the same type. A value of a matrix type
+includes storage for ``rows * columns`` values of the *element type*. The
+internal layout, overall size and alignment are implementation-defined.
+
+The maximum of the product of the number of rows and columns is
+implementation-defined. If that implementation-defined limit is exceeded, the
+program is ill-formed.
+
+Currently, the element type of a matrix is only permitted to be one of the
+following types:
+
+* an integer type (as in C2x 6.2.5p19), but excluding enumerated types and ``_Bool``
+* the standard floating types ``float`` or ``double``
+* a half-precision floating point type, if one is supported on the target
+
+Other types may be supported in the future.
+
+Matrix Type Attribute
+---------------------
+
+Matrix types can be declared by adding the ``matrix_type`` attribute to the
+declaration of a *typedef* (or a C++ alias declaration). The underlying type
+of the *typedef* must be a valid matrix element type. The
+attribute takes two arguments, both of which must be integer constant
+expressions that evaluate to a value greater than zero. The first specifies the
+number of rows, and the second specifies the number of columns. The underlying
+type of the *typedef* becomes a matrix type with the given dimensions and an
+element type of the former underlying type.
+
+If a declaration of a *typedef-name* has a ``matrix_type`` attribute, then all
+declaration of that *typedef-name* shall have a matrix_type attribute with the
+same element type, number of rows, and number of columns.
+
+Standard Conversions
+--------------------
+
+The standard conversions are extended as follows. Note that these conversions
+are intentionally not listed as satisfying the constraints for assignment,
+which is to say, they are only permitted as explicit casts, not as implicit
+conversions.
+
+A value of matrix type can be converted to another matrix type if the number of
+rows and columns are the same and the value's elements can be converted to the
+element type of the result type. The result is a matrix where each element is
+the converted corresponding element.
+
+A value of any real type (as in C2x 6.2.5p17) can be converted to a matrix type
+if it can be converted to the element type of the matrix. The result is a
+matrix where all elements are the converted original value.
+
+If the number of rows or columns differ between the original and resulting
+type, the program is ill-formed.
+
+
+Arithmetic Conversions
+----------------------
+
+The usual arithmetic conversions are extended as follows.
+
+Insert at the start:
+
+* If both operands are of matrix type, no arithmetic conversion is performed.
+* If one operand is of matrix type and the other operand is of a real type,
+  convert the real type operand to the matrix type
+  according to the standard conversion rules.
+
+Matrix Type Element Access Operator
+-----------------------------------
+
+An expression of the form ``E1 [E2] [E3]``, where ``E1`` has matrix type ``cv
+M``, is a matrix element access expression.  Let ``T`` be the element type
+of ``M``, and let ``R`` and ``C`` be the number of rows and columns in ``M``
+respectively.  The index expressions shall have integral or unscoped
+enumeration type and shall not be uses of the comma operator unless
+parenthesized.  The first index expression shall evaluate to a
+non-negative value less than ``R``, and the second index expression shall
+evaluate to a non-negative value less than ``C``, or else the expression has
+undefined behavior.  If ``E1`` is a prvalue, the result is a prvalue with type
+``T`` and is the value of the element at the given row and column in the matrix.
+Otherwise, the result is a glvalue with type ``cv T`` and with the same value
+category as ``E1`` which refers to the element at the given row and column in
+the matrix.
+
+Programs containing a single subscript expression into a matrix are ill-formed.
+
+**Note**: We considered providing an expression of the form
+``postfix-expression [expression]`` to access columns of a matrix. We think
+that such an expression would be problematic once both column and row major
+matrixes are supported: depending on the memory layout, either accessing columns
+or rows can be done efficiently, but not both. Instead, we propose to provide
+builtins to extract rows and columns from a matrix. This makes the operations
+more explicit.
+
+Matrix Type Binary Operators
+----------------------------
+
+Each matrix type supports the following binary operators: ``+``, ``-`` and ``*``. The ``*``
+operator provides matrix multiplication, while ``+`` and ``-`` are performed
+element-wise. There are also scalar versions of the operators, which take a
+matrix type and the matrix element type. The operation is applied to all
+elements of the matrix using the scalar value.
+
+For ``BIN_OP`` in ``+``, ``-``, ``*`` given the expression ``M1 BIN_OP M2`` where
+at least one of ``M1`` or ``M2`` is of matrix type and, for `*`, the other is of
+a real type:
+
+* The usual arithmetic conversions are applied to ``M1`` and ``M2``. [ Note: if ``M1`` or
+  ``M2`` are of a real type, they are broadcast to matrices here. — end note ]
+* ``M1`` and ``M2`` shall be of the same matrix type.
+* The result is equivalent to Res in the following where col is the number of
+  columns and row is the number of rows in the matrix type:
+
+.. code-block:: c++
+
+  decltype(M1) Res;
+  for (int C = 0; C < col; ++C)
+    for (int R = 0; R < row; ++R)
+      Res[R][C] = M1[R][C] BIN_OP M2[R][C];
+
+Given the expression ``M1 * M2`` where ``M1`` and ``M2`` are of matrix type:
+
+* The usual arithmetic conversions are applied to ``M1`` and ``M2``.
+* The type of ``M1`` shall have the same number of columns as the type of ``M2`` has
+  rows. The element types of ``M1`` and ``M2`` shall be the same type.
+* The resulting type, ``MTy``, is a matrix type with the common element type,
+  the number of rows of ``M1`` and the number of columns of ``M2``.
+* The result is equivalent to ``Res`` in the following where ``EltTy`` is the
+  element type of ``MTy``, ``col`` is the number of columns, ``row`` is the
+  number of rows in ``MTy`` and ``inner`` is the number of columns of ``M1``:
+
+.. code-block:: c++
+
+  MTy Res;
+  for (int C = 0; C < col; ++C) {
+    for (int R = 0; R < row; ++R) {
+      EltTy Elt = 0;
+      for (int K = 0; K < inner; ++K) {
+        Elt += M1[R][K] * M2[K][C];
+    }
+    Res[R][C] = Elt;
+  }
+
+All operations on matrix types match the behavior of the element type with
+respect to signed overflows.
+
+With respect to floating-point contraction, rounding and environment rules,
+operations on matrix types match the behavior of the elementwise operations
+in the corresponding expansions provided above.
+
+Operations on floating-point matrices have the same rounding and floating-point
+environment behavior as ordinary floating-point operations in the expression's
+context. For the purposes of floating-point contraction, all calculations done
+as part of a matrix operation are considered intermediate operations, and their
+results need not be rounded to the format of the element type until the final
+result in the containing expression. This is subject to the normal restrictions
+on contraction, such as ``#pragma STDC FP_CONTRACT``.
+
+For the ``+=``, ``-=`` and ``*=`` operators the semantics match their expanded
+variants.
+
+Matrix Type Builtin Operations
+------------------------------
+
+Each matrix type supports a collection of builtin expressions that look like
+function calls but do not form an overload set. Here they are described as
+function declarations with rules for how to construct the argument list types
+and return type and the library description elements from
+[library.description.structure.specifications]/3 in the C++ standard.
+
+Definitions:
+
+* *M*, *M1*, *M2*, *M3* - Matrix types
+* *T* - Element type
+* *row*, *col* - Row and column arguments respectively.
+
+
+``M2 __builtin_matrix_transpose(M1 matrix)``
+
+**Remarks**: The return type is a cv-unqualified matrix type that has the same
+element type as ``M1`` and has the the same number of rows as ``M1`` has columns and
+the same number of columns as ``M1`` has rows.
+
+**Returns**: A matrix ``Res`` equivalent to the code below, where ``col`` refers to the
+number of columns of ``M``, and ``row`` to the number of rows of ``M``.
+
+**Effects**: Equivalent to:
+
+.. code-block:: c++
+
+  M Res;
+  for (int C = 0; C < col; ++C)
+    for (int R = 0; R < row; ++R)
+      Res[C][R] = matrix[R][C];
+
+
+``M __builtin_matrix_column_major_load(T *ptr, size_t row, size_t col, size_t columnStride)``
+
+**Mandates**: ``row`` and ``col`` shall be integral constants greater than 0.
+
+**Preconditions**: ``columnStride`` is greater than or equal to ``row``.
+
+**Remarks**: The return type is a cv-unqualified matrix type with an element
+type of the cv-unqualified version of ``T`` and a number of rows and columns equal
+to ``row`` and ``col`` respectively. The parameter ``columnStride`` is optional
+and if omitted ``row`` is used as ``columnStride``.
+
+**Returns**: A matrix ``Res`` equivalent to:
+
+.. code-block:: c++
+
+  M Res;
+  for (size_t C = 0; C < col; ++C) {
+    for (size_t R = 0; R < row; ++K)
+      Res[R][C] = ptr[R];
+    ptr += columnStride
+  }
+
+
+``void __builtin_matrix_column_major_store(M matrix, T *ptr, size_t columnStride)``
+
+**Preconditions**: ``columnStride`` is greater than or equal to the number of rows in ``M``.
+
+**Remarks**: The type ``T`` is the const-unqualified version of the matrix
+argument’s element type. The paramter ``columnStride`` is optional and if
+ommitted, the number of rows of ``M`` is used as ``columnStride``.
+
+**Effects**: Equivalent to:
+
+.. code-block:: c++
+
+  for (size_t C = 0; C < columns in M; ++C) {
+    for (size_t R = 0; R < rows in M; ++K)
+      ptr[R] = matrix[R][C];
+    ptr += columnStride
+  }
+
+
+TODOs
+-----
+
+TODO: Does it make sense to allow M::element_type, M::rows, and M::columns
+where M is a matrix type? We don’t support this anywhere else, but it’s
+convenient. The alternative is using template deduction to extract this
+information. Also add spelling for C.
+
+Future Work: Initialization syntax.
+
+
+Decisions for the Implementation in Clang
+=========================================
+
+This section details decisions taken for the implementation in Clang and is not
+part of the draft specification.
+
+The elements of a  value of a matrix type are laid out in column-major order
+without padding.
+
+We propose to provide a Clang option to override this behavior and allow
+contraction of those operations (e.g. *-ffp-contract=matrix*).
+
+TODO: Specify how matrix values are passed to functions.