Added a new file for documenting VPR placement constraints

Author: sfkhalid

doc/src/vpr/placement_constraints.rst

@@ -0,0 +1,103 @@
+VPR Placement Constraints
+=========================
+
+VPR supports running flows with placement constraints. Placement constraints are set on primitives to lock them down to specified regions on the FPGA chip. The placement constraints should be specified by the user using an XML constraints file format, as described in the section below. When VPR is run with placement constraints, both the packing and placement flows are performed in such a way that the constraints are respected. The packing stage does not pack any primitives together that have conflicting floorplan constraints. The placement stage considers the floorplan constraints when choosing a location for each clustered block during initial placement, and does not move any block outside of its constraint boundaries during place moves.
+
+Constraints File Format
+-----------------------
+
+VPR has a specific XML format which must be used when creating a placement constraints file. The purpose of this constraints file is to specify 
+
+#. Which primitives are to have placement constraints
+#. The regions on the FPGA chip to which those primitives must be constrained
+
+The file is passed as an input to VPR when running with placement constraints. When the file is read in, its information is used during the packing and placement stages of VPR. The hierarchy of the file is set up as follows.
+
+.. note:: Use the VPR :option: `--read_vpr_constraints` to specify the VPR placement constraints file that is to be loaded. 
+
+The top level tag is the ``<vpr_constraints>`` tag. This tag contains one ``<partition_list>`` tag. The ``<partition_list>`` tag can be made up of an unbounded number of ``<partition>`` tags. The ``<partition>`` tags contains all of the detailed information of the placement constraints, and is described in detail below.
+
+Partitions, Atoms, and Regions
+------------------------------
+
+Partition
+^^^^^^^^^
+
+A partition is made up of two components - a group of primitives (a.k.a. atoms) that must be constrained to the same area on the chip, and a set of one or more regions specifying where those primitives must be constrained. The information for each partition is contained within a ``<partition>`` tag, and the number of ``partition`` tags that the partition_list tag can contain is unbounded. 
+
+:req_param name:
+   A name for the partition.
+
+:req_param add_atom:
+   A tag used for adding an atom primitive to the partition.
+
+:req_param add_region:
+   A tag used for specifying a region for the partition.
+
+Atom 
+^^^^
+
+An ``<add_atom>`` tag is used to add an atom that must be constrained to the partition. Each partition can contain any number of atoms from the circuit. The ``<add_atom>`` tag has the following attribute:
+
+:req_param name_pattern:
+   The name of the atom.
+
+The ``name_pattern`` can either be the exact name of the atom from the atom netlist produced by VPR. It can also be a regular expression, in which case VPR will add all atoms from the netlist which have a portion of their name matching the regular expression to the partition.
+
+Region
+^^^^^^
+
+An ``<add_region>`` tag is used to add a region to the partition. A ``region`` is a rectangular area on the chip. A partition can contain any number of independent regions - the regions within one partition must not overlap with each other (in order to ease processing when loading in the file). An ``<add_region>`` tag has the following attributes.
+
+:req_param x_low:
+   The x value of the lower left point of the rectangle.
+
+:req_param y_low:
+   The y value of the lower left point of the rectangle.
+
+:req_param x_high:
+   The x value of the upper right point of the rectangle.
+
+:req_param y_high:
+   The y value of the upper right point of the rectangle.
+
+:opt_param subtile:
+   Each x, y location on the grid may contain multiple locations known as subtiles. This paramter is an optional value specifying the subtile location that the atom(s) of the partition shall be constrained to.
+
+The optional ``subtile`` attribute is useful when the user would like to constrain a primitive to one specific x, y, subtile location on the chip. In this case, ``x_low`` can be set to equal ``x_high``, ``y_low`` can equal ``y_high``, and the subtile attribute can be specified.
+
+If a user would like to specify an area on the chip with an unusual shape (e.g. L-shaped or T-shaped), they can simply add multiple ``<add_region>`` tags to cover the area specified.
+
+
+A Constraints File Example
+--------------------------
+
+.. code-block:: xml
+:caption: An example of a placement constraints file in XML format.
+:linenos:
+
+<vpr_constraints tool_name="vpr">
+     <partition_list>
+	  <partition name="Part0">
+	       <add_atom name_pattern="li354">
+	       <add_atom name_pattern="lo326">
+	       <add_atom name_pattern="n877">
+	       <add_region x_low="2" y_low="3" x_high="10" y_high="12">
+	       <add_region x_low="14" y_low="16" x_high="25" y_high="25">
+	  </partition>
+	  <partition name="Part1">
+	       <add_region x_low="3" y_low="3" x_high="7" y_high="7" subtile="0">
+	       <add_atom name_pattern="n4917">
+	       <add_atom name_pattern="n6010">
+	  </partition>
+     </partition_list>
+</vpr_constraints>
+
+.. _end:
+
+
+
+
+
+
+