Update README

README.md

@@ -16,23 +16,28 @@ 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
 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/).

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.