From a1d971919e7cb79baac911b268f28848f2a886f5 Mon Sep 17 00:00:00 2001
From: Vaivaswatha Nagaraj <vaivaswatha@gmail.com>
Date: Sun, 7 Jul 2024 13:54:39 +0530
Subject: [PATCH] Update README

---
 README.md             | 19 ++++++++++++-------
 pliron-llvm/README.md | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 92de4e1..5899b08 100644
--- a/README.md
+++ b/README.md
@@ -16,15 +16,19 @@ and written in safe Rust.
   It should print something like:
   ```mlir
   builtin.module @bar {
-    block_0_0():
-      builtin.func @foo: builtin.function <() -> (builtin.integer <si64>)> {
-        entry():
-          c0_op_2_0_res0 = builtin.constant 0x0: builtin.integer <si64>;
-          llvm.return c0_op_2_0_res0
+    ^block_1v1():
+      builtin.func @foo: builtin.function<() -> (builtin.int<si64>)> {
+        ^entry_block_2v1():
+          c0_op_3v1_res0 = test.constant builtin.integer <0x0: builtin.int<si64>>;
+          test.return c0_op_3v1_res0
       }
   }
   ```
 
+* `pliron` provide an [`llvm-opt` tool](pliron-llvm/README.md) that
+can parse LLVM-IR bitcode into the LLVM dialct and output LLVM-IR
+bitcode.
+
 ## Using the Library
 `pliron` is currently in a nascent stage and not yet useful for
 real-world use. In the future it can be used by just adding
@@ -32,7 +36,8 @@ a dependence to the [crate](https://crates.io/crates/pliron)
 in your Rust project.
 
 ## Documentation
-* Some key design decisions are explained in the
-  [introductory blog article](https://github.com/vaivaswatha/pliron/wiki/Introducing-pliron).
+* Introduction and motivation are covered in the [introductory wiki article](https://github.com/vaivaswatha/pliron/wiki/Introduction).
+* The wiki also has a [comparison](https://github.com/vaivaswatha/pliron/wiki/Comparison-with-other-compiler-frameworks) of `pliron`
+with other compiler projects, touching upon some design decisions.
 * Code documentation can be found on
   [docs.rs](https://docs.rs/pliron/latest/pliron/).
diff --git a/pliron-llvm/README.md b/pliron-llvm/README.md
index c47d5e0..12d68cd 100644
--- a/pliron-llvm/README.md
+++ b/pliron-llvm/README.md
@@ -11,3 +11,38 @@ which requires LLVM to be installed on your system.
 We currently support LLVM-17, and hence LLVM-17 needs to be on your computer.
 On Ubuntu, this means, you require the `libllvm17` and `libpolly-17-dev`
 [packages](https://thedan64.github.io/inkwell/).
+
+## llvm-opt tool
+The `llvm-opt` binary is provided to enable parsing LLVM bitcode binaries
+into `pliron`'s LLVM dialect and to emit LLVM bitcode back from the dialect.
+
+Example usage:
+1. Compile `fib.c` into LLVM-IR:
+  
+    `$clang-17 -c -emit-llvm -o /tmp/fib.bc tests/resources/fib.c `
+
+2. Convert the LLVM bitcode to LLVM dialect in `pliron` and back to
+LLVM bitcode (the binary `llvm-opt`, produced in your cargo's target
+directory must be in $PATH):
+
+    `$llvm-opt -S -i /tmp/fib.bc -o /tmp/fib.opt.ll`
+
+3. Compile the output fibonacci LLVM-IR, along with a main function
+into a binary:
+
+    `$clang-17 -o /tmp/fib /tmp/fib.out.ll tests/resources/fib-main.c`
+
+4. Run the fibonacci binary to see the first few fibonacci numbers
+printed.
+
+    `$/tmp/fib`
+
+    ```
+        fib(0): 0
+        fib(1): 0
+        fib(2): 1
+        fib(3): 1
+        fib(4): 2
+    ```
+
+**Note**: Implementation of the LLVM dialect is not complete, and the above is just a proof-of-concept.
\ No newline at end of file