openlane/docs/source/chip_integration.md - third_party/shuttle/sky130/mpw-006/slot-033 - Git at Google

 **DISCLAIMER: THIS PAGE IS STILL UNDER DEVELOPMENT.**
 **THE INFORMATION HERE MIGHT BE INCORRECT OR OUTDATED.**

 # Chip Integration

 Using openlane, you can produce a GDSII from a chip RTL.


 ## The current Methodology

 The current methodology views the chip using the following hierarchy:
 - Chip Core
     - The hard macros
     - The rest of the design
 - Chip IO
     - IO Pads
     - Power Pads
     - Corener Pads

 The current methodology goes as follows:
 1. Hardening the hard macros.
 2. Hardening the core with the hard macros inside it.
 3. Hardening the padframe
 4. Hardening the full chip with the padframe.


 ## Hardening The Macros

 This is discussed in more detail [here][8].

 ## Hardening The Core

 The chip core would usually have other macros inside it.

 You need to set the following environment variables in your `config.tcl` file for the chip core:
 - `::env(VERILOG_FILES)` To point at the used verilog files; those that were not previously hardened.
 - `::env(VERILOG_FILES_BLACKBOX)` To point at the blackboxes (the hardened macros).
 - `::env(EXTRA_LEFS)` To point at the LEF files of the hardened macros.
 - `::env(EXTRA_GDS_FILES)` To point at the GDS files of the hardened macros.

 Therefore, the verilog files shouldn't have any includes in any of your verilog files. But use `::env(VERILOG_FILES)` and `::env(VERILOG_FILES_BLACKBOX)` for that purpose.

 Add `set ::env(SYNTH_READ_BLACKBOX_LIB) 1`, if you have std cells hard coded in your RTL.

 You can follow the same instructions provided [here][8] for the rest of the hardenning steps.

 In case you want to manually place the macros in specific locations, [this][9] should provide a good example on how to do it. This is done by creating a configuration file containing an endline separated list of `instance_name X_pos Y_pos Orientation` and pointing to it with this configuartion: `::env(MACRO_PLACEMENT_CFG)`.

 [Here][0] you can find a list of all the available OpenLane configuartions.

 Check this [section](#power-routing) for more details on power routing setup.

 ## Hardening The Full Chip


 The full chip requires an [interactive script][2] to harden. You could take this [full chip][5] as an example.

 First you need to harden the padframe as a separate macro, check [this flow][4] as an example on how to do so.

 You need to set the following environment variables in your `config.tcl` file for the chip:
 - `::env(VERILOG_FILES)` To point at the used verilog files; those that were not previously hardened. Ideally, this should be only one file.
 - `::env(VERILOG_FILES_BLACKBOX)` To point at the blackboxes (the hardened macros). Ideally, this should include all the other verilog files.
 - `::env(EXTRA_LEFS)` To point at the LEF files of the hardened core macro.
 - `::env(EXTRA_GDS_FILES)` To point at the GDS files of the hardened core macro.

 Therefore, the verilog files shouldn't have any includes in any of your verilog files. But use `::env(VERILOG_FILES)` and `::env(VERILOG_FILES_BLACKBOX)` for that purpose.

 Add `set ::env(SYNTH_READ_BLACKBOX_LIB) 1`, if you have std cells hard coded in your RTL.

 Add `set ::env(SYNTH_FLAT_TOP) 1` to your `config.tcl`. To flatten the padframe, if it's presented in a `chip_io` module, otherwise you can harden it separately as indicated in [this flow][4].

 The following inputs are provided to produce the final GDSII:

 1. Padframe cfg file (provided by the user or generated by padring). [Here][6] is an example. Or a hardened chip_io.gds and chip_io.lef following [this][4].
 2. Hardened lef & GDS-II for the core module, generated [here](#hardening-the-core)
 3. Top level netlist instantiating pads and core module (Could be provided by the user or generated by [topModuleGen][7])

 [The interactive script for the IOs][4] does the following:
 - Sources configurations.
 - Elaborates the verilog.
 - Runs floorplan.
 - Uses padringer.py to generate the padframe.
 - Adds the obstructions to the core area, and removes core nets and pins.
 - Routes.
 - Streams out the GDS-II and the LEFv view.

 Given these inputs the following [interactive script][5] script. Mainly, it does the following steps:
 -  Runs the top level netlist through yosys.
 -  Runs floorplan.
 -  Performs manual placement of the core macros, this sample has many cores, however for full automation you should have only a single core.
 -  legalize the placement.
 -  Removes Nets and Pins to a different file.
 -  This stages is skipped because the design has many cores and so fully automated power routing is not possible. However if you only have a single core, you can perform automatic power routing by adding `power_routing` at this stage in your interactive script.
 -  Route the design.
 -  Perform power routing.
 -  Generate a GDSII file of the routed design.
 -  Run DRC and LVS checks [here][11].

 ## Power_routing

 ### Macros:

 This is discussed in detail [here][8].

 ### Core:

 It should have an `stdcell` section that includes a `core_ring` on met4 and met5. It should use met5 and met4 for the straps, and met1 for the rails. Thus, make sure to add these to your config file:

 ```tcl
 set ::env(DESIGN_IS_CORE) 1
 set ::env(FP_PDN_CORE_RING) 1
 ```

 You can automate the power routing process in the core and macro level by reading [this documentation][10]. Otherwise, refer to [this][3] for more details about the syntax. In case you needed to create your own `pdn.tcl` then point to it using `PDN_CFG`.

 When you use the `power_routing` command in the chip interactive script, the power pads will be connected to the core ring, and thus the whole chip would be powered.

 ## General Notes:

 [This][2] includes more guidance on how to create an interactive script.

 [This][0] documents all OpenLane configurations.

 [This][1] has a description for all OpenLane commands.

 [0]: ./../../configuration/README.md
 [1]: ./openlane_commands.md
 [2]: ./advanced_readme.md
 [3]: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/doc/PDN.md
 [4]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/interactive.tcl
 [5]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.tcl
 [6]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/padframe.cfg
 [7]: ./../../scripts/topModuleGen/README.md
 [8]: ./hardening_macros.md
 [9]: https://github.com/efabless/openlane/tree/master/designs/manual_macro_placement_test
 [10]: ./advanced_power_grid_control.md
 [11]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.lvs.tcl
	DISCLAIMER: THIS PAGE IS STILL UNDER DEVELOPMENT.
	THE INFORMATION HERE MIGHT BE INCORRECT OR OUTDATED.

	# Chip Integration

	Using openlane, you can produce a GDSII from a chip RTL.


	## The current Methodology

	The current methodology views the chip using the following hierarchy:
	- Chip Core
	- The hard macros
	- The rest of the design
	- Chip IO
	- IO Pads
	- Power Pads
	- Corener Pads

	The current methodology goes as follows:
	1. Hardening the hard macros.
	2. Hardening the core with the hard macros inside it.
	3. Hardening the padframe
	4. Hardening the full chip with the padframe.


	## Hardening The Macros

	This is discussed in more detail [here][8].

	## Hardening The Core

	The chip core would usually have other macros inside it.

	You need to set the following environment variables in your `config.tcl` file for the chip core:
	- `::env(VERILOG_FILES)` To point at the used verilog files; those that were not previously hardened.
	- `::env(VERILOG_FILES_BLACKBOX)` To point at the blackboxes (the hardened macros).
	- `::env(EXTRA_LEFS)` To point at the LEF files of the hardened macros.
	- `::env(EXTRA_GDS_FILES)` To point at the GDS files of the hardened macros.

	Therefore, the verilog files shouldn't have any includes in any of your verilog files. But use `::env(VERILOG_FILES)` and `::env(VERILOG_FILES_BLACKBOX)` for that purpose.

	Add `set ::env(SYNTH_READ_BLACKBOX_LIB) 1`, if you have std cells hard coded in your RTL.

	You can follow the same instructions provided [here][8] for the rest of the hardenning steps.

	In case you want to manually place the macros in specific locations, [this][9] should provide a good example on how to do it. This is done by creating a configuration file containing an endline separated list of `instance_name X_pos Y_pos Orientation` and pointing to it with this configuartion: `::env(MACRO_PLACEMENT_CFG)`.

	[Here][0] you can find a list of all the available OpenLane configuartions.

	Check this [section](#power-routing) for more details on power routing setup.

	## Hardening The Full Chip


	The full chip requires an [interactive script][2] to harden. You could take this [full chip][5] as an example.

	First you need to harden the padframe as a separate macro, check [this flow][4] as an example on how to do so.

	You need to set the following environment variables in your `config.tcl` file for the chip:
	- `::env(VERILOG_FILES)` To point at the used verilog files; those that were not previously hardened. Ideally, this should be only one file.
	- `::env(VERILOG_FILES_BLACKBOX)` To point at the blackboxes (the hardened macros). Ideally, this should include all the other verilog files.
	- `::env(EXTRA_LEFS)` To point at the LEF files of the hardened core macro.
	- `::env(EXTRA_GDS_FILES)` To point at the GDS files of the hardened core macro.

	Therefore, the verilog files shouldn't have any includes in any of your verilog files. But use `::env(VERILOG_FILES)` and `::env(VERILOG_FILES_BLACKBOX)` for that purpose.

	Add `set ::env(SYNTH_READ_BLACKBOX_LIB) 1`, if you have std cells hard coded in your RTL.

	Add `set ::env(SYNTH_FLAT_TOP) 1` to your `config.tcl`. To flatten the padframe, if it's presented in a `chip_io` module, otherwise you can harden it separately as indicated in [this flow][4].

	The following inputs are provided to produce the final GDSII:

	1. Padframe cfg file (provided by the user or generated by padring). [Here][6] is an example. Or a hardened chip_io.gds and chip_io.lef following [this][4].
	2. Hardened lef & GDS-II for the core module, generated [here](#hardening-the-core)
	3. Top level netlist instantiating pads and core module (Could be provided by the user or generated by [topModuleGen][7])

	[The interactive script for the IOs][4] does the following:
	- Sources configurations.
	- Elaborates the verilog.
	- Runs floorplan.
	- Uses padringer.py to generate the padframe.
	- Adds the obstructions to the core area, and removes core nets and pins.
	- Routes.
	- Streams out the GDS-II and the LEFv view.

	Given these inputs the following [interactive script][5] script. Mainly, it does the following steps:
	- Runs the top level netlist through yosys.
	- Runs floorplan.
	- Performs manual placement of the core macros, this sample has many cores, however for full automation you should have only a single core.
	- legalize the placement.
	- Removes Nets and Pins to a different file.
	- This stages is skipped because the design has many cores and so fully automated power routing is not possible. However if you only have a single core, you can perform automatic power routing by adding `power_routing` at this stage in your interactive script.
	- Route the design.
	- Perform power routing.
	- Generate a GDSII file of the routed design.
	- Run DRC and LVS checks [here][11].

	## Power_routing

	### Macros:

	This is discussed in detail [here][8].

	### Core:

	It should have an `stdcell` section that includes a `core_ring` on met4 and met5. It should use met5 and met4 for the straps, and met1 for the rails. Thus, make sure to add these to your config file:

	```tcl
	set ::env(DESIGN_IS_CORE) 1
	set ::env(FP_PDN_CORE_RING) 1
	```

	You can automate the power routing process in the core and macro level by reading [this documentation][10]. Otherwise, refer to [this][3] for more details about the syntax. In case you needed to create your own `pdn.tcl` then point to it using `PDN_CFG`.

	When you use the `power_routing` command in the chip interactive script, the power pads will be connected to the core ring, and thus the whole chip would be powered.

	## General Notes:

	[This][2] includes more guidance on how to create an interactive script.

	[This][0] documents all OpenLane configurations.

	[This][1] has a description for all OpenLane commands.

	[0]: ./../../configuration/README.md
	[1]: ./openlane_commands.md
	[2]: ./advanced_readme.md
	[3]: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/doc/PDN.md
	[4]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/interactive.tcl
	[5]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.tcl
	[6]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/padframe.cfg
	[7]: ./../../scripts/topModuleGen/README.md
	[8]: ./hardening_macros.md
	[9]: https://github.com/efabless/openlane/tree/master/designs/manual_macro_placement_test
	[10]: ./advanced_power_grid_control.md
	[11]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.lvs.tcl