From 1884e4b9786ae660d02a8c3c1151be682058bf36 Mon Sep 17 00:00:00 2001
From: Keith Rothman <537074+litghost@users.noreply.github.com>
Date: Thu, 18 Mar 2021 09:41:54 -0700
Subject: Add initial pseudo cell documentation.

Signed-off-by: Keith Rothman <537074+litghost@users.noreply.github.com>
---
 docs/pseudo_cells.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 docs/pseudo_cells.md

diff --git a/docs/pseudo_cells.md b/docs/pseudo_cells.md
new file mode 100644
index 0000000..064c656
--- /dev/null
+++ b/docs/pseudo_cells.md
@@ -0,0 +1,36 @@
+## Pseudo Cells
+
+Pseudo PIPs and site pseudo PIPs are edges in the device graph that route
+through other sites and/or BELs.  Pseudo cells are the expression of the what
+routing resources are "blocked" by the use of a pseudo PIP.
+
+The device database currently expresses pseudo PIPs as using BEL pins within
+the site that the pseudo PIP is attached too.  Both input and output BEL pins
+are included in the pseudo cell definition, but only output BEL pins "block"
+the site wire.
+
+### Example
+
+In the case of a `CLBLL`'s `CLBLL_LL_A1` to `CLBLL_LL_A` pseudo PIP, this PIP
+connects a signal from an input site port to an output site port.  Each site
+wire that is consumed has **both** a output BEL pin (from the site wire
+source) and a input BEL pin (connected to either a logic BEL, e.g. `A6LUT` or
+routing BEL, e.g. `AUSED` or output site port BEL, e.g. `A`).
+
+In the case of a `CLBLL`'s `CLBLL_LL_A` to `CLBLL_LL_AMUX` pseudo PIP, this
+PIP connects a signal from an output site port to an output site port.  In
+this case, it is assumed and required that some of the site wires are already
+bound to the relevant net (by virtue of the wire `CLBLL_LL_A` already being
+part of the net).  In this case, the first BEL pin will be an input BEL pin
+(specifically `AOUTMUX/O6`) that indicates that a site PIP is used as part of
+the pseudo PIP.  However in this case, this edge does **not** block the site
+wire, instead it only requires it.  The following output BEL pin (specifically
+ `AOUTMUX/OUT`) blocks the site wire `AMUX`.
+
+### Future enhancements
+
+Pseudo cells right now only have BEL pins used by the pseudo PIP.  This
+ignores the fact that some BEL's when route through may have constraint
+implications.  For example, routing through a LUT BEL requires that it be in
+LUT mode.  If that BEL is in either a SRL or LUT-RAM mode, the LUT route
+through may not operate properly.
-- 
cgit v1.2.3


From d0a0a0bf38434a257dd8493791fcc266fb58d53d Mon Sep 17 00:00:00 2001
From: Keith Rothman <537074+litghost@users.noreply.github.com>
Date: Thu, 18 Mar 2021 13:08:20 -0700
Subject: Clarify some lines based on review comments.

Signed-off-by: Keith Rothman <537074+litghost@users.noreply.github.com>
---
 docs/pseudo_cells.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/pseudo_cells.md b/docs/pseudo_cells.md
index 064c656..a55fc44 100644
--- a/docs/pseudo_cells.md
+++ b/docs/pseudo_cells.md
@@ -1,7 +1,7 @@
 ## Pseudo Cells
 
 Pseudo PIPs and site pseudo PIPs are edges in the device graph that route
-through other sites and/or BELs.  Pseudo cells are the expression of the what
+through other sites and/or BELs.  Pseudo cells are the expression of what
 routing resources are "blocked" by the use of a pseudo PIP.
 
 The device database currently expresses pseudo PIPs as using BEL pins within
@@ -11,11 +11,12 @@ the site wire.
 
 ### Example
 
-In the case of a `CLBLL`'s `CLBLL_LL_A1` to `CLBLL_LL_A` pseudo PIP, this PIP
-connects a signal from an input site port to an output site port.  Each site
-wire that is consumed has **both** a output BEL pin (from the site wire
-source) and a input BEL pin (connected to either a logic BEL, e.g. `A6LUT` or
-routing BEL, e.g. `AUSED` or output site port BEL, e.g. `A`).
+In the case of a Xilinx 7-series `CLBLL`'s `CLBLL_LL_A1` to `CLBLL_LL_A`
+pseudo PIP, this PIP connects a signal from an input site port to an output
+site port.  Each site wire that is consumed has **both** a output BEL pin
+(from the site wire source) and a input BEL pin (connected to either a logic
+BEL, e.g. `A6LUT` or routing BEL, e.g. `AUSED` or output site port BEL, e.g.
+`A`).
 
 In the case of a `CLBLL`'s `CLBLL_LL_A` to `CLBLL_LL_AMUX` pseudo PIP, this
 PIP connects a signal from an output site port to an output site port.  In
-- 
cgit v1.2.3