[DOC] refactor openlane docs + support it in make README.rst
diff --git a/Makefile b/Makefile
index 5c27250..4747b95 100644
--- a/Makefile
+++ b/Makefile
@@ -245,7 +245,13 @@
endif
# Make README.rst
-README.rst: README.src.rst docs/source/getting_started.rst docs/source/tool_versioning.rst Makefile
+README.rst: README.src.rst docs/source/getting_started.rst docs/source/tool_versioning.rst openlane/README.src.rst docs/source/caravel_with_openlane.rst Makefile
pip -q install rst_include && \
rm -f README.rst && \
- rst_include include README.src.rst - > README.rst
\ No newline at end of file
+ rst_include include README.src.rst - | sed -e's@\.\/\_static@\/docs\/source\/\_static@g' > README.rst && \
+ rst_include include openlane/README.src.rst - | \
+ sed \
+ -e's@https://github.com/efabless/caravel/blob/master/verilog@../verilog@g' \
+ -e's@:ref:`getting-started`@`README.rst <../README.rst>`__@g' \
+ -e's@https://github.com/efabless/caravel/blob/master/openlane/@./@g' \
+ > openlane/README.rst
\ No newline at end of file
diff --git a/docs/source/caravel_with_openlane.rst b/docs/source/caravel_with_openlane.rst
new file mode 100644
index 0000000..c9c0d0e
--- /dev/null
+++ b/docs/source/caravel_with_openlane.rst
@@ -0,0 +1,207 @@
+.. raw:: html
+
+ <!---
+ # SPDX-FileCopyrightText: 2020 Efabless Corporation
+ #
+ # Licensed under the Apache License, Version 2.0 (the "License");
+ # you may not use this file except in compliance with the License.
+ # You may obtain a copy of the License at
+ #
+ # http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS,
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ # See the License for the specific language governing permissions and
+ # limitations under the License.
+ #
+ # SPDX-License-Identifier: Apache-2.0
+ -->
+
+.. _carave-with-openlane:
+
+Using OpenLANE to Harden Your Design
+====================================
+
+You can utilize the Makefile existing here in this directory to do that.
+
+But, first you need to specify 2 things:
+
+.. code:: bash
+
+ export PDK_ROOT=<The location where the pdk is installed>
+ export OPENLANE_ROOT=<the absolute path to the openlane directory cloned or to be cloned>
+
+**NOTE:** caravel is still a WIP so expect to run into some issues when
+using it.
+
+If you don't have openlane already, then you can get it from
+`here <https://github.com/efabless/openlane>`__. Alternatively, you can
+clone and build openlane through:
+
+.. code:: bash
+
+ make openlane
+
+**NOTE:** We are developing caravel using openlane:rc6 which is the
+current master branch.
+
+**NOTE:** rc6 (current openlane master) and rc4 (previous openlane
+master) are using two different concepts of cell padding. rc4 is
+modifying the LEF, while rc6 is relying on openroad to handle the cell
+padding. Also, rc4 is using the standalone version of openDP while rc6
+is using the one integrated in the openroad app. This affects the
+concept of PL\_TARGET\_DENSITY and while in rc4 it was preferred to have
+PL\_TARGET\_DENSITY=(FP\_CORE\_UTIL-(5\~10)/100). Now, in rc6 it is
+preferred to be PL\_TARGET\_DENSITY=(FP\_CORE\_UTIL+(1\~5)/100).
+| FP\_CORE\_UTIL should be relaxed as well as it became more
+representative of the actual core utilization, which wasn't so much the
+case earlier. So, the perception of these two variables as well as
+CELL\_PAD changed between rc4 and rc6 which necessitates a change in the
+configurations of almost every single design.
+| CELL\_PAD should be 4\~6 for the skywater libraries in rc6 unlike rc4
+which was 8.
+
+Then, you have two options:
+
+#. Create a macro for your design and harden it, then insert it into
+ user\_project\_wrapper.
+
+#. Flatten your design with the user\_project\_wrapper and harden them
+ as one.
+
+**NOTE:** The OpenLANE documentation should cover everything you might
+need to create your design. You can find that
+`here <https://github.com/efabless/openlane/blob/master/README.md>`__.
+
+Option 1
+--------
+
+This could be done by creating a directory for your design here in this
+directory, and adding a configuration file for it under the same
+directory. You can follow the instructions given
+`here <https://github.com/efabless/openlane#adding-a-design>`__ to
+generate an initial configuration file for your design, or you can start
+with the following:
+
+.. code:: tcl
+
+ set script_dir [file dirname [file normalize [info script]]]
+
+ set ::env(DESIGN_NAME) <Your Design Name>
+
+ set ::env(DESIGN_IS_CORE) 0
+ set ::env(FP_PDN_CORE_RING) 0
+ set ::env(GLB_RT_MAXLAYER) 5
+
+ set ::env(VERILOG_FILES) "$script_dir/../../verilog/rtl/<Your RTL.v>"
+
+ set ::env(CLOCK_PORT) <Clock port name if it exists>
+ set ::env(CLOCK_PERIOD) <Desired clock period>
+
+Then you can add them as you see fit to get the desired DRC/LVS clean
+outcome.
+
+After that, run the following command:
+
+.. code:: bash
+
+ make <your design directory name>
+
+Then, follow the instructions given in Option 2.
+
+**NOTE:** You might have other macros inside your design. In which case,
+you may need to have some special power configurations. This is covered
+`here <https://github.com/efabless/openlane/blob/master/doc/hardening_macros.md#power-grid-pdn>`__.
+
+Option 2
+--------
+
+#. Add your design to the RTL of the
+ `user\_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/user_project_wrapper.v>`__.
+
+#. Modify the configuration file `here <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper/config.tcl>`__ to include any extra
+ files you may need. Make sure to change these accordingly:
+
+.. code:: tcl
+
+ set ::env(CLOCK_NET) "mprj.clk"
+ set ::env(VERILOG_FILES) "\\
+ $script_dir/../../verilog/rtl/defines.v \\
+ $script_dir/../../verilog/rtl/user_project_wrapper.v"
+
+ set ::env(VERILOG_FILES_BLACKBOX) "\\
+ $script_dir/../../verilog/rtl/defines.v \\
+ $script_dir/../../verilog/rtl/user_proj_example.v"
+
+ set ::env(EXTRA_LEFS) "\\
+ $script_dir/../../lef/user_proj_example.lef"
+
+ set ::env(EXTRA_GDS_FILES) "\\
+ $script_dir/../../gds/user_proj_example.gds"
+
+
+
+| **NOTE:** Don't change the size or the pin order!
+
+#. If your design has standard cells then you need to modify the
+ configuration file `here <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper/config.tcl>`__ to
+ remove or change these configs accordingly:
+
+ .. code:: tcl
+
+ # The following is because there are no std cells in the example wrapper project.
+ set ::env(SYNTH_TOP_LEVEL) 1
+ set ::env(PL_RANDOM_GLB_PLACEMENT) 1
+ set ::env(PL_OPENPHYSYN_OPTIMIZATIONS) 0
+ set ::env(DIODE_INSERTION_STRATEGY) 0
+ set ::env(FILL_INSERTION) 0
+ set ::env(TAP_DECAP_INSERTION) 0
+ set ::env(CLOCK_TREE_SYNTH) 0
+
+#. Remove this line
+ ``set ::env(MACRO_PLACEMENT_CFG) $script_dir/macro.cfg`` from the
+ configuration file `here <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper/config.tcl>`__
+ entirely if you have no macros. Alternatively, if you do have macros
+ inside your design, then control their placement by modifying `this
+ file <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper/macro.cfg>`__
+
+#. Run your design through the flow: ``make user_project_wrapper``
+
+#. You may want to take a look at the `Extra
+ Pointers <#extra-pointers>`__ to apply any necessary changes to the
+ interactive script.
+
+#. Re-iterate until you have what you want.
+
+#. Go back to the main :ref:`getting-started` and continue the
+ process of boarding the chip.
+
+**NOTE:** In both cases you might have other macros inside your design.
+In which case, you may need to have some special power configurations.
+This is covered
+`here <https://github.com/efabless/openlane/blob/master/doc/hardening_macros.md#power-grid-pdn>`__.
+
+Extra Pointers
+--------------
+
+- The OpenLANE documentation should cover everything you might need to
+ create your design. You can find that
+ `here <https://github.com/efabless/openlane/blob/master/README.md>`__.
+- The OpenLANE `FAQs <https://github.com/efabless/openlane/wiki>`__ can
+ guide through your troubles.
+- `Here <https://github.com/efabless/openlane/blob/master/configuration/README.md>`__
+ you can find all the configurations and how to use them.
+- `Here <https://github.com/efabless/openlane/blob/master/doc/advanced_readme.md>`__
+ you can learn how to write an interactive script.
+- `Here <https://github.com/efabless/openlane/blob/master/doc/OpenLANE_commands.md>`__
+ you can find a full documentation for all OpenLANE commands.
+- `This
+ documentation <https://github.com/efabless/openlane/blob/master/regression_results/README.md>`__
+ describes how to use the exploration script to achieve an LVS/DRC
+ clean design.
+- `This
+ documentation <https://github.com/efabless/openlane/blob/master/doc/hardening_macros.md>`__
+ walks you through hardening a macro and all the decisions you should
+ make.
+
diff --git a/openlane/README.rst b/openlane/README.rst
index 34bf8ef..4aeb76e 100644
--- a/openlane/README.rst
+++ b/openlane/README.rst
@@ -18,8 +18,30 @@
# SPDX-License-Identifier: Apache-2.0
-->
-Using OpenLANE to Harden Your Design:
-=====================================
+.. raw:: html
+
+ <!---
+ # SPDX-FileCopyrightText: 2020 Efabless Corporation
+ #
+ # Licensed under the Apache License, Version 2.0 (the "License");
+ # you may not use this file except in compliance with the License.
+ # You may obtain a copy of the License at
+ #
+ # http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS,
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ # See the License for the specific language governing permissions and
+ # limitations under the License.
+ #
+ # SPDX-License-Identifier: Apache-2.0
+ -->
+
+.. _carave-with-openlane:
+
+Using OpenLANE to Harden Your Design
+====================================
You can utilize the Makefile existing here in this directory to do that.
@@ -72,8 +94,8 @@
need to create your design. You can find that
`here <https://github.com/efabless/openlane/blob/master/README.md>`__.
-Option 1:
----------
+Option 1
+--------
This could be done by creating a directory for your design here in this
directory, and adding a configuration file for it under the same
@@ -112,8 +134,8 @@
you may need to have some special power configurations. This is covered
`here <https://github.com/efabless/openlane/blob/master/doc/hardening_macros.md#power-grid-pdn>`__.
-Option 2:
----------
+Option 2
+--------
#. Add your design to the RTL of the
`user\_project\_wrapper <../verilog/rtl/user_project_wrapper.v>`__.
@@ -123,20 +145,20 @@
.. code:: tcl
- set ::env(CLOCK\_NET) "mprj.clk"
- set ::env(VERILOG\_FILES) "\\
- $script\_dir/../../verilog/rtl/defines.v \\
- $script\_dir/../../verilog/rtl/user\_project\_wrapper.v"
+ set ::env(CLOCK_NET) "mprj.clk"
+ set ::env(VERILOG_FILES) "\\
+ $script_dir/../../verilog/rtl/defines.v \\
+ $script_dir/../../verilog/rtl/user_project_wrapper.v"
- set ::env(VERILOG\_FILES\_BLACKBOX) "\\
- $script\_dir/../../verilog/rtl/defines.v \\
- $script\_dir/../../verilog/rtl/user\_proj\_example.v"
+ set ::env(VERILOG_FILES_BLACKBOX) "\\
+ $script_dir/../../verilog/rtl/defines.v \\
+ $script_dir/../../verilog/rtl/user_proj_example.v"
- set ::env(EXTRA\_LEFS) "\\
- $script\_dir/../../lef/user\_proj\_example.lef"
+ set ::env(EXTRA_LEFS) "\\
+ $script_dir/../../lef/user_proj_example.lef"
- set ::env(EXTRA\_GDS\_FILES) "\\
- $script\_dir/../../gds/user\_proj\_example.gds"
+ set ::env(EXTRA_GDS_FILES) "\\
+ $script_dir/../../gds/user_proj_example.gds"
diff --git a/openlane/README.src.rst b/openlane/README.src.rst
new file mode 100644
index 0000000..d940c48
--- /dev/null
+++ b/openlane/README.src.rst
@@ -0,0 +1,22 @@
+.. raw:: html
+
+ <!---
+ # SPDX-FileCopyrightText: 2020 Efabless Corporation
+ #
+ # Licensed under the Apache License, Version 2.0 (the "License");
+ # you may not use this file except in compliance with the License.
+ # You may obtain a copy of the License at
+ #
+ # http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS,
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ # See the License for the specific language governing permissions and
+ # limitations under the License.
+ #
+ # SPDX-License-Identifier: Apache-2.0
+ -->
+
+
+.. include:: ../docs/source/caravel_with_openlane.rst
\ No newline at end of file
