[AP] Added Documentation for AP Flow

Author: AlexandreSinger

doc/src/arch/reference.rst

@@ -158,6 +158,8 @@ The valid tags within the ``<layout>`` tag are:
 
     .. note:: At most one ``<auto_layout>`` can be specified.
 
+.. _fixed_arch_grid_layout:
+
 .. arch:tag:: <fixed_layout name="string" width="int" height="int">
 
     :req_param name:

doc/src/vpr/command_line_usage.rst

@@ -82,6 +82,23 @@ VPR runs all stages of (pack, place, route, and analysis) if none of :option:`--
 
     **Default:** ``off``
 
+.. option:: --analytical_place
+
+    Run the analytical placement flow.
+    This flows uses an integrated packing and placement algorithm which uses information from the primitive level to improve clustering and placement;
+    as such, the :option:`--pack` and :option:`--place` options should not be set when this option is set.
+    This flow requires that the device has a fixed size and some of the primitive blocks are fixed somewhere on the device grid.
+
+    .. seealso:: See :ref:`Fixed FPGA Grid Layout <fixed_arch_grid_layout>` and :option:`--device` for how to fix the device size.
+
+    .. seealso:: See :ref:`VPR Placement Constraints <placement_constraints>` for how to fix primitive blocks in a design to the device grid.
+
+    .. warning::
+
+        This analytical placement flow is experimental and under active development.
+
+    **Default:** ``off``
+
 .. option:: --route
 
     Run routing stage

vpr/src/base/CheckSetup.cpp

@@ -91,8 +91,8 @@ void CheckSetup(const t_packer_opts& PackerOpts,
         //       some fixed blocks somewhere. Maybe we can live without fixed
         //       blocks.
 
-        // FIXME: Should we enforce that the size of the device is fixed? Or is
-        //        that defined in the constraints file?
+        // TODO: Should we enforce that the size of the device is fixed. This
+        //       goes with ensuring that some blocks are fixed.
     }
 
     if (RouterOpts.doRouting) {

vpr/src/base/SetupVPR.cpp

@@ -280,6 +280,8 @@ void SetupVPR(const t_options* Options,
         }
 
         if (Options->do_analytical_placement) {
+            // In the Analytical Placement flow, packing and placement are
+            // integrated. Thus, these stages are skipped.
             PackerOpts->doPacking = STAGE_SKIP;
             PlacerOpts->doPlacement = STAGE_SKIP;
             APOpts->doAP = STAGE_DO;

vpr/src/base/read_options.cpp

@@ -1325,7 +1325,7 @@ argparse::ArgumentParser create_arg_parser(const std::string& prog_name, t_optio
         .default_value("off");
 
     stage_grp.add_argument<bool, ParseOnOff>(args.do_analytical_placement, "--analytical_place")
-        .help("Run analytical placement")
+        .help("Run analytical placement. Analytical Placement uses an integrated packing and placement algorithm, using information from the primitive level to improve clustering and placement.")
         .action(argparse::Action::STORE_TRUE)
         .default_value("off");