Update docs (#62)

_sources/development-environment.md.txt

@@ -20,7 +20,7 @@ Tests are run using `pytest`. Useful things to know are:
 Custom options are:
 
 * `--transactron-traces` -- generates trace files readable by `gtkwave`. The trace files are saved in `test/__traces__`.
-* `--transactron-profile` -- generates Transactron execution profiles, readable by the script named `tprof.py`. The profiles are saved in `test/__profiles__`.
+* `--transactron-profile` -- generates Transactron execution profiles, readable by the script named `transactron-prof`. The profiles are saved in `test/__profiles__`.
 * `--transactron-log-filter` -- allows to filter test logs.
 
 ## Using scripts
@@ -53,14 +53,14 @@ This way you may display the changes `black` would apply to `[filename]` if you
 
 Generates local documentation using [Sphinx](https://www.sphinx-doc.org/). The generated HTML files are located in `build/html`.
 
-### tprof.py
+### transactron-prof
 
 Processes Transactron profile files and presents them in a readable way.
 To generate a profile file, the `run_tests.py` script should be used with the `--profile` option.
-The `tprof.py` can then be run as follows:
+The script can then be run as follows:
 
 ```
-scripts/tprof.py test/__profile__/profile_file.json
+transactron-prof test/__profile__/profile_file.json
 ```
 
 This displays the profile information about transactions by default.
@@ -79,7 +79,7 @@ Counters presented in the tree shows information about the calls from the transa
 When displaying method profiles, an inverted call graph is produced: the transactions are in the leaves, and the children nodes are the callers of the method in question.
 In this mode, the `locked` field in the tree shows how many cycles a given method or transaction was responsible for locking the method in the root.
 
-Other options of `tprof.py` are:
+Other options of `transactron-prof` are:
 
 * `--sort` -- selects which column is used for sorting rows.
 * `--filter-name` -- filters rows by name. Regular expressions can be used.

_sources/transactions.md.txt

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Transactron is an Amaranth library for managing connections between modules in complex projects.
+Transactron is an [Amaranth](https://amaranth-lang.org/) library for managing connections between modules in complex projects.
 It is inspired by the [Bluespec](http://bluespec.com/) programming language (see: [Bluespec wiki](http://wiki.bluespec.com/), [Bluespec compiler](https://github.com/B-Lang-org/bsc)).
 
 The basic idea is to interface hardware modules using _transactions_ and _methods_.
@@ -17,13 +17,13 @@ If multiple transactions try to call the same method in the same clock cycle, th
 In this way, access to methods is coordinated via the transaction system to avoid conflicts.
 
 Methods can communicate with their callers in both directions: from caller to method and back.
-The communication is structured using Amaranth records.
+The communication is structured using Amaranth structures.
 
 ## Basic usage
 
 ### Implementing transactions
 
-The simplest way to implement a transaction as a part of Amaranth `Elaboratable` is by using a `with` block:
+The standard way to implement a transaction as a part of Amaranth `Elaboratable` is by using a `with` block:
 
 ```python
 class MyThing(Elaboratable):
@@ -102,18 +102,27 @@ class MyOtherThing(Elaboratable):
 The `def_method` technique presented above is a convenience syntax, but it works just like other Amaranth `with` blocks.
 In particular, the *Python code* inside the unnamed `def` function is always executed once.
 
-A method defined in one `Elaboratable` is usually passed to other `Elaboratable`s via constructor parameters.
-For example, the `MyThing` constructor could be defined as follows.
-Only methods should be passed around, not entire `Elaboratable`s!
+If a given `Elaboratable` depends on a method defined in another `Elaboratable`, it should declare it in the constructor, but not define it.
+The definition is then provided using `proxy` outside both `Elaboratable`s.
 
 ```python
 class MyThing(Elaboratable):
-    def __init__(self, method: Method):
-        self.method = method
+    def __init__(self):
+        self.method = Method(i=input_layout, o=output_layout)
 
         ...
 
     ...
+
+class LargerThing(Elaboratable):
+    def elaborate(self, platform):
+        m = TModule()
+
+        m.submodules.thing = thing = MyThing()
+        m.submodules.other_thing = other_thing = MyOtherThing()
+        thing.method.proxy(m, other_thing.my_method)
+
+        return m
 ```
 
 ### Method or transaction?
@@ -135,7 +144,7 @@ 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.
+Even though method arguments are Amaranth structures, 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
@@ -144,7 +153,7 @@ method = Method(i=layout)
 ```
 
 The method can be called in multiple ways.
-The cleanest and recommended way is to pass each record field using a keyword argument:
+The cleanest and recommended way is to pass each field using a keyword argument:
 
 ```python
 method(m, foo=foo_expr, bar=bar_expr)
@@ -156,10 +165,10 @@ Another way is to pass the arguments using a `dict`:
 method(m, {'foo': foo_expr, 'bar': bar_expr})
 ```
 
-Finally, one can directly pass an Amaranth record:
+Finally, one can directly pass an Amaranth structure:
 
 ```python
-rec = Record(layout)
+rec = Signal(layout)
 m.d.comb += rec.foo.eq(foo_expr)
 m.d.comb += rec.bar.eq(bar_expr)
 method(m, rec)
@@ -186,19 +195,19 @@ 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:
+The cleanest and recommended way is to create an argument for each 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:
+The other is to receive the argument structure directly. The `arg` name is required:
 
 ```python
-def_method(m, method)
-def _(arg: Record):
+@def_method(m, method)
+def _(arg: data.View):
     ...
 ```
 

api.html

@@ -175,7 +175,7 @@ <h2>transactron<a class="headerlink" href="#transactron" title="Permalink to thi
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>
 

development-environment.html

@@ -48,7 +48,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#using-scripts">Using scripts</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#lint-sh">lint.sh</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#build-docs-sh">build_docs.sh</a></li>
-<li class="toctree-l3"><a class="reference internal" href="#tprof-py">tprof.py</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#transactron-prof">transactron-prof</a></li>
 </ul>
 </li>
 </ul>
@@ -107,7 +107,7 @@ <h2>Running tests<a class="headerlink" href="#running-tests" title="Permalink to
 <p>Custom options are:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">--transactron-traces</span></code> – generates trace files readable by <code class="docutils literal notranslate"><span class="pre">gtkwave</span></code>. The trace files are saved in <code class="docutils literal notranslate"><span class="pre">test/__traces__</span></code>.</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">--transactron-profile</span></code> – generates Transactron execution profiles, readable by the script named <code class="docutils literal notranslate"><span class="pre">tprof.py</span></code>. The profiles are saved in <code class="docutils literal notranslate"><span class="pre">test/__profiles__</span></code>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">--transactron-profile</span></code> – generates Transactron execution profiles, readable by the script named <code class="docutils literal notranslate"><span class="pre">transactron-prof</span></code>. The profiles are saved in <code class="docutils literal notranslate"><span class="pre">test/__profiles__</span></code>.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">--transactron-log-filter</span></code> – allows to filter test logs.</p></li>
 </ul>
 </section>
@@ -137,12 +137,12 @@ <h3>lint.sh<a class="headerlink" href="#lint-sh" title="Permalink to this headin
 <h3>build_docs.sh<a class="headerlink" href="#build-docs-sh" title="Permalink to this heading"></a></h3>
 <p>Generates local documentation using <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a>. The generated HTML files are located in <code class="docutils literal notranslate"><span class="pre">build/html</span></code>.</p>
 </section>
-<section id="tprof-py">
-<h3>tprof.py<a class="headerlink" href="#tprof-py" title="Permalink to this heading"></a></h3>
+<section id="transactron-prof">
+<h3>transactron-prof<a class="headerlink" href="#transactron-prof" title="Permalink to this heading"></a></h3>
 <p>Processes Transactron profile files and presents them in a readable way.
 To generate a profile file, the <code class="docutils literal notranslate"><span class="pre">run_tests.py</span></code> script should be used with the <code class="docutils literal notranslate"><span class="pre">--profile</span></code> option.
-The <code class="docutils literal notranslate"><span class="pre">tprof.py</span></code> can then be run as follows:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">scripts</span><span class="o">/</span><span class="n">tprof</span><span class="o">.</span><span class="n">py</span> <span class="n">test</span><span class="o">/</span><span class="n">__profile__</span><span class="o">/</span><span class="n">profile_file</span><span class="o">.</span><span class="n">json</span>
+The script can then be run as follows:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">transactron</span><span class="o">-</span><span class="n">prof</span> <span class="n">test</span><span class="o">/</span><span class="n">__profile__</span><span class="o">/</span><span class="n">profile_file</span><span class="o">.</span><span class="n">json</span>
 </pre></div>
 </div>
 <p>This displays the profile information about transactions by default.
@@ -159,7 +159,7 @@ <h3>tprof.py<a class="headerlink" href="#tprof-py" title="Permalink to this head
 Counters presented in the tree shows information about the calls from the transaction in the root of the tree: if a method is also called by a different transaction, these calls are not counted.
 When displaying method profiles, an inverted call graph is produced: the transactions are in the leaves, and the children nodes are the callers of the method in question.
 In this mode, the <code class="docutils literal notranslate"><span class="pre">locked</span></code> field in the tree shows how many cycles a given method or transaction was responsible for locking the method in the root.</p>
-<p>Other options of <code class="docutils literal notranslate"><span class="pre">tprof.py</span></code> are:</p>
+<p>Other options of <code class="docutils literal notranslate"><span class="pre">transactron-prof</span></code> are:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">--sort</span></code> – selects which column is used for sorting rows.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">--filter-name</span></code> – filters rows by name. Regular expressions can be used.</p></li>
@@ -181,7 +181,7 @@ <h3>tprof.py<a class="headerlink" href="#tprof-py" title="Permalink to this head
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>
 

genindex.html

@@ -1999,7 +1999,7 @@ <h2 id="W">W</h2>
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>
 

index.html

@@ -80,7 +80,7 @@ <h1>Transactron<a class="headerlink" href="#transactron" title="Permalink to thi
 <li class="toctree-l2"><a class="reference internal" href="development-environment.html#using-scripts">Using scripts</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="development-environment.html#lint-sh">lint.sh</a></li>
 <li class="toctree-l3"><a class="reference internal" href="development-environment.html#build-docs-sh">build_docs.sh</a></li>
-<li class="toctree-l3"><a class="reference internal" href="development-environment.html#tprof-py">tprof.py</a></li>
+<li class="toctree-l3"><a class="reference internal" href="development-environment.html#transactron-prof">transactron-prof</a></li>
 </ul>
 </li>
 </ul>
@@ -129,7 +129,7 @@ <h1>Transactron<a class="headerlink" href="#transactron" title="Permalink to thi
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>
 

modules.html

@@ -161,7 +161,7 @@ <h1>transactron<a class="headerlink" href="#transactron" title="Permalink to thi
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>
 

py-modindex.html

@@ -363,7 +363,7 @@ <h1>Python Module Index</h1>
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>
 

search.html

@@ -91,7 +91,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright Kuźnia Rdzeni, 2025.
-      <span class="lastupdated">Last updated on 21:23 2025-03-04.
+      <span class="lastupdated">Last updated on 19:59 2025-03-06.
       </span></p>
   </div>