doc: add more explaination of each dialect in home page (#263)

fix #260

Author: Roger-luo

docs/dialects/cf.md

@@ -3,6 +3,122 @@
     on [GitHub](https://github.com/QuEraComputing/kirin/issues/new) if you need help or want to
     contribute.
 
+# The Control Flow Dialect
+
+The control flow dialect provides the most generic control flow semantics via [`cf.Branch`][kirin.dialects.cf.Branch] and [`cf.ConditionalBranch`][kirin.dialects.cf.ConditionalBranch].
+
+## `cf.Branch`
+
+the [`cf.Branch`][kirin.dialects.cf.Branch] statement is used to mark how basic block branches to another basic block without condition. This represents an edge on the control flow graph (CFG).
+
+```mlir
+^1(%2):
+  │   %y = py.constant.constant 1 : !py.int
+  │        cf.br ^3(%y)
+  ^2(%3):
+  │ %y_1 = py.constant.constant 2 : !py.int
+  │        cf.br ^3(%y_1)
+  ^3(%y_2):
+  │        func.return %y_2
+```
+
+**Definition** the `cf.Branch` statement takes a successor block and its argument. The `cf.Branch` is a terminator thus it should always be the last statement of a block.
+
+!!! note
+    [`ir.Statement`][kirin.ir.Statement] does not own any [`ir.Block`][kirin.ir.Block], the [`ir.Region`][kirin.ir.Region] owns blocks. The [`ir.Statement`][kirin.ir.Statement] will only own [`ir.Region`][kirin.ir.Region]. In Kirin, we use similar design as LLVM/MLIR where the phi nodes in SSA form are replaced by block arguments.
+
+## `cf.ConditionalBranch`
+
+The [`cf.ConditionalBranch`][kirin.dialects.cf.ConditionalBranch] statement represents a conditional branching statement that looks like following (the `cf.cond_br` statement):
+
+```mlir
+^0(%main_self, %x):
+│   %0 = py.constant.constant 1 : !py.int
+│   %1 = py.cmp.gt(lhs=%x, rhs=%0) : !py.bool
+│        cf.cond_br %1 goto ^1(%1) else ^2(%1)
+```
+
+**Definition**, [`cf.ConditionalBranch`][kirin.dialects.cf.ConditionalBranch] takes a boolean condition `cond` of type [`ir.SSAValue`][kirin.ir.SSAValue] and:
+
+- then successor and its argument
+- else successor and its argument
+
+this statement is also a terminator, which means it must be the last statement of a block.
+
+## Combining together - lowering from Python
+
+Now combining these two statemente together, we can represent most of the Python control flows, e.g `if-else` and `for`-loops. These two statement basically just provides a basic way describing the edges on a control flow graph (CFG) by assuming the node only has one or two outgoing edges.
+
+As an example, the following Python program:
+
+```python
+from kirin.prelude import basic_no_opt
+
+@basic_no_opt
+def main(x):
+    if x > 1:
+        y = 1
+    else:
+        y = 2
+    return y
+```
+
+will be lowered to the following SSA form in `cf` dialect:
+
+```mlir
+func.func main(!Any) -> !Any {
+  ^0(%main_self, %x):
+  │   %0 = py.constant.constant 1 : !py.int
+  │   %1 = py.cmp.gt(lhs=%x, rhs=%0) : !py.bool
+  │        cf.cond_br %1 goto ^1(%1) else ^2(%1)
+  ^1(%2):
+  │   %y = py.constant.constant 1 : !py.int
+  │        cf.br ^3(%y)
+  ^2(%3):
+  │ %y_1 = py.constant.constant 2 : !py.int
+  │        cf.br ^3(%y_1)
+  ^3(%y_2):
+  │        func.return %y_2
+} // func.func main
+```
+
+And similarly, we can lower a `for`-loop into the `cf` dialect:
+
+```python
+@basic_no_opt
+def main(x):
+    for i in range(5):
+        x = x + i
+    return x
+```
+
+will be lowered into the following SSA form:
+
+```mlir
+func.func main(!Any) -> !Any {
+  ^0(%main_self, %x_1):
+  │ %0 = py.constant.constant 0 : !py.int
+  │ %1 = py.constant.constant 5 : !py.int
+  │ %2 = py.constant.constant 1 : !py.int
+  │ %3 = py.range.range(start=%0, stop=%1, step=%2) : !py.range
+  │ %4 = py.iterable.iter(value=%3) : !Any
+  │ %5 = py.constant.constant None : !py.NoneType
+  │ %6 = py.iterable.next(iter=%4) : !Any
+  │ %7 = py.cmp.is(lhs=%6, rhs=%5) : !py.bool
+  │      cf.cond_br %7 goto ^2(%x_1) else ^1(%6, %x_1)
+  ^1(%i, %x_2):
+  │ %x = py.binop.add(%x_2, %i) : ~T
+  │ %8 = py.iterable.next(iter=%4) : !Any
+  │ %9 = py.cmp.is(lhs=%8, rhs=%5) : !py.bool
+  │      cf.cond_br %9 goto ^2(%x) else ^1(%8, %x)
+  ^2(%x_3):
+  │      func.return %x_3
+} // func.func main
+```
+
+However, as you may already notice, lowering from Python directly to `cf` dialect will lose some of the high-level information such as the control flow is actually a for-loop. This information can be useful when one wants to perform some optimization. This is why we are taking the same route as MLIR with a structural IR (via [`ir.Region`][kirin.ir.Region]s). For the interested readers, please proceed to [Structural Control Flow](scf.md) for further reading.
+
+## API Reference
 
 ::: kirin.dialects.cf.stmts
     options:

docs/dialects/func.md

@@ -3,6 +3,92 @@
     on [GitHub](https://github.com/QuEraComputing/kirin/issues/new) if you need help or want to
     contribute.
 
+# The Function Dialect
+
+The function dialect provides a set of statements to model semantics of Python-like functions, that means:
+
+- `def <name>(<args>*, <kwargs>*)` like function declarations
+- nested functions (namely closures)
+- high-order functions (functions can be used as arguments)
+- dynamically/statically calling a function or closure
+
+## `func.Return`
+
+This is a simple statement that models the `return` statement in a function declaration. While this is a very simple statement, it is worth noting that this statement only accepts **one argument** of type [ir.SSAValue][kirin.ir.SSAValue] because in Python (and most of other languages) functions always have a single return value, and multiple return values are represented by returning a `tuple`.
+
+## `func.Function`
+
+This is the most fundamental statement that models a Python function.
+
+**Definition** The [`func.Function`][kirin.dialects.func.Function] takes no arguments, but contains a special `str` attribute (thus stored as `PyAttr`) that can be used as a symbolic reference within a symbol table. The `func.Function` also takes a `func.Signature` attribute to store the signature of corresponding function declaration. Last, it contains a [`ir.Region`][kirin.ir.Region] that represents the function body. The [`ir.Region`][kirin.ir.Region] follows the SSACFG convention where the blocks in the region forms a control flow graph.
+
+!!! note "Differences with MLIR"
+    As Kirin's priority is writing eDSL as kernel functions in Python. To support high-order functions the entry block arguments always have their first argument `self` of type [`types.MethodType`][kirin.types.MethodType]. This is a design inspired by [Julia](https://julialang.org)'s IR design.
+
+As an example, the following Python function
+
+```python
+from kirin.prelude import basic_no_opt
+
+@basic_no_opt
+def main(x):
+    return x
+```
+
+will be lowered into the following IR, where `main_self` referencing the function itself.
+
+```mlir
+func.func main(!Any) -> !Any {
+  ^0(%main_self, %x):
+  │ func.return %x
+} // func.func main
+```
+
+the function can be terminated by a [`func.Return`][kirin.dialects.func.Return] statement. All blocks in the function region must have terminators. In the lowering process, if the block is not terminated, a `func.Return` will be attached to return `None` in the function body. Thus `func.Function` can only have a single return value.
+
+## `func.Call` and `func.Invoke`
+
+These two statements models the most common call convention in Python with consideration of compilation:
+
+- `func.Call` models dynamic calls where the **callee is unknown at compile time**, thus of type [`ir.SSAValue`][kirin.ir.SSAValue]
+- `func.Invoke` models static calls where the **callee is known at compile time**, thus of type [`ir.Method`][kirin.ir.Method]
+
+they both take `inputs` which is a tuple of [`ir.SSAValue`][kirin.ir.SSAValue] as argument. Because we assume all functions will only return a single value, `func.Call` and `func.Invoke` only have a single result.
+
+## `func.Lambda`
+
+This statement models nested functions (a.k.a closures). While most definitions are similar to `func.Function` the key difference is `func.Lambda` takes a tuple of [`ir.SSAValue`][kirin.ir.SSAValue] arguments as `captured`. This models the captured variables for a nested function, e.g
+
+the following Python function containing a closure inside with variable `x` being captured:
+
+```python
+from kirin import basic_no_opt
+
+@basic_no_opt
+def main(x):
+    def closure():
+        return x
+    return closure
+```
+
+will be lowered into
+
+```mlir
+func.func main(!Any) -> !Any {
+  ^0(%main_self, %x):
+  │ %closure = func.lambda closure(%x) -> !Any {
+  │            │ ^1(%closure_self):
+  │            │ │ %x_1 = func.getfield(%closure_self, 0) : !Any
+  │            │ │        func.return %x_1
+  │            } // func.lambda closure
+  │            func.return %closure
+} // func.func main
+```
+
+Unlike `func.Function` this statement also has a result value which points to the closure itself. Inside the closure body, we insert [`func.GetField`][kirin.dialects.func.GetField] to unpack captured variables into the closure body.
+
+## API Reference
+
 ::: kirin.dialects.func.stmts
     options:
         show_if_no_docstring: true

docs/dialects/ilist.md

@@ -4,6 +4,86 @@
     contribute.
 
 
+# The Immutable List Dialect
+
+The immutable list dialect models a Python-like `list` but is immutable. There are many good reasons to have an immutable list for compilation, especially when a list is immutable, we can assume a lot of statements to be pure and foldable (and thus can be inlined or simplified without extra analysis/rewrites).
+
+!!! note "JAX"
+    This is also the reason why JAX picks an immutable array semantic.
+
+!!! note "Why not use tuple?"
+    Tuple can take multiple items of different types, but list can only take items of the same type. Thus they have different trade-offs when doing analysis such as type inference of iterating through a tuple/list.
+
+## Runtime
+
+This dialect provides a runtime object `IList` which is a simple Python class wraps a Python list. This object can be used as a compile-time value by providing an implementation of `__hash__` that returns the object id. This means common simplifications like Common Subexpression Elimination (CSE) will not detect duplicated `IList` unless the `ir.SSAValue` points to identical `IList` object.
+
+!!! warning "Implementation Details"
+    this is an implementation detail of `IList`, we can switch to a more efficient runtime in the future where the memory layout is optimized based on the assumption of items in same type and immutabiility.
+
+The `IList` runtime object implements most of the Python `Sequence` interface, such as `__getitem__`, `__iter__`, `__len__` etc.
+
+## `New`
+
+This statements take a tuple of [`ir.SSAValue`][kirin.ir.SSAValue] and creates an `IList` as result.
+
+!!! note "Syntax Sugar in Lowering"
+    The syntax `[a, b, c]` will be lowered into `New` statement as a syntax sugar when `ilist` dialect is used (thus in conflict with mutable Python list). This may change in the future to give developers more freedom to choose what to lower from.
+
+## `Map`
+
+This statements take a high-order function (a function object) of signature `[[ElemT], OutT]` and apply it on a given `IList[ElemT, Len]` object then return a new `IList[OutT, Len]`.
+
+For example:
+
+```python
+@basic_no_opt
+def main(x: ilist.IList[float, Literal[5]]):
+    def closure(a):
+        return a + 1
+    return ilist.map(closure, x)
+```
+
+will be lowerd into the following
+
+```mlir
+func.func main(!py.IList[!py.float, 5]) -> !Any {
+  ^0(%main_self, %x):
+  │ %closure = func.lambda closure() -> !Any {
+  │            │ ^1(%closure_self, %a):
+  │            │ │ %1 = py.constant.constant 1 : !py.int
+  │            │ │ %2 = py.binop.add(%a, %1) : ~T
+  │            │ │      func.return %2
+  │            } // func.lambda closure
+  │       %0 = py.ilist.map(fn=%closure, collection=%x : !py.IList[!py.float, 5]) : !py.IList[~OutElemT, ~ListLen]
+  │            func.return %0
+} // func.func main
+```
+
+## `Foldl` and `Foldr`
+
+These two statements represents applying a binary operator `+` (any binary operator) on an `IList` with a different reduction order, e.g given `[a, b, c]`, `Foldl` represents `((a + b) + c)` and `Foldr` represents `(a + (b + c))`.
+
+## `Scan`
+
+While the actual implementation is not the same, this statement represents the same semantics as the following function:
+
+```python
+def scan(fn, xs, init):
+    carry = init
+    ys = []
+    for elem in xs:
+        carry, y = fn(carry, elem)
+        ys.append(y)
+    return carry, ys
+```
+
+## `ForEach`
+
+this represents a `for`-loop without any loop variables (variables pass through each loop iteration).
+
+## API Reference
+
 ::: kirin.dialects.ilist.stmts
     options:
         show_if_no_docstring: true