[tlgen/doc] Slightly expand the description of nodes and edges
This is definitely not a full set of documentation for the tlgen tool,
but it should be enough to help a reader get his or her bearings. It
also explains exactly how nodes should be named to match with the
recent changes to allow multiple devices on a block.
Signed-off-by: Rupert Swarbrick <rswarbrick@lowrisc.org>
diff --git a/doc/rm/comportability_specification/index.md b/doc/rm/comportability_specification/index.md
index 7d824b8..61817a7 100644
--- a/doc/rm/comportability_specification/index.md
+++ b/doc/rm/comportability_specification/index.md
@@ -161,7 +161,7 @@
Based upon this and the fact that much of the team history was with asynchronous active low reset, we chose that methodology with added requirements that special care be applied for security state, the details of which will come at a later date.
-### Bus Interfaces
+### Bus Interfaces {#bus-interfaces}
Peripherals can connect to the chip bus.
All peripherals are assumed to have registers, and are thus required to expose at least one device interface on the chip bus.
diff --git a/doc/rm/crossbar_tool/index.md b/doc/rm/crossbar_tool/index.md
index 0e4e7f0..3a315d9 100644
--- a/doc/rm/crossbar_tool/index.md
+++ b/doc/rm/crossbar_tool/index.md
@@ -30,12 +30,26 @@
## Configuration File Format
The `tlgen` script reads an Hjson file containing the crossbar connections and the host and device information.
-It describes a generic Directed Acyclic Graph (DAG) with some additional clock information and steering information.
+The two main sections of the configuration file are the list of nodes and the list of connections.
+Together, these describe a generic Directed Acyclic Graph (DAG) with some additional clock information and steering information.
If the tool is used in the process of top generation (`topgen.py`, details forthcoming), a few fields are derived from the top Hjson configuration module structure.
A description of Hjson and the recommended style is in the [Hjson Usage and Style Guide]({{< relref "doc/rm/hjson_usage_style" >}}).
+An item in the `nodes` list corresponds to a host or device interface on an instantiated IP block.
+The name of such a node should be of the form `<instance_name>.<interface_name>`, so the `my_if` interface on the instance `my_instance` would be denoted `my_instance.my_if`.
+However, many instances have a single, unnamed, device interface.
+For these devices, the node should just be named with the name of the instance (just `my_instance` in the example above).
+For details of how interfaces are defined using the register tool, see the [Bus Interfaces]({{< relref "doc/rm/comportability_specification#bus-interfaces" >}}) section of the Comportability Specification.
+
+Edges in the DAG are specified in the `connections` map.
+This uses an adjacency list format.
+The keys are the names of host nodes.
+The value at a host a list of the names of device nodes which that host should be able to see.
+
+### Configuration file syntax
+
The tables below describe the keys for each context.
The tool raises an error if *Required* keys are missing.
*Optional* keys may be provided in the input files.
