docs: Add a diagram showing legal/illegal site pip usage

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

2 files changed, 185 insertions, 1 deletions

diff --git a/docs/device_resources.md b/docs/device_resources.md
index 323e177..9793098 100644
--- a/docs/device_resources.md
+++ b/docs/device_resources.md
@@ -242,6 +242,10 @@ entered via the site port corresponding to the site pin. The first site wire
 in the site will be the site wire attached to the output BEL pin of the site
 port.  From there site routing continues per above.
 
+![Wire and nodes](https://symbiflow.readthedocs.io/projects/arch-defs/en/latest/_images/rrgraph-wire.svg)
+
+### Use of site PIPs
+
 It is important to note that site PIPs can only be used to access placed cells
 inside that site. Site PIPs cannot be used as general route-thrus, to route
 from site input to output. General route-thrus across entire sites should use
@@ -255,7 +259,9 @@ an associated flipflop input inside the site. The tile PIP would be used to
 route across the entire site as part of the general, inter-tile, routing
 problem.
 
-![Wire and nodes](https://symbiflow.readthedocs.io/projects/arch-defs/en/latest/_images/rrgraph-wire.svg)
+A diagram illustrating the legal and illegal uses is shown below.
+
+![Site PIP usage](site_pip_usage.svg)
 
 ### Tile Types and site types
 
diff --git a/docs/site_pip_usage.svg b/docs/site_pip_usage.svg
new file mode 100644
index 0000000..ebf5721
--- /dev/null
+++ b/docs/site_pip_usage.svg
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="38cm" height="33cm" viewBox="359 779 758 642" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <rect style="fill: #ffffff" x="400" y="780" width="500" height="640"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="400" y="780" width="500" height="640"/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="460" y="820" width="120" height="160"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="460" y="820" width="120" height="160"/>
+    <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="903.881">
+      <tspan x="520" y="903.881"></tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="480" y="860" width="80" height="120"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="480" y="860" width="80" height="120"/>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="844.431">
+    <tspan x="520" y="844.431">LUT6</tspan>
+  </text>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="884.245">
+    <tspan x="520" y="884.245">LUT5</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="940" x2="360" y2="940"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="480" y1="920" x2="360" y2="920"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="900" x2="360" y2="900"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="880" x2="360" y2="880"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="960" x2="360" y2="960"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="460" y1="840" x2="360" y2="840"/>
+  <g>
+    <rect style="fill: #90ee90" x="720" y="900" width="80" height="80"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #008000" x="720" y="900" width="80" height="80"/>
+    <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="760" y="943.881">
+      <tspan x="760" y="943.881"></tspan>
+    </text>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="760" y="924.245">
+    <tspan x="760" y="924.245">DFF</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="580" y1="840" x2="940" y2="840"/>
+  <g>
+    <polygon style="fill: #ffffff" points="840,940 860,920 860,880 840,860 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="840,940 860,920 860,880 840,860 "/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="700" y1="940" x2="720" y2="940"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="640" y1="880" x2="840" y2="880"/>
+  <g>
+    <polygon style="fill: #ffffff" points="680,980 700,960 700,920 680,900 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="680,980 700,960 700,920 680,900 "/>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="620,840 660,840 660,920 680,920 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" points="560,880 640,880 640,960 680,960 "/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="860" y1="900" x2="940" y2="900"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="800" y1="920" x2="840" y2="920"/>
+  <g>
+    <rect style="fill: #ffffff" x="460" y="1020" width="120" height="160"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="460" y="1020" width="120" height="160"/>
+    <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="1103.88">
+      <tspan x="520" y="1103.88"></tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="480" y="1060" width="80" height="120"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="480" y="1060" width="80" height="120"/>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="1044.43">
+    <tspan x="520" y="1044.43">LUT6</tspan>
+  </text>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="1084.43">
+    <tspan x="520" y="1084.43">LUT5</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1140" x2="360" y2="1140"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1100" x2="360" y2="1100"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="480" y1="1120" x2="360" y2="1120"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1080" x2="360" y2="1080"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1160" x2="360" y2="1160"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="460" y1="1040" x2="360" y2="1040"/>
+  <g>
+    <rect style="fill: #ffffff" x="720" y="1100" width="80" height="80"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="720" y="1100" width="80" height="80"/>
+    <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="760" y="1143.88">
+      <tspan x="760" y="1143.88"></tspan>
+    </text>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="760" y="1124.43">
+    <tspan x="760" y="1124.43">DFF</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="580" y1="1040" x2="940" y2="1040"/>
+  <g>
+    <polygon style="fill: #ffffff" points="840,1140 860,1120 860,1080 840,1060 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="840,1140 860,1120 860,1080 840,1060 "/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="700" y1="1140" x2="720" y2="1140"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="560" y1="1080" x2="840" y2="1080"/>
+  <g>
+    <polygon style="fill: #ffffff" points="680,1180 700,1160 700,1120 680,1100 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="680,1180 700,1160 700,1120 680,1100 "/>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="620,1040 660,1040 660,1120 680,1120 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,1080 640,1080 640,1160 680,1160 "/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="860" y1="1100" x2="940" y2="1100"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="800" y1="1120" x2="840" y2="1120"/>
+  <g>
+    <rect style="fill: #90ee90" x="460" y="1220" width="120" height="160"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #008000" x="460" y="1220" width="120" height="160"/>
+    <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="1303.88">
+      <tspan x="520" y="1303.88"></tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="480" y="1260" width="80" height="120"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="480" y="1260" width="80" height="120"/>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="1244.43">
+    <tspan x="520" y="1244.43">LUT6</tspan>
+  </text>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="520" y="1284.43">
+    <tspan x="520" y="1284.43">LUT5</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1340" x2="360" y2="1340"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="460" y1="1320" x2="360" y2="1320"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1300" x2="360" y2="1300"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1280" x2="360" y2="1280"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="480" y1="1360" x2="360" y2="1360"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="460" y1="1240" x2="360" y2="1240"/>
+  <g>
+    <rect style="fill: #ffffff" x="720" y="1300" width="80" height="80"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="720" y="1300" width="80" height="80"/>
+    <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="760" y="1343.88">
+      <tspan x="760" y="1343.88"></tspan>
+    </text>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="760" y="1324.43">
+    <tspan x="760" y="1324.43">DFF</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="580" y1="1240" x2="940" y2="1240"/>
+  <g>
+    <polygon style="fill: #ffffff" points="840,1340 860,1320 860,1280 840,1260 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="840,1340 860,1320 860,1280 840,1260 "/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="700" y1="1340" x2="720" y2="1340"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="560" y1="1280" x2="840" y2="1280"/>
+  <g>
+    <polygon style="fill: #ffffff" points="680,1380 700,1360 700,1320 680,1300 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="680,1380 700,1360 700,1320 680,1300 "/>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="660,1240 660,1240 660,1320 680,1320 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,1280 640,1280 640,1360 680,1360 "/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 20 8 4 8; stroke: #ff0000" x1="860" y1="1300" x2="940" y2="1300"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="800" y1="1320" x2="840" y2="1320"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="480" y1="920" x2="560" y2="880"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="680" y1="960" x2="700" y2="940"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #008000" x1="840" y1="920" x2="860" y2="900"/>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="940" y="940">
+    <tspan x="940" y="940">Legal - site routing</tspan>
+    <tspan x="940" y="956">used to access DFF</tspan>
+    <tspan x="940" y="972">input and output</tspan>
+  </text>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="940" y="1120">
+    <tspan x="940" y="1120">Illegal - not being</tspan>
+    <tspan x="940" y="1136">used to access bound</tspan>
+    <tspan x="940" y="1152">bel inside site; tile PIP</tspan>
+    <tspan x="940" y="1168">should be used instead</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="480" y1="1120" x2="560" y2="1080"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="840" y1="1080" x2="860" y2="1100"/>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="940" y="1320">
+    <tspan x="940" y="1320">Illegal - red dashed</tspan>
+    <tspan x="940" y="1336">part not being used to</tspan>
+    <tspan x="940" y="1352">access bound bel inside</tspan>
+    <tspan x="940" y="1368">site; tile PIP should be used</tspan>
+    <tspan x="940" y="1384">instead for that part</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="480" y1="1320" x2="560" y2="1280"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="480" y1="1320" x2="460" y2="1320"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 10 4 2 4; stroke: #ff0000" x1="840" y1="1280" x2="860" y2="1300"/>
+</svg>