From 796428d848f1d66b91f072a56734be9045a81b77 Mon Sep 17 00:00:00 2001
From: tangxifan <tangxifan@gmail.com>
Date: Thu, 17 Feb 2022 14:22:21 -0800
Subject: [PATCH] [Doc] Add documentation about bus group file format

---
 .../manual/file_formats/bus_group_file.rst    | 48 +++++++++++++++++++
 docs/source/manual/file_formats/index.rst     |  2 +
 2 files changed, 50 insertions(+)
 create mode 100644 docs/source/manual/file_formats/bus_group_file.rst

diff --git a/docs/source/manual/file_formats/bus_group_file.rst b/docs/source/manual/file_formats/bus_group_file.rst
new file mode 100644
index 000000000..499db8900
--- /dev/null
+++ b/docs/source/manual/file_formats/bus_group_file.rst
@@ -0,0 +1,48 @@
+.. _file_format_bus_group_file:
+
+Bus Group File (.xml)
+=====================
+
+The bus group file aims to show 
+
+- How bus ports are flatten by EDA engines, e.g., synthesis.
+- What are the pins in post-routing corresponding to the bus ports before synthesis
+
+An example of file is shown as follows.
+
+.. code-block:: xml
+
+  <bus_groups>
+    <bus name="i_addr" lsb="0" msb="3">
+      <pin id="0" name="i_addr_0_"/>
+      <pin id="1" name="i_addr_1_"/>
+      <pin id="2" name="i_addr_2_"/>
+      <pin id="3" name="i_addr_3_"/>
+    </bus>
+  </bus_groups>
+
+Bus-related Syntax
+------------------
+
+.. option:: name="<string>"
+
+  The bus port name defined before synthesis.
+
+.. option:: lsb="<int>"
+
+  The *Least Significant Bit* (LSB) of the bus
+
+.. option:: msb="<int>"
+
+  The *Most Significant Bit* (MSB) of the bus
+
+Pin-related Syntax
+------------------
+
+.. option:: id="<int>"
+
+  The index of the current pin in a bus port. The index must be the range of **[LSB, MSB-1]** that are defined in the bus.
+
+.. option:: name="<string>"
+
+  The pin name after bus flatten in synthesis results
diff --git a/docs/source/manual/file_formats/index.rst b/docs/source/manual/file_formats/index.rst
index 7ed213012..c00f46b6b 100644
--- a/docs/source/manual/file_formats/index.rst
+++ b/docs/source/manual/file_formats/index.rst
@@ -25,3 +25,5 @@ OpenFPGA widely uses XML format for interchangable files
    io_mapping_file
 
    bitstream_distribution_file
+
+   bus_group_file