Extend Transactron introduction

docs/Transactions.md

@@ -54,12 +54,6 @@ The transaction body `with` block works analogously to Amaranth's `with m.If():`
 This is implemented in hardware via multiplexers.
 Please remember that this is not a Python `if` statement -- the *Python code* inside the `with` block is always executed once.
 
-If a transaction is not always ready for execution (for example, because of the dependence on some resource), a `request` parameter should be used. An Amaranth single-bit expression should be passed.
-
-```python
-        with Transaction().body(m, request=expr):
-```
-
 ### Implementing methods
 
 As methods are used as a way to communicate with other `Elaboratable`s, they are typically declared in the `Elaboratable`'s constructor, and then defined in the `elaborate` method:
@@ -114,7 +108,7 @@ Only methods should be passed around, not entire `Elaboratable`s!
 
 ```python
 class MyThing(Elaboratable):
-    def __init__(self, method):
+    def __init__(self, method: Method):
         self.method = method
 
         ...
@@ -139,6 +133,114 @@ If in doubt, methods are preferred.
 This is because if a functionality is implemented as a method, and a transaction is needed, one can use a transaction which calls this method and does nothing else.
 Such a transaction is included in the library -- it's named `AdapterTrans`.
 
+### Method argument passing conventions
+
+Even though method arguments are Amaranth records, their use can be avoided in many cases, which results in cleaner code.
+Suppose we have the following layout, which is an input layout for a method called `method`:
+
+```python
+layout = [("foo", 1), ("bar", 32)]
+method = Method(input_layout=layout)
+```
+
+The method can be called in multiple ways.
+The cleanest and recommended way is to pass each record field using a keyword argument:
+
+```python
+method(m, foo=foo_expr, bar=bar_expr)
+```
+
+Another way is to pass the arguments using a `dict`:
+
+```python
+method(m, {'foo': foo_expr, 'bar': bar_expr})
+```
+
+Finally, one can directly pass an Amaranth record:
+
+```python
+rec = Record(layout)
+m.d.comb += rec.foo.eq(foo_expr)
+m.d.comb += rec.bar.eq(bar_expr)
+method(m, rec)
+```
+
+The `dict` convention can be used recursively when layouts are nested.
+Take the following definitions:
+
+```python
+layout2 = [("foobar", layout), ("baz", 42)]
+method2 = Method(input_layout=layout2)
+```
+
+One can then pass the arguments using `dict`s in following ways:
+
+```python
+# the preferred way
+method2(m, foobar={'foo': foo_expr, 'bar': bar_expr}, baz=baz_expr)
+
+# the alternative way
+method2(m, {'foobar': {'foo': foo_expr, 'bar': bar_expr}, 'baz': baz_expr})
+```
+
+### Method definition conventions
+
+When defining methods, two conventions can be used.
+The cleanest and recommended way is to create an argument for each record field:
+
+```python
+@def_method(m, method)
+def _(foo: Value, bar: Value):
+    ...
+```
+
+The other is to receive the argument record directly. The `arg` name is required:
+
+```python
+def_method(m, method)
+def _(arg: Record):
+    ...
+```
+
+### Method return value conventions
+
+The `dict` syntax can be used for returning values from methods.
+Take the following method declaration:
+
+```python
+method3 = Method(input_layout=layout, output_layout=layout2)
+```
+
+One can then define this method as follows:
+
+```python
+@def_method(m, method3)
+def _(foo: Value, bar: Value):
+    return {{'foo': foo, 'bar': foo + bar}, 'baz': foo - bar}
+```
+
+### Readiness signals
+
+If a transaction is not always ready for execution (for example, because of the dependence on some resource), a `request` parameter should be used.
+An Amaranth single-bit expression should be passed.
+When the `request` parameter is not passed, the transaction is always requesting execution.
+
+```python
+        with Transaction().body(m, request=expr):
+```
+
+Methods have a similar mechanism, which uses the `ready` parameter on `def_method`:
+
+```python
+        @def_method(m, self.my_method, ready=expr)
+        def _(arg):
+            ...
+```
+
+The `request` signal typically should only depend on the internal state of an `Elaboratable`.
+Other dependencies risk introducing combinational loops.
+In certain occasions, it is possible to relax this requirement; see e.g. [Scheduling order](#scheduling-order).
+
 ## The library
 
 The transaction framework is designed to facilitate code re-use.
@@ -152,6 +254,71 @@ The most useful ones are:
 
 ## Advanced concepts
 
+### Special combinational domains
+
+Transactron defines its own variant of Amaranth modules, called `TModule`.
+Its role is to allow to improve circuit performance by omitting unneeded multiplexers in combinational circuits.
+This is done by adding two additional, special combinatorial domains, `av_comb` and `top_comb`.
+
+Statements added to the `av_comb` domain (the "avoiding" domain) are not executed when under a false `m.If`, but are executed when under a false `m.AvoidedIf`.
+Transaction and method bodies are internally guarded by an `m.AvoidedIf` with the transaction `grant` or method `run` signal.
+Therefore combinational assignments added to `av_comb` work even if the transaction or method definition containing the assignments are not running.
+Because combinational signals usually don't induce state changes, this is often safe to do and improves performance.
+
+Statements added to the `top_comb` domain are always executed, even if the statement is under false conditions (including `m.If`, `m.Switch` etc.).
+This allows for cleaner code, as combinational assignments which logically belong to some case, but aren't actually required to be there, can be as performant as if they were manually moved to the top level.
+
+An important caveat of the special domains is that, just like with normal domains, a signal assigned in one of them cannot be assigned in others.
+
+### Scheduling order
+
+When writing multiple methods and transactions in the same `Elaboratable`, sometimes some dependency between them needs to exist.
+For example, in the `Forwarder` module in the library, forwarding can take place only if both `read` and `write` are executed simultaneously.
+This requirement is handled by making the the `read` method's readiness depend on the execution of the `write` method.
+If the `read` method was considered for execution before `write`, this would introduce a combinational loop into the circuit.
+In order to avoid such issues, one can require a certain scheduling order between methods and transactions.
+
+`Method` and `Transaction` objects include a `schedule_before` method.
+Its only argument is another `Method` or `Transaction`, which will be scheduled after the first one:
+
+```python
+first_t_or_m.schedule_before(other_t_or_m)
+```
+
+Internally, scheduling orders exist only on transactions.
+If a scheduling order is added to a `Method`, it is lifted to the transaction level.
+For example, if `first_m` is scheduled before `other_t`, and is called by `t1` and `t2`, the added scheduling orderings will be the same as if the following calls were made:
+
+```python
+t1.schedule_before(other_t)
+t2.schedule_before(other_t)
+```
+
+### Conflicts
+
+In some situations it might be useful to make some methods or transactions mutually exclusive with others.
+Two conflicting transactions or methods can't execute simultaneously: only one or the other runs in a given clock cycle.
+
+Conflicts are defined similarly to scheduling orders:
+
+```python
+first_t_or_m.add_conflict(other_t_or_m)
+```
+
+Conflicts are lifted to the transaction level, just like scheduling orders.
+
+The `add_conflict` method has an optional argument `priority`, which allows to define a scheduling order between conflicting transactions or methods.
+Possible values are `Priority.LEFT`, `Priority.RIGHT` and `Priority.UNDEFINED` (the default).
+For example, the following code adds a conflict with a scheduling order, where `first_m` is scheduled before `other_m`:
+
+```python
+first_m.add_conflict(other_m, priority = Priority.LEFT)
+```
+
+Scheduling conflicts come with a possible cost.
+The conflicting transactions have a dependency in the transaction scheduler, which can increase the size and combinational delay of the scheduling circuit.
+Therefore, use of this feature requires consideration.
+
 ### Transaction and method nesting
 
 Transaction and method bodies can be nested. For example: