[llvm] [llvm][TableGen] Add a README to the main TableGen folder (PR #69943)

Wed Oct 25 01:20:57 PDT 2023

https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/69943

>From 2f82d9edad0043e07e337459d4be706189448a15 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Mon, 23 Oct 2023 17:36:44 +0100
Subject: [PATCH 1/3] [llvm][TableGen] Add a README to the main TableGen folder

Though I doubt that many people will land here directly, I
thought it odd that we didn't have one.

The intro I've copied from the programmer's reference and
added a simple example. Then some links to resources and tools,
which is the main reason to have this page.
---
 llvm/utils/TableGen/README.md | 46 +++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 llvm/utils/TableGen/README.md

diff --git a/llvm/utils/TableGen/README.md b/llvm/utils/TableGen/README.md
new file mode 100644
index 000000000000000..dfa672a21a8aa3b
--- /dev/null
+++ b/llvm/utils/TableGen/README.md
@@ -0,0 +1,46 @@
+# LLVM TableGen
+
+The purpose of TableGen is to generate complex output files based on information
+from source files that are significantly easier to code than the output files would be, and also easier to maintain and modify over time.
+
+The information is coded in a declarative style involving classes and records,
+which are then processed by TableGen.
+
+```
+class Hello <string _msg> {
+	string msg = !strconcat("Hello ", _msg);
+}
+
+def HelloWorld: Hello<"world!"> {}
+```
+```
+------------- Classes -----------------
+class Hello<string Hello:_msg = ?> {
+  string msg = !strconcat("Hello ", Hello:_msg);
+}
+------------- Defs -----------------
+def HelloWorld {        // Hello
+  string msg = "Hello world!";
+}
+```
+
+The internalized records are passed on to various backends, which extract
+information from a subset of the records and generate one or more output files.
+
+These output files are typically .inc files for C++, but may be any type of file
+that the backend developer needs.
+
+Resources for learning the language:
+* [Programmer's reference guide](https://llvm.org/docs/TableGen/ProgRef.html)
+* [Tutorial](jupyter/tablegen_tutorial_part_1.ipynb)
+* [Lessons in TableGen](https://www.youtube.com/watch?v=45gmF77JFBY) (video),
+  [slides](https://archive.fosdem.org/2019/schedule/event/llvm_tablegen/attachments/slides/3304/export/events/attachments/llvm_tablegen/slides/3304/tablegen.pdf)
+* [How to write a TableGen backend](https://www.youtube.com/watch?v=UP-LBRbvI_U)
+  (video), [slides](https://llvm.org/devmtg/2021-11/slides/2021-how-to-write-a-tablegen-backend.pdf), also available as a
+	[notebook](jupyter/sql_query_backend.ipynb).
+* [Improving Your TableGen Descriptions](https://www.youtube.com/watch?v=dIEVUlsiktQ)
+  (video), [slides](https://llvm.org/devmtg/2019-10/slides/Absar-ImprovingYourTableGenDescription.pdf)
+
+Useful tools:
+* [TableGen Jupyter Kernel](jupyter/)
+* [TableGen LSP Language Server](https://mlir.llvm.org/docs/Tools/MLIRLSP/#tablegen-lsp-language-server--tblgen-lsp-server)
\ No newline at end of file

>From 74feb36c71abef7f675121148db2b60fb5f8d6ea Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Tue, 24 Oct 2023 09:17:05 +0100
Subject: [PATCH 2/3] * Split language and backend sections * Add MLIR links

---
 llvm/utils/TableGen/README.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/llvm/utils/TableGen/README.md b/llvm/utils/TableGen/README.md
index dfa672a21a8aa3b..501c8f49c7eb638 100644
--- a/llvm/utils/TableGen/README.md
+++ b/llvm/utils/TableGen/README.md
@@ -31,15 +31,23 @@ These output files are typically .inc files for C++, but may be any type of file
 that the backend developer needs.
 
 Resources for learning the language:
+* [TableGen Overview](https://llvm.org/docs/TableGen/index.html)
 * [Programmer's reference guide](https://llvm.org/docs/TableGen/ProgRef.html)
 * [Tutorial](jupyter/tablegen_tutorial_part_1.ipynb)
 * [Lessons in TableGen](https://www.youtube.com/watch?v=45gmF77JFBY) (video),
   [slides](https://archive.fosdem.org/2019/schedule/event/llvm_tablegen/attachments/slides/3304/export/events/attachments/llvm_tablegen/slides/3304/tablegen.pdf)
+* [Improving Your TableGen Descriptions](https://www.youtube.com/watch?v=dIEVUlsiktQ)
+  (video), [slides](https://llvm.org/devmtg/2019-10/slides/Absar-ImprovingYourTableGenDescription.pdf)
+
+Writing TableGen backends:
+* [TableGen Backend Developer's Guide](https://llvm.org/docs/TableGen/BackGuide.html)
 * [How to write a TableGen backend](https://www.youtube.com/watch?v=UP-LBRbvI_U)
   (video), [slides](https://llvm.org/devmtg/2021-11/slides/2021-how-to-write-a-tablegen-backend.pdf), also available as a
 	[notebook](jupyter/sql_query_backend.ipynb).
-* [Improving Your TableGen Descriptions](https://www.youtube.com/watch?v=dIEVUlsiktQ)
-  (video), [slides](https://llvm.org/devmtg/2019-10/slides/Absar-ImprovingYourTableGenDescription.pdf)
+
+TableGen in MLIR:
+* [Operation Definition Specification](https://mlir.llvm.org/docs/DefiningDialects/Operations/)
+* [Defining Dialect Attributes and Types](https://mlir.llvm.org/docs/DefiningDialects/AttributesAndTypes/)
 
 Useful tools:
 * [TableGen Jupyter Kernel](jupyter/)

>From ebf61e61632bf850ebb3a264e93547c22c23f8d5 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 25 Oct 2023 09:20:31 +0100
Subject: [PATCH 3/3] Fix indentation in example

---
 llvm/utils/TableGen/README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/llvm/utils/TableGen/README.md b/llvm/utils/TableGen/README.md
index 501c8f49c7eb638..e19701acfce63ac 100644
--- a/llvm/utils/TableGen/README.md
+++ b/llvm/utils/TableGen/README.md
@@ -8,7 +8,7 @@ which are then processed by TableGen.
 
 ```
 class Hello <string _msg> {
-	string msg = !strconcat("Hello ", _msg);
+  string msg = !strconcat("Hello ", _msg);
 }
 
 def HelloWorld: Hello<"world!"> {}
@@ -51,4 +51,5 @@ TableGen in MLIR:
 
 Useful tools:
 * [TableGen Jupyter Kernel](jupyter/)
-* [TableGen LSP Language Server](https://mlir.llvm.org/docs/Tools/MLIRLSP/#tablegen-lsp-language-server--tblgen-lsp-server)
\ No newline at end of file
+* [TableGen LSP Language Server](https://mlir.llvm.org/docs/Tools/MLIRLSP/#tablegen-lsp-language-server--tblgen-lsp-server)
+

