# Initialize Floorplan

This tool initializes floorplan constraints, die/core area, and makes tracks. 

## Commands

```{note}
- Parameters in square brackets `[-param param]` are optional.
- Parameters without square brackets `-param2 param2` are required.
```

### Initialize Floorplan

Do note that there are two ways of setting the floorplan dimensions.
The user can either specify manually die/core area, or
specify the utilization/aspect ratio. If you set both, 
unexpected behaviour might occur.

- Method 1: Automatic die size calculation
Example: `initialize_floorplan -utilization 70 -aspect_ratio 1.0 -core_space 0.0 -sites FreePDK45_38x28_10R_NP_162NW_34O`

- Method 2: Set die/core area
Example: `initialize_floorplan -die_area 0 0 2000 2000 -core_area 100 100 1900 1900` -sites FreePDK45_38x28_10R_NP_162NW_34O`

The die area and core area used to write ROWs can be specified explicitly
with the `-die_area` and `-core_area` arguments. Alternatively, the die and
core areas can be computed from the design size and utilization as shown below:

The -site argument determines the basic single-height rows to make.
For a hybrid row design the site should have a row pattern.  Any sites
referenced by an instance in the netlist will also have rows
constructed for them.

Additional sites are specified if you wish to have rows for a site
that is not used in the nelist but may be needed later.  For example,
you might not have any double height cells in the incoming netlist but
you expect some to be generated by flop clustering later in the flow.

Example computation:

```
core_area = design_area / (utilization / 100)
core_width = sqrt(core_area / aspect_ratio)
core_height = core_width * aspect_ratio
core = ( core_space_left, core_space_bottom )
      ( core_space_left + core_width, core_space_bottom + core_height )
die =  ( 0, 0 )
      ( core_width + core_space_left + core_space_right,
        core_height + core_space_bottom + core_space_top )
```


```tcl
initialize_floorplan
  (-die_area {llx lly urx ury | x1 y1 x2 y2 ...} -core_area {llx lly urx ury | x1 y1 x2 y2 ...}) | (-utilization util -core_space (space | {bottom top left right}) [-aspect_ratio ratio])
  -site site_name
  [-additional_sites site_names]
  [-flip_sites site_names]
  [-gap space]
  [-row_parity NONE|EVEN|ODD]
```

#### Options

| Switch Name | Description |
| ----- | ----- |
| `-core_area` | Core area coordinates in microns. Either a rectangle as `{llx lly urx ury}`, or a rectilinear polygon as a list of vertex coordinates `{x1 y1 x2 y2 ...}`. See [Rectilinear Floorplans](#rectilinear-floorplans). |
| `-core_space` | Space around the core in microns. Allowed values are either one value for all margins or a set of four values, one for each margin. The order of the four values are: `{bottom top left right}`. |
| `-die_area` | Die area coordinates in microns. Either a rectangle as `{llx lly urx ury}`, or a rectilinear polygon as a list of vertex coordinates `{x1 y1 x2 y2 ...}`. See [Rectilinear Floorplans](#rectilinear-floorplans). |
| `-site` | Site name. |
| `-utilization` | Percentage utilization. Allowed values are `double` in the range `(0-100]`. |
| `[-additional_sites]` | Tcl list of sites to make rows for (e.g. `{SITEXX, SITEYY}`) |
| `[-aspect_ratio]` | Ratio $\frac{height}{width}$. The default value is `1.0` and the allowed values are floats `[0, 1.0]`. |
| `[-flip_sites]` | Flip the orientations of rows matching these sites. Sites listed under this option will create `FS`-oriented rows at even indices and `N`-oriented rows at odd ones, and vice versa for sites not listed under this option. (e.g. `{SITEXX, SITEYY}`) |
| `[-gap]` | Space between power domains in microns. The default value is 6 times the minimum site height. |
| `[-row_parity]` | Snap to either an odd (`ODD`) or even (`EVEN`) number of rows. Defaults to `NONE` (no constraint on parity). |

### Rectilinear Floorplans

The `initialize_floorplan` command supports non-rectangular die and core
outlines (e.g. L-shapes, T-shapes, or arbitrary rectilinear polygons).
Rectilinear mode is selected automatically when `-die_area` is given more than
four coordinates. When rectilinear mode is used, `-core_area` must also be
specified as a polygon (it is not derived from `-utilization`,
`-aspect_ratio`, or `-core_space`).

Example: an L-shaped die with a matching L-shaped core, with a 20 micron
margin between them.

<!-- checker: skip -->
```tcl
initialize_floorplan \
  -die_area  {0 0   200 0   200 100   100 100   100 200   0 200} \
  -core_area {20 20  180 20  180 80   80 80     80 180    20 180} \
  -site FreePDK45_38x28_10R_NP_162NW_34O
```

Rows are generated only inside the polygonal core, respecting its rectilinear edges.

#### Polygon Vertex Rules

- Coordinates are in microns, listed as `{x1 y1 x2 y2 ... xN yN}`.
- The vertex count must be even (each `x` paired with a `y`).
- Exactly 4 coordinates are interpreted as a rectangle. A polygon must
  have more than 4 coordinates and at least 4 vertices (8 coordinates).
- Edges must be axis-aligned (rectilinear): consecutive vertices must
  share either an `x` or a `y` coordinate.
- The die polygon must fully contain the core polygon.

### Make Tracks

The `initialize_floorplan` command removes existing tracks. 
Use the `make_tracks` command to add routing tracks to a floorplan.

```tcl
make_tracks 
    [layer]
    [-x_offset x_offset]
    [-y_offset y_offset]
    [-x_pitch x_pitch]
    [-y_pitch y_pitch]
```

#### Options

| Switch Name | Description |
| ----- | ----- |
| `[layer]` | Select layer name to make tracks for. Defaults to all layers. |
| `[-x_offset]`, `[-y_offset]` | If set, overrides the LEF technology x-/y- offset. Use the same unit as in the LEFT file. |
| `[-x_pitch]`, `[-y_pitch]` | If set, overrides the LEF technology x-/y- pitch. Use the same unit as in the LEF file. |

### Make Rows

The `make_rows` command removes existing rows. 
Use the `make_rows` command to add rows to an existing floorplan. Useful,
if your floorplan is stored as a floorplan def without rows.

```tcl
make_rows
  (-core_area {llx lly urx ury}) | (-core_space (space | {bottom top left right}))
  -site site_name
  [-additional_sites site_names]
  [-flip_sites site_names]
  [-gap space]
  [-row_parity NONE|EVEN|ODD]
```

#### Options


| Switch Name | Description |
| ----- | ----- |
| `-core_area` | Core area coordinates in microns (lower left x/y and upper right x/y coordinates). |
| `-core_space` | Space around the core in microns. Allowed values are either one value for all margins or a set of four values, one for each margin. The order of the four values are: `{bottom top left right}`. |
| `-site` | Site name. |
| `[-additional_sites]` | Tcl list of sites to make rows for (e.g. `{SITEXX, SITEYY}`) |
| `[-flip_sites]` | Flip the orientations of rows matching these sites. Sites listed under this option will create `FS`-oriented rows at even indices and `N`-oriented rows at odd ones, and vice versa for sites not listed under this option. (e.g. `{SITEXX, SITEYY}`) |
| `[-gap]` | Space between power domains in microns. The default value is 6 times the minimum site height. |
| `[-row_parity]` | Snap to either an odd (`ODD`) or even (`EVEN`) number of rows. Defaults to `NONE` (no constraint on parity). |

### Insert tieoff cells

This comamnd inserts tiecells.

```tcl
insert_tiecells 
    [-prefix inst_prefix]
    tie_pin
```

#### Options

| Switch Name | Description |
| ----- | ----- |
| `[-prefix]` | Used to control the prefix of the new tiecell names. This will default to `TIEOFF_`. |
| `tie_pin` | Indicates the master and port to use to tie off nets. For example, `LOGIC0_X1/Z` for the Nangate45 library, where `LOGIC0_X1` is the master and `Z` is the output port on the master. |

## Useful Developer Commands

If you are a developer, you might find these useful. More details can be found in the [source file](./src/InitFloorplan.cc) or the [swig file](./src/InitFloorplan.i).

| Command Name | Description |
| ----- | ----- |
| `microns_to_mfg_grid` | Convert microns to manufacturing grid DBU. |

## Example scripts

Example scripts on running `ifp` for a sample design of `mpd_top` are as follows:

```
./test/upf_test.tcl
```

## Regression tests

There are a set of regression tests in `./test`. For more information, refer to this [section](../../README.md#regression-tests).

Simply run the following script:

```shell
./test/regression
```

## Limitations

## License

BSD 3-Clause License. See [LICENSE](../../LICENSE) file.