[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

255

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

255

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

4

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.

13

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.

15

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

31

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.

49

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

56

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.

58

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

65

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.

107

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

111

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.

119

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

4

I changed it to "Matrix Types"

[fhahn]

clang/docs/MatrixSupport.rst

31

Thanks, that helps to simplify this section a lot.

49

Sounds good! Moved.

58

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.

65

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

111

Updated, thanks.

119

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

29

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.

40

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

71

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.

127

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++.

130

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.

177

"builtin" should be capitalized here.

212

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

40

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

71

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

130

I added the following at the end of the section

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

212

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

212

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

79 ↗

(On Diff #257115)

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.

123 ↗

(On Diff #257115)

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

138 ↗

(On Diff #257115)

Same point about element types.

141 ↗

(On Diff #257115)

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.

152 ↗

(On Diff #257115)

inner is not defined.

164 ↗

(On Diff #257115)

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

79 ↗

(On Diff #257115)

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.

123 ↗

(On Diff #257115)

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.

138 ↗

(On Diff #257115)

Added

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

141 ↗

(On Diff #257115)

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.

152 ↗

(On Diff #257115)

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

164 ↗

(On Diff #257115)

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

12 ↗

(On Diff #257259)

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

25 ↗

(On Diff #257259)

typo: ype -> type

27 ↗

(On Diff #257259)

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

12 ↗

(On Diff #257259)

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.

27 ↗

(On Diff #257259)

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

27 ↗

(On Diff #257259)

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

27 ↗

(On Diff #257259)

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

79 ↗

(On Diff #257115)

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

29 ↗

(On Diff #257309)

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?

27 ↗

(On Diff #257259)

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.

[fhahn]

Update list of types excluded from real types, thanks!

clang/docs/MatrixTypes.rst

29 ↗

(On Diff #257309)

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.

27 ↗

(On Diff #257259)

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.

79 ↗

(On Diff #257115)

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

[rjmccall]

clang/docs/MatrixTypes.rst

29 ↗

(On Diff #257309)

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

29 ↗

(On Diff #257309)

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

62 ↗

(On Diff #258179)

s/size/same/

66 ↗

(On Diff #258179)

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

167 ↗

(On Diff #258179)

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.

216 ↗

(On Diff #258179)

"omitted".

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

29 ↗

(On Diff #257309)

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".

[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

167 ↗

(On Diff #258179)

Updated, thanks!

216 ↗

(On Diff #258179)

"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.

29 ↗

(On Diff #257309)

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

[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
+   MatrixSupport
 
 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).
 
+Matrixes
+========
+
+Clang provides a matrix extension, which is currently being implemented. See
+:ref:`matrixsupport` for more details.
+
 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
 targets pending ABI standardization:
 
 * 32-bit ARM
 * 64-bit ARM (AArch64)
 * SPIR
 
 ``_Float16`` will be supported on more targets as they define ABIs for it.
 
 ``__fp16`` is a storage and interchange format only.  This means that values of
 ``__fp16`` are immediately promoted to (at least) ``float`` when used in arithmetic

clang/docs/MatrixSupport.rst

+==================
+Matrix Support
+==================
+
+.. contents::
+   :local:
+
+.. _matrixsupport:
+
+Clang provides a language extension that allows users to express high-level
+matrix math on the C/C++ level. The draft specification can be found :ref:`below <matrixsupport-draftspec>`.
+
+Note that the implementation is currently in progress.
+
+.. _matrixsupport-draftspec:
+
+Draft Specification
+===================
+
+Matrix Type Attribute
+---------------------
+
+The *attribute-token* ``matrix_type`` is used to declare a matrix type. It shall
+appear at most once in each *attribute-list*. The attribute shall only appertain
+to a *typedef-name* of a typedef of a non-volatile type that is a *signed 
+integer type*, an *unsigned integer type*, or a *floating-point type*. An
+*attribute-argument-clause* must be present and it shall have the form:
+
+``(constant-expression, constant-expression)``
+
+Both *constant-expressions* shall be a positive non-zero integral constant
+expressions. The maximum of the product of the constants is implementation
+defined. If that implementation defined limit is exceeded, the program is
+ill-formed.
+
+An *attribute* of the form ``matrix_type(R, C)`` forms a matrix type with an
+element type of the cv-qualified type the attribute appertains to and *R* rows
+and *C* columns.
+
+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.
+
+Matrix Type
+-----------
+
+A matrix type has 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 contains ``rows *
+columns`` values of the *element type* laid out in column-major order without
+padding in a way compatible with an array of at least that many elements of the
+underlying *element type*.
+
+A matrix type is a *scalar type* with the same alignment as its underlying
+element type, but objects of matrix type are not usable in constant
+expressions.
+
+TODO: Allow reinterpret_cast from pointer to element type. Make aliasing work.
+
+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.
+
+Future Work: Initialization syntax.
+
+Future Work: Conversions between matrix types with const qualified and
+unqualified element types.
+
+Standard Conversions
+--------------------
+
+The standard conversions are extended as follows.
+
+For integral promotions, floating-point promotion, integral conversions,
+floating-point conversions, and floating-integral conversions: apply the rules
+to the underlying type of the matrix type. The resulting type is a matrix type
+with that underlying element type. The resulting value is as follows:
+
+* If the original value was of matrix type, each element is converted element
+  by element.
+* If the original value was not of matrix type, each element takes the value of
+  the original value.
+
+Arithmetic Conversions
+----------------------
+
+The usual arithmetic conversions are extended as follows.
+
+Insert at the start:
+
+* If either operand is of matrix type, apply the usual arithmetic conversions
+  using its underlying element type. The resulting type is a matrix type with
+  that underlying element type.
+
+Matrix Type Element Access Operator
+-----------------------------------
+
+An expression of the form ``postfix-expression [expression][expression]`` where
+the ``postfix-expression`` is of matrix type is a matrix element access
+expression. ``expression`` shall not be a comma expression, and shall be a
+prvalue of unscoped enumeration or integral type. Given the expression
+``E1[E2][E3]`` the result is an lvalue of the same type as the underlying
+element type of the matrix that refers to the value at E2 row and E3 column in
+the matrix. The expression E1 is sequenced before E2 and E3. The expressions
+E2 and E3 are unsequenced.
+
+**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 underlying element type. The operation is applied to all
+elements of the matrix using the scalar value.
+
+The operands of ``+``, ``-`` and ``*`` shall have either matrix type, arithmetic or
+unscoped enumeration type. At least one of the operands shall be of matrix type.
+
+For ``BIN_OP`` in ``+``, ``-``, ``*`` given the expression ``M1 BIN_OP M2`` where, for
+``*``, one of M1 or M2 is of arithmetic type:
+
+* The usual arithmetic conversions are applied to M1 and M2. [ Note: if M1 or
+  M2 are of arithmetic type, they are broadcast to matrices here. — end note ]
+* The matrix types of M1 and M2 shall have the same number of rows and columns.
+* 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 resulting type, ``MTy``, is the result of applying the usual arithmetic
+  conversions to ``M1`` and ``M2``, but with the same number of rows as M1’s matrix
+  type and the same number of columns as M2’s matrix type.
+* The result is equivalent to ``Res`` in the following where ``EltTy`` is the
+  element type of ``MTy``, ``col`` is the number of columns and ``row`` is the
+  number of rows in ``MTy``:
+
+.. 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 underlying element
+type with respect to signed overflows.
+
+With respect to rounding errors, the the ``*`` operator preserves the behavior of
+the separate multiply and add operations by default. We propose to provide a
+Clang option to override this behavior and allow contraction of those
+operations (e.g. *-ffp-contract=matrix*).
+
+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_load(T *ptr, int row, int col, int stride)``
+
+**Mandates**: ``row`` and ``col`` shall be integral constants greater than 0.
+
+**Preconditions**: ``stride >= 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.
+
+**Returns**: A matrix ``Res`` equivalent to:
+
+.. code-block:: c++
+
+  M Res;
+  for (int C = 0; C < col; ++C) {
+    for (int R = 0; R < row; ++K)
+      Res[R][C] = ptr[R];
+    ptr += stride
+  }
+
+
+``void __builtin_matrix_column_store(M matrix, T *ptr, int stride)``
+
+**Preconditions**: ``stride`` is greater than or equal to the number of rows in ``M``.
+
+**Effects**: Equivalent to:
+
+.. code-block:: c++
+
+  for (int C = 0; C < columns in M; ++C) {
+    for (int R = 0; R < rows in M; ++K)
+      ptr[R] = matrix[R][C];
+    ptr += stride
+  }
+
+**Remarks**: The type ``T`` is the const-unqualified version of the matrix
+argument’s element type.
+
+Example
+=======
+
+This code performs a matrix-multiply of two 4x4 *float* matrixes followed by an matrix addition:
+
+.. code-block:: c++
+
+  typedef float m4x4_t __attribute__((matrix_type(4, 4)));
+
+  void f(m4x4_t *a, m4x4_t *b, m4x4_t *c, m4x4_t *r) {
+    *r = *a +  (*b * *c);
+  }
+
+
+This will get lowered by Clang to the LLVM IR below. In our current
+implementation, we use LLVM’s array type as storage type for the matrix
+data. Before accessing the data, we cast the array to a vector type. This
+allows us to use the element width as alignment, without running into issues
+with LLVM’s large default alignment for vector types, which is problematic in
+structs.
+
+.. code::
+
+  define void @f([16 x float]* %a, [16 x float]* %b, [16 x float]* %c, [16 x float]* %r) #0 {
+  entry:
+    %a.addr = alloca [16 x float]*, align 8
+    %b.addr = alloca [16 x float]*, align 8
+    %c.addr = alloca [16 x float]*, align 8
+    %r.addr = alloca [16 x float]*, align 8
+    store [16 x float]* %a, [16 x float]** %a.addr, align 8
+    store [16 x float]* %b, [16 x float]** %b.addr, align 8
+    store [16 x float]* %c, [16 x float]** %c.addr, align 8
+    store [16 x float]* %r, [16 x float]** %r.addr, align 8
+    %0 = load [16 x float]*, [16 x float]** %a.addr, align 8
+    %1 = bitcast [16 x float]* %0 to <16 x float>*
+    %2 = load <16 x float>, <16 x float>* %1, align 4
+    %3 = load [16 x float]*, [16 x float]** %b.addr, align 8
+    %4 = bitcast [16 x float]* %3 to <16 x float>*
+    %5 = load <16 x float>, <16 x float>* %4, align 4
+    %6 = call <16 x float> @llvm.matrix.multiply.v16f32.v16f32.v16f32(<16 x float> %2, <16 x float> %5, i32 4, i32 4, i32 4)
+    %7 = load [16 x float]*, [16 x float]** %c.addr, align 8
+    %8 = bitcast [16 x float]* %7 to <16 x float>*
+    %9 = load <16 x float>, <16 x float>* %8, align 4
+    %10 = fadd <16 x float> %6, %9
+    %11 = load [16 x float]*, [16 x float]** %r.addr, align 8
+    %12 = bitcast [16 x float]* %11 to <16 x float>*
+    store <16 x float> %10, <16 x float>* %12, align 4
+    ret void
+  }
+  ; Function Attrs: nounwind readnone speculatable willreturn
+  declare <16 x float> @llvm.matrix.multiply.v16f32.v16f32.v16f32(<16 x float>, <16 x floa
+