common: Add JSON timing and utilisation report

Signed-off-by: gatecat <gatecat@ds0.me>

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/report.md b/docs/report.md
new file mode 100644
index 00000000..a766bb3d
--- /dev/null
+++ b/docs/report.md
@@ -0,0 +1,22 @@
+# JSON Reports
+
+nextpnr can write a JSON report using `--report` post-place-and-route for integration with other build systems. It contains information on post-pack utilization and maximum achieved frequency for each clock domain, and is of the following format:
+
+```
+{
+    "utilization": {
+        <beltype>: {
+            "used": <number of bels used in design>,
+            "available": <total number of bels available in device>
+        }, 
+        ...
+    },
+    "fmax": {
+        <clock domain>: {
+            "achieved": <computed Fmax of routed design for clock in MHz>,
+            "constraint": <constraint for clock in MHz>
+        },
+        ...
+    }
+}
+```