From 23218b3378ec57915f321e22ae7060ea454b65aa Mon Sep 17 00:00:00 2001
From: Clifford Wolf <clifford@clifford.at>
Date: Tue, 13 Nov 2018 16:08:04 +0100
Subject: Add some architecture API FAQ items

Signed-off-by: Clifford Wolf <clifford@clifford.at>
---
 docs/faq.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

(limited to 'docs/faq.md')

diff --git a/docs/faq.md b/docs/faq.md
index d440bba6..63869240 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -38,7 +38,93 @@ For nextpnr we are using the following terminology.
 Adding new architectures to nextpnr
 -----------------------------------
 
-TBD
+### Implementing new architectures
+
+Each nextpnr architecture must implement the *nextpnr architecture API*.
+See [archapi.md](archapi.md) for a complete reference of the architecture API.
+
+### Delay Estimates
+
+Each architecture must implement a `estimateDelay()` method that estimates the expected delay for a path from given `src` to `dst` wires.
+*It is very important that this method slightly overestimates the expected delay.* Otherwise there will be performance issues with the router.
+
+The delays estimates returned by that method should also be as fine-grain as possible. It definitely pays off to spend some time improving the `estimateDelay()`
+for your architecture once implementing small designs work.
+
+### Ripup Information
+
+The `getConflictingWireWire()`, `getConflictingWireNet()`, `getConflictingPipWire()`, and `getConflictingPipNet()` methods are used by the router
+to determine which resources to rip up in order to make a given routing resource (wire or pip) available.
+
+The architecture must guanrantee that the following invariants hold.
+
+**Invariant 1:**
+
+```
+    if (!ctx->checkWireAvail(wire)) {
+        WireId w = getConflictingWireWire(wire);
+        if (w != WireId()) {
+            ctx->unbindWire(w);
+            assert(ctx->checkWireAvail(wire));
+        }
+    }
+```
+
+**Invariant 2:**
+
+```
+    if (!ctx->checkWireAvail(wire)) {
+        NetInfo *n = getConflictingWireNet(wire);
+        if (n != nullptr) {
+            for (auto &it : n->wires)
+                ctx->unbindWire(it.first);
+            assert(ctx->checkWireAvail(wire));
+        }
+    }
+```
+
+**Invariant 3:**
+
+```
+    if (!ctx->checkPipAvail(pip)) {
+        WireId w = getConflictingPipWire(pip);
+        if (w != WireId()) {
+            ctx->unbindWire(w);
+            assert(ctx->checkPipAvail(pip));
+        }
+    }
+```
+
+**Invariant 4:**
+
+```
+    if (!ctx->checkPipAvail(pip)) {
+        NetInfo *n = getConflictingPipNet(pip);
+        if (n != nullptr) {
+            for (auto &it : n->wires)
+                ctx->unbindWire(it.first);
+            assert(ctx->checkPipAvail(pip));
+        }
+    }
+```
+
+**Invariant 5:**
+
+```
+    if (ctx->checkWireAvail(wire)) {
+        // bind is guaranteed to succeed
+        ctx->bindWire(wire, net, strength);
+    }
+```
+
+**Invariant 6:**
+
+```
+    if (ctx->checkPipAvail(pip) && ctx->checkWireAvail(ctx->getPipDstWire(pip))) {
+        // bind is guaranteed to succeed
+        ctx->bindPip(pip, net, strength);
+    }
+```
 
 Nextpnr and other tools
 -----------------------
-- 
cgit v1.2.3


From caca485cfff7f999a19e86e2f00187550b0c92f4 Mon Sep 17 00:00:00 2001
From: Clifford Wolf <clifford@clifford.at>
Date: Tue, 13 Nov 2018 17:30:49 +0100
Subject: Minor router1 debug log improvements

Signed-off-by: Clifford Wolf <clifford@clifford.at>
---
 docs/faq.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs/faq.md')

diff --git a/docs/faq.md b/docs/faq.md
index 63869240..7b358187 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -46,7 +46,8 @@ See [archapi.md](archapi.md) for a complete reference of the architecture API.
 ### Delay Estimates
 
 Each architecture must implement a `estimateDelay()` method that estimates the expected delay for a path from given `src` to `dst` wires.
-*It is very important that this method slightly overestimates the expected delay.* Otherwise there will be performance issues with the router.
+*It is very important that this method slightly overestimates the expected delay.* Furthermore, it should overestimate the expected delay
+by a slightly larger margin for longer paths than for shorter paths. Otherwise there will be performance issues with the router.
 
 The delays estimates returned by that method should also be as fine-grain as possible. It definitely pays off to spend some time improving the `estimateDelay()`
 for your architecture once implementing small designs work.
-- 
cgit v1.2.3