[fpga] Update documentation based on 8138 analysis
Signed-off-by: Timothy Chen <timothytim@google.com>
diff --git a/doc/ug/getting_started_fpga.md b/doc/ug/getting_started_fpga.md
index 452a56d..74b35b5 100644
--- a/doc/ug/getting_started_fpga.md
+++ b/doc/ug/getting_started_fpga.md
@@ -61,6 +61,13 @@
The resulting bitstream is located at `build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit`.
See the [reference manual]({{< relref "ref_manual_fpga.md" >}}) for more information.
+### Dealing with FPGA Congestion Issues
+
+The default Vivado tool placement may sometimes result in congested FPGA floorplans.
+When this happens, the implemenation time and results become unpredictable.
+It may become necessary for the user to manually adjust certain placement.
+See [this comment](https://github.com/lowRISC/opentitan/pull/8138#issuecomment-916696830) for a thorough analysis of one such situation and what changes were made to improve congestion.
+
## Connecting the ChipWhisperer CW310 board
The ChipWhisperer CW310 board supports different power options.
diff --git a/hw/top_earlgrey/data/placement.xdc b/hw/top_earlgrey/data/placement.xdc
index 6b709235..91e6dbf 100644
--- a/hw/top_earlgrey/data/placement.xdc
+++ b/hw/top_earlgrey/data/placement.xdc
@@ -1,3 +1,11 @@
+# While the code below looks messy, it was taken directly from a vivado example
+# See here (https://www.xilinx.com/support/answers/66386.html)
+# See also this link (https://github.com/lowRISC/opentitan/pull/8138#issuecomment-916696830)
+# for a thorough explanation of why such a custom placement helps.
+# Note the placement location was not chosen through any systematic means, but through trial
+# and error, it may become necessary in the future to tweak this if other congestion
+# issues arise.
+
# Clock net "top_earlgrey/u_clkmgr_aon/u_clk_main_aes_cg/gen_xilinx.u_impl_xilinx/clocks_o[clk_main_aes]" driven by instance "top_earlgrey/u_clkmgr_aon/u_clk_main_aes_cg/gen_xilinx.u_impl_xilinx/gen_gate.gen_bufhce.u_bufhce" located at site "BUFHCE_X1Y0"
#startgroup
create_pblock {CLKAG_top_earlgrey/u_clkmgr_aon/u_clk_main_aes_cg/gen_xilinx.u_impl_xilinx/clocks_o[clk_main_aes]}
