[Matrix] Add documentation for compound assignment and type conversion of matrix types

[SaurabhJha]

Summary

This patch adds examples of compound assignment and type conversions for matrix types.

[SaurabhJha]

Forgot to add a colon in code-block header. Fixed.

[fhahn]

Thanks for the patch! some comments inline.

clang/docs/LanguageExtensions.rst

527

it might also be helpful to include an example with matrix / scalar operations? Division is also supported for matrix/scalar combinations (but not for matrix/matrix)

533

perhaps return the result, so it is not a no-op?

547

can we instead return the casted value, so the code is not a no-op?

[SaurabhJha]

Address review comments

[SaurabhJha]

Document matrix scalar division

[fhahn]

clang/docs/LanguageExtensions.rst

535

Is there any reason we use variables for the scalars? If not, it might be good to keep the examples as compact as possible. Using the extra variables seems overly verbose, when it could be just return (a + 23) * 12 and may give the impression only scalar variables are supported.

same also applies to the other examples below.

578

this could also just be return (fx5x5) i;, right?

[SaurabhJha]

Address comment: replace scalar variables by values

[SaurabhJha]

Did a --amend to rebuild

[SaurabhJha]

Removing mistakenly added files

[fhahn]

Thanks for the latest changes!

clang/docs/LanguageExtensions.rst

526

I'm not a native speaker, but I am not sure if between is the best choice here. To me, on would sound slightly better, but again, I'm no expert.

533

nit: only indent 2 spaces, like the others.

562

Maybe just say that explicit conversions are supported, without going into the specific types of casts?

[SaurabhJha]

Somehow the builds are failing even though this patch contains no code changes.

clang/docs/LanguageExtensions.rst

526

I think you are right. Will change.

[fhahn]

In D104198#2838416, @SaurabhJha wrote:

Somehow the builds are failing even though this patch contains no code changes.

There a few reasons as to why the tests may fail unrelated to the patch (flaky tests, infrastructure issues, test broken on main), so it is a good idea to check what is failing and why. In this case, it looks like a flaky test.

[SaurabhJha]

Address round 2 comments

[SaurabhJha]

Rebase with latest main

[fhahn]

LGTM,thanks.

clang/docs/LanguageExtensions.rst

546

nit: also change to on instead of between for consistency?

[SaurabhJha]

Thanks, the build is also passing now so I will land this in a bit.

[SaurabhJha]

Sorry, I committed this without the Differential Revision: https://reviews.llvm.org/D104198 line. Is there a way to change the commit message after it is in main? I could not push after git commit --amend

[fhahn]

In D104198#2838658, @SaurabhJha wrote:

Sorry, I committed this without the Differential Revision: https://reviews.llvm.org/D104198 line. Is there a way to change the commit message after it is in main? I could not push after git commit --amend

There's no way to adjust an already pushed commit (force pushes are blocked). You could either revert the change and re-commit with the updated wording or you could manually close the revision here. If the rest of the commit message is OK, I'd recommend just closing the revision manually and provide a link to the commit.

[SaurabhJha]

In D104198#2838665, @fhahn wrote:

In D104198#2838658, @SaurabhJha wrote:

Sorry, I committed this without the Differential Revision: https://reviews.llvm.org/D104198 line. Is there a way to change the commit message after it is in main? I could not push after git commit --amend

There's no way to adjust an already pushed commit (force pushes are blocked). You could either revert the change and re-commit with the updated wording or you could manually close the revision here. If the rest of the commit message is OK, I'd recommend just closing the revision manually and provide a link to the commit.

Okay thanks, I will do the latter.

[SaurabhJha]

This is closed by this commit https://github.com/llvm/llvm-project/commit/cd256c8bcc9723f0ce7a32957f26600c966fa07c

[xgupta]

clang/docs/LanguageExtensions.rst

539

This is incorrect ig.

I get warning message :

Warning, treated as error:
/home/user/llvm-project/clang/docs/LanguageExtensions.rst:538:Error in "code-block" directive:
maximum 1 argument(s) allowed, 6 supplied.

[xgupta]

clang/docs/LanguageExtensions.rst

538

oh just an blank line is needed :)

[SaurabhJha]

clang/docs/LanguageExtensions.rst

538

Thanks, fixing this now.

[SaurabhJha]

@fhahn addressed your broadcast comment. Would you prefer that I create the initialisation implementation patch before we get this in?

[SaurabhJha]

Sorry, commented on incorrect patch.

clang-tools-extra/clang-reorder-fields/tool/ClangReorderFields.cpp

int main(int argc, const char **argv) {
   IntrusiveRefCntPtr<DiagnosticOptions> DiagOpts(new DiagnosticOptions());
   TextDiagnosticPrinter DiagnosticPrinter(errs(), &*DiagOpts);
   DiagnosticsEngine Diagnostics(
       IntrusiveRefCntPtr<DiagnosticIDs>(new DiagnosticIDs()), &*DiagOpts,
       &DiagnosticPrinter, false);
 
   auto &FileMgr = Tool.getFiles();
   SourceManager Sources(Diagnostics, FileMgr);
-  Rewriter Rewrite(Sources, DefaultLangOptions);
+  Rewriter Rewrite(Sources, DefaultLangOptions); // TODO: Ally Donaldson
   Tool.applyAllReplacements(Rewrite);
 
   for (const auto &File : Files) {
     auto Entry = FileMgr.getFile(File);
     const auto ID = Sources.getOrCreateFileID(*Entry, SrcMgr::C_User);
     Rewrite.getEditBuffer(ID).write(outs());
   }
 
   return ExitCode;
 }

clang/docs/LanguageExtensions.rst

 .. 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;
   }
 
+The matrix type extension also supports operations between a matrix and a scalar.
+
+.. code-block:: c++
+
+  typedef float m4x4_t __attribute__((matrix_type(4, 4)));
+
+  m4x4_t f(m4x4_t a) {
+      return (a + 23) * 12;
+  }
+
+The matrix type extension supports division between a matrix and a scalar but not between a matrix and a matrix.
+
+.. code-block:: c++
+  typedef float m4x4_t __attribute__((matrix_type(4, 4)));
+
+  m4x4_t f(m4x4_t a) {
+    a = a / 3.0;
+    return a;
+  }
+
+The matrix type extension supports compound assignments for addition, subtraction, and multiplication between matrices
+and between a matrix and a scalar, provided their types are consistent.
+
+.. code-block:: c++
+
+  typedef float m4x4_t __attribute__((matrix_type(4, 4)));
+
+  m4x4_t f(m4x4_t a, m4x4_t b) {
+    a += b;
+    a -= b;
+    a *= b;
+    a += 23;
+    a -= 12;
+    return a;
+  }
+
+The matrix type extension supports explicit casts. The casts we support are C-style casts in C and C++ and
+static casts. Implicit type conversion between matrix types is not allowed.
+
+.. code-block:: c++
+
+  typedef int ix5x5 __attribute__((matrix_type(5, 5)));
+  typedef float fx5x5 __attribute__((matrix_type(5, 5)));
+
+  fx5x5 f1(ix5x5 i, fx5x5 f) {
+    return (fx5x5) i;
+  }
+
+
+  template <typename X>
+  using matrix_4_4 = X __attribute__((matrix_type(4, 4)));
+
+  void f2() {
+    matrix_5_5<double> d;
+    matrix_5_5<int> i;
+    i = (matrix_5_5<int>)d;
+    i = static_cast<matrix_5_5<int>>(d);
+  }
 
 Half-Precision Floating Point
 =============================
 
 Clang supports three half-precision (16-bit) floating point types: ``__fp16``,
 ``_Float16`` and ``__bf16``.  These types are supported in all language modes.
 
 ``__fp16`` is supported on every target, as it is purely a storage format; see below.