Noc documentation

doc/src/api/vprinternals/index.rst

@@ -9,3 +9,4 @@ VPR INTERNALS
    draw_structs
    vpr_ui
    draw_files
+   vpr_noc

doc/src/api/vprinternals/noc_data_types.rst

@@ -0,0 +1,8 @@
+==============
+NoC Data Types
+==============
+
+Data Types
+----------
+.. doxygenfile:: noc_data_types.h
+   :project: vpr

doc/src/api/vprinternals/noc_link.rst

@@ -0,0 +1,8 @@
+========
+NoC Link
+========
+
+NocLink
+-------
+.. doxygenfile:: noc_link.h
+   :project: vpr

doc/src/api/vprinternals/noc_router.rst

@@ -0,0 +1,8 @@
+==========
+NoC Router
+==========
+
+NocRouter
+---------
+.. doxygenfile:: noc_router.h
+   :project: vpr

doc/src/api/vprinternals/noc_routing.rst

@@ -0,0 +1,23 @@
+===========
+NoC Routing
+===========
+
+NocRouting
+---------------
+.. doxygenfile:: noc_routing.h
+   :project: vpr
+
+NocRoutingAlgorithmCreator
+--------------------------
+.. doxygenfile:: noc_routing_algorithm_creator.h
+   :project: vpr
+
+XYRouting
+---------
+.. doxygenfile:: xy_routing.h
+   :project: vpr
+
+BFSRouting
+----------
+.. doxygenfile:: bfs_routing.h
+   :project: vpr

doc/src/api/vprinternals/noc_storage.rst

@@ -0,0 +1,8 @@
+===========
+NoC Storage
+===========
+
+NocStorage
+----------
+.. doxygenfile:: noc_storage.h
+   :project: vpr

doc/src/api/vprinternals/noc_traffic_flows.rst

@@ -0,0 +1,8 @@
+=================
+NoC Traffic Flows
+=================
+
+NocTrafficFlows
+---------------
+.. doxygenfile:: noc_traffic_flows.h
+   :project: vpr

doc/src/api/vprinternals/vpr_noc.rst

@@ -0,0 +1,15 @@
+.. _noc:
+
+=======
+VPR NoC
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   noc_router
+   noc_link
+   noc_storage
+   noc_traffic_flows
+   noc_routing 
+   noc_data_types  

doc/src/arch/reference.rst

@@ -23,6 +23,7 @@ The architecture tag contains the following tags:
 * ``<segmentlist>``
 * ``<directlist>``
 * ``<complexblocklist>``
+* ``<noc>``
 
 .. _arch_models:
 
@@ -136,6 +137,10 @@ Global FPGA Information
 
     Content inside this tag contains a group of ``<pb_type>`` tags that specify the types of functional blocks and their properties.
 
+.. arch:tag:: <noc link_bandwidth="float" link_latency="float" router_latency="float" noc_router_tile_name="string">content</noc>
+
+    Content inside this tag specifies the Network-on-Chip (NoC) architecture on the FPGA device and its properties.
+
 .. _arch_grid_layout:
 
 FPGA Grid Layout
@@ -1855,6 +1860,95 @@ Power
     :opt_param scaled_by_static_prob: Port name by which to scale ``energy_per_toggle`` based on its logic high probability.
     :opt_param scaled_by_static_prob_n: Port name by which to scale ``energy_per_toggle`` based on its logic low probability.
 
+NoC Description
+---------------
+
+The ``<noc>`` tag is an optional tag and its contents allows designers to describe a NoC on an FPGA device.
+The ``<noc>`` tag is the top level tag for the NoC description and its attributes define the overall properties
+of the NoC; refer below for its contents.
+
+.. arch:tag:: <noc link_bandwidth="float" link_latency="float" router_latency="float" noc_router_tile_name="string">
+
+    :req_param link_bandwidth:
+        Specifies the maximum bandwidth in bits-per-second (bps) that a link in the NoC can support
+
+    :req_param link_latency:
+        Specifies the delay in seconds seen by a flit as it travels from one physical NoC router to another using a NoC link.
+
+    :req_param router_latency:
+        Specifies the un-loaded delays in seconds as it travels through a physical router.
+
+    :req_param noc_router_tile_name:
+        Specifies a string which represents the name used to identify a NoC router tile (physical hard block) in the 
+        corresponding FPGA architecture. This information is needed to create a model of the NoC.
+
+The ``<noc>`` tag contains a single ``<topology>`` tag which describes the topology of the NoC.
+
+NoC topology
+~~~~~~~~~~~~
+
+As mentioned above the ``<topology>`` tag can be used to specify the topology or how the routers in the NoC
+are connected to each other. The ``<topology>`` tag consists of a group ``<router>``tags.
+
+Below is an example of how the ``<topology>`` tag is used.
+
+.. code-block:: xml
+
+    <topology>
+        <!--A number of <router> tags go here-->
+    </topology>
+
+The ``<router>`` tag and its contents are described below.
+
+.. arch:tag:: <router id="int" positionx="float" positiony="float" connections="int int int int ...">
+
+    This tag represents a single physical NoC router on the FPGA device and specifies how it is connected within the NoC.
+
+    :req_param  id:
+        Specifies a user identification (ID) number which is associate to the physical
+        router that this tag is identifying. This ID is used to report errors and
+        warnings to the user.
+
+    :req_param positionx:
+        Specifies the horizontal position of the physical router block that this
+        tag is identifying. This position does not have to be exact, it can
+        be an approximate value.
+
+    :req_param positiony:
+        Specifies the vertical position of the physical router block that this
+        tag is identifying. This position does not have to be exact, it can
+        be an approximate value.
+
+    :req_param connections:
+        Specifies a list of numbers seperated by spaces which are the user IDs supplied to other
+        ``<router>`` tags. This describes how the current physical Noc router
+        that this tag is identifying is connected to the other physical NoC routers on the device.
+
+    Below is an example of the ``<router>`` tag which identifies a physical router located near (0,0) with ID 0. This router
+    is also connected to two other routers identified by IDs 1 and 2.
+
+    .. code-block:: xml
+
+        <router id="0" positionx="0" positiony="0" connections="1 2"/>
+
+NoC Description Example
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Below is an example which describes a NoC architecture which has 4 physical routers that are connected to each other to form a 
+2x2 mesh topology.
+
+.. code-block:: xml
+
+    <!-- Description of a 2x2 mesh NoC-->
+    <noc link_bandwidth="1.2e9" router_latency="1e-9" link_latency="1e-9" noc_router_tile_name="noc_router_adapter">
+        <topology>
+                <router id="0" positionx="0" positiony="0" connections="1 2"/>
+                <router id="1" positionx="5" positiony="0" connections="0 3"/>
+                <router id="2" positionx="0" positiony="5" connections="0 3"/>
+                <router id="3" positionx="5" positiony="5" connections="1 2"/>
+        </topology>
+    </noc>
+
 Wire Segments
 -------------
 

doc/src/vpr/command_line_usage.rst

@@ -1681,7 +1681,7 @@ Analysis Options
 
             It is possible that by opening a switch between (1,2) to (1,1), CHANY:2113 actually only extends from (1,3) to (1,2).
 
-            2. The preceding channel's ending coordinates have no relation to the following channel's starting coordinates.
+            1. The preceding channel's ending coordinates have no relation to the following channel's starting coordinates.
                There is no logical contradiction, but for clarification, it is best to see an explanation of the VPR coordinate system.
                The path can also be visualized by VPR graphics, as an illustration of this point:
 

doc/src/vpr/file_formats.rst

@@ -1074,6 +1074,95 @@ To aid in handling large graphs, rr_graph files can also be :ref:`saved in <file
 
 .. _end:
 
+
+Network-on-Chip (NoC) Traffic Flows Format (.flows)
+---------------------------------------------------
+
+In order to co-optimize for the NoC placement VPR needs expected performance metrics of the NoC.
+VPR defines the performance requirements of the NoC as traffic flows. A traffic flow is a one-way communication between two
+logical routers in a design. The traffic flows provide the communications bandwidth and Quality of
+Service (QoS) requirements. The traffic flows are application dependant and need to be supplied
+externally by a user. The traffic flows file is an XML based file format which designers
+can use to describe the traffic flows in a given application.
+
+.. note:: Use :option:`vpr --noc_traffic_flows` to specify an NoC traffic flows file to be loaded.
+
+Top Level Tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first tag in all NoC traffic flow files is the ``<traffic_flows>`` tag that contains detailed subtags for each catagory in the NoC traffic flows.
+
+The ``traffic_flows`` tag contains the following tags:
+
+* ``<single_flow>``
+        * ``<single_flow>``content``</single_flow>`` 
+
+Detailed Tag Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Single Flow
+^^^^^^^^^^^
+
+A given traffic flow information is contained within the ``single_flow`` tag. There can be 0 or more single flow tags.
+0 would indicate that an application does not have any traffic flows.
+
+.. rrgraph:tag:: <channel src="logical_router_name" dst="logical_router_name" bandwidth="float" latency_cons="float" priority="int"/>
+
+    :opt_param latency_cons:
+        A floating point number which indicates the upper bound
+        on the latency for a traffic flow. This is in units of seconds and is an optional attribute.
+        If this attribute is not provided then the CAD tool will try to reduce the latency as much
+        as possible.
+
+    :opt_param priority:
+        An integer which represents the relative importance of the traffic flow
+        against all other traffic flows in an application. For example, a traffic flow with priority
+        10 would be weighted ten times more than a traffic flow with priority 1. This is an
+        optional attribute and by default all traffic flows have a priority of 1
+
+    :req_param src:
+        A string which represents a logical router name in an application.
+        This logical router is the source endpoint for the traffic flow being described by the cor-
+        responding single flow tag. The logical router name must match the name of the router
+        as found in the clustered netlist; since this name assigned by the CAD tool, instead of
+        having the designer go through the clustered netlist to retrieve the exact name we instead
+        allow designers to use regex patters in the logical router name. For example, instead of
+        ”noc_router_adapter_block:noc_router_layer1_mvm2:slave_tready_reg0” user could pro-
+        vide ”.*noc_router_layer1_mvm2.*”. This allows users to provide the instance name for a given logical router
+        module in the design. This is a required attribute.
+
+    :req_param dst:
+        A string which represents a logical router name in an application.
+        This logical router is the deastination endpoint for the traffic flow being described by the cor-
+        responding single flow tag. The logical router name must match the name of the router
+        as found in the clustered netlist; since this name assigned by the CAD tool, instead of
+        having the designer go through the clustered netlist to retrieve the exact name we instead
+        allow designers to use regex patters in the logical router name. For example, instead of
+        ”noc_router_adapter_block:noc_router_layer1_mvm3:slave_tready_reg0” user could pro-
+        vide ”.*noc_router_layer1_mvm3.*”. This allows users to provide the instance name for a given logical router
+        module in the design. This is a required attribute.
+
+    :req_param bandwidth:
+        A floating point number which indicates the data size in the
+        traffic flow communication. This is in units of bits-per-second (bps) and is a required
+        attribute.
+
+NoC Traffic Flows File Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An example of what a NoC traffic flows file looks like is shown below:
+
+.. code-block:: xml
+    :caption: Example of a NoC traffic flows file in XML format
+    :linenos:
+
+    <traffic_flows>
+        <single_flow src="m0" dst="m1" bandwidth="2.3e9" latency_cons="3e-9"/>
+        <single_flow src="m0" dst="m2" bandwidth="5e8"/>
+        <single_flow src="ddr" dst="m0" bandwidth="1.3e8" priority=3/>
+        <single_flow src="m3" dst="m2" bandwidth="4.8e9" latency_cons="5e-9" priority=2/>
+    </traffic_flows>
+
 Block types usage summary (.txt .xml or .json)
 -----------------------------------------
 

vpr/src/noc/noc_data_types.h

@@ -1,18 +1,27 @@
 #ifndef NOC_DATA_TYPES_H
 #define NOC_DATA_TYPES_H
 
+/** 
+ * @file 
+ * @brief This file contains datatype definitions which are used by the NoC datastructures.
+ *  
+ */
+
 #include "vtr_strong_id.h"
 
 // data types used to index the routers and links within the noc
 struct noc_router_id_tag;
 struct noc_link_id_tag;
 
+/** Datatype to index routers within the NoC */
 typedef vtr::StrongId<noc_router_id_tag, int> NocRouterId;
+/** Datatype to index links within the NoC */
 typedef vtr::StrongId<noc_link_id_tag, int> NocLinkId;
 
 // data type to index traffic flows within the noc
 struct noc_traffic_flow_id_tag;
 
+/** Datatype to index traffic flows within the application */
 typedef vtr::StrongId<noc_traffic_flow_id_tag, int> NocTrafficFlowId;
 
 #endif