diff --git a/doc/src/api/vprinternals/index.rst b/doc/src/api/vprinternals/index.rst index 792069325ed..b22aaa85ebc 100644 --- a/doc/src/api/vprinternals/index.rst +++ b/doc/src/api/vprinternals/index.rst @@ -9,3 +9,4 @@ VPR INTERNALS draw_structs vpr_ui draw_files + vpr_noc diff --git a/doc/src/api/vprinternals/noc_data_types.rst b/doc/src/api/vprinternals/noc_data_types.rst new file mode 100644 index 00000000000..cba74bfa576 --- /dev/null +++ b/doc/src/api/vprinternals/noc_data_types.rst @@ -0,0 +1,8 @@ +============== +NoC Data Types +============== + +Data Types +---------- +.. doxygenfile:: noc_data_types.h + :project: vpr \ No newline at end of file diff --git a/doc/src/api/vprinternals/noc_link.rst b/doc/src/api/vprinternals/noc_link.rst new file mode 100644 index 00000000000..6a7dfb121eb --- /dev/null +++ b/doc/src/api/vprinternals/noc_link.rst @@ -0,0 +1,8 @@ +======== +NoC Link +======== + +NocLink +------- +.. doxygenfile:: noc_link.h + :project: vpr \ No newline at end of file diff --git a/doc/src/api/vprinternals/noc_router.rst b/doc/src/api/vprinternals/noc_router.rst new file mode 100644 index 00000000000..02e6148c8a2 --- /dev/null +++ b/doc/src/api/vprinternals/noc_router.rst @@ -0,0 +1,8 @@ +========== +NoC Router +========== + +NocRouter +--------- +.. doxygenfile:: noc_router.h + :project: vpr \ No newline at end of file diff --git a/doc/src/api/vprinternals/noc_routing.rst b/doc/src/api/vprinternals/noc_routing.rst new file mode 100644 index 00000000000..584bb6681bc --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/src/api/vprinternals/noc_storage.rst b/doc/src/api/vprinternals/noc_storage.rst new file mode 100644 index 00000000000..1670d93a5ec --- /dev/null +++ b/doc/src/api/vprinternals/noc_storage.rst @@ -0,0 +1,8 @@ +=========== +NoC Storage +=========== + +NocStorage +---------- +.. doxygenfile:: noc_storage.h + :project: vpr \ No newline at end of file diff --git a/doc/src/api/vprinternals/noc_traffic_flows.rst b/doc/src/api/vprinternals/noc_traffic_flows.rst new file mode 100644 index 00000000000..ab9d5b68b66 --- /dev/null +++ b/doc/src/api/vprinternals/noc_traffic_flows.rst @@ -0,0 +1,8 @@ +================= +NoC Traffic Flows +================= + +NocTrafficFlows +--------------- +.. doxygenfile:: noc_traffic_flows.h + :project: vpr diff --git a/doc/src/api/vprinternals/vpr_noc.rst b/doc/src/api/vprinternals/vpr_noc.rst new file mode 100644 index 00000000000..190f7cc5f66 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/src/arch/reference.rst b/doc/src/arch/reference.rst index 0ed04d87694..8b52726a7cb 100644 --- a/doc/src/arch/reference.rst +++ b/doc/src/arch/reference.rst @@ -23,6 +23,7 @@ The architecture tag contains the following tags: * ```` * ```` * ```` +* ```` .. _arch_models: @@ -136,6 +137,10 @@ Global FPGA Information Content inside this tag contains a group of ```` tags that specify the types of functional blocks and their properties. +.. arch:tag:: content + + 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 ```` tag is an optional tag and its contents allows designers to describe a NoC on an FPGA device. +The ```` 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:: + + :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 ```` tag contains a single ```` tag which describes the topology of the NoC. + +NoC topology +~~~~~~~~~~~~ + +As mentioned above the ```` tag can be used to specify the topology or how the routers in the NoC +are connected to each other. The ```` tag consists of a group ````tags. + +Below is an example of how the ```` tag is used. + +.. code-block:: xml + + + + + +The ```` tag and its contents are described below. + +.. arch:tag:: + + 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 + ```` 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 ```` 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 + + + +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 + + + + + + + + + + + Wire Segments ------------- diff --git a/doc/src/vpr/command_line_usage.rst b/doc/src/vpr/command_line_usage.rst index 10b60715f5d..933d4748eff 100644 --- a/doc/src/vpr/command_line_usage.rst +++ b/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: diff --git a/doc/src/vpr/file_formats.rst b/doc/src/vpr/file_formats.rst index a35924a2b85..cc114105810 100644 --- a/doc/src/vpr/file_formats.rst +++ b/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 `` tag that contains detailed subtags for each catagory in the NoC traffic flows. + +The ``traffic_flows`` tag contains the following tags: + +* ```` + * ````content```` + +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:: + + :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: + + + + + + + + Block types usage summary (.txt .xml or .json) ----------------------------------------- diff --git a/vpr/src/noc/noc_data_types.h b/vpr/src/noc/noc_data_types.h index c6c9c483da6..86135ca77cb 100644 --- a/vpr/src/noc/noc_data_types.h +++ b/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 NocRouterId; +/** Datatype to index links within the NoC */ typedef vtr::StrongId 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 NocTrafficFlowId; #endif \ No newline at end of file diff --git a/vpr/src/noc/noc_link.h b/vpr/src/noc/noc_link.h index e35802a2f2a..dee19cc676b 100644 --- a/vpr/src/noc/noc_link.h +++ b/vpr/src/noc/noc_link.h @@ -1,7 +1,7 @@ #ifndef NOC_LINK_H #define NOC_LINK_H -/* +/** * @file * @brief This file defines the NocLink class. * @@ -23,14 +23,14 @@ * exceeds the links supported capability). * * Example: - * + * ``` * ---------- ---------- * / / link / / * / router / --------------------->/ router / * / a / / b / * / / / / * /--------/ /--------/ - * + * ``` * In the example above the links source router would be router a and * the sink router would be router b. * @@ -44,10 +44,10 @@ class NocLink { private: // the two routers that are connected by this link - NocRouterId source_router; /*!< The router which has this link as an outgoing edge*/ + NocRouterId source_router; /*!< The router which uses this link as an outgoing edge*/ NocRouterId sink_router; /*!< The router which uses this link as an incoming edge*/ - double bandwidth_usage; /*!< Represents the bandwidth of the data being transmitted on the link. Units in bps*/ + double bandwidth_usage; /*!< Represents the bandwidth of the data being transmitted on the link. Units in bits-per-second(bps)*/ public: NocLink(NocRouterId source_router, NocRouterId sink_router); @@ -77,14 +77,14 @@ class NocLink { // setters /** * @brief Can be used to set the source router of the link to a different router. - * @param source_router The identifier representing the router that should be the source of + * @param source An identifier representing the router that should be the source of * this link */ void set_source_router(NocRouterId source); /** * @brief Can be used to set the sink router of the link to a different router. - * @param sink_router The identifier representing the router that should be the sink of + * @param sink An identifier representing the router that should be the sink of * this link */ void set_sink_router(NocRouterId sink); diff --git a/vpr/src/noc/noc_router.h b/vpr/src/noc/noc_router.h index a48c64cb971..8cbda26e0bc 100644 --- a/vpr/src/noc/noc_router.h +++ b/vpr/src/noc/noc_router.h @@ -1,7 +1,7 @@ #ifndef NOC_ROUTER_H #define NOC_ROUTER_H -/* +/** * @file * @brief This file defines the NocRouter class. * @@ -38,16 +38,24 @@ class NocRouter { private: - /** this represents a unique id provided by the user when describing the NoC topology in the arch file. The intended + /** This represents a unique id provided by the user when describing the NoC topology in the arch file. The intended * use is to report errors with router ids the user understands*/ int router_user_id; // device position of the physical router tile - int router_grid_position_x; /* router_storage; /* router_storage; // list of outgoing links for each router /** @@ -63,7 +65,8 @@ class NocStorage { */ vtr::vector> router_link_list; - vtr::vector link_storage; /* link_storage; /** * @brief The user provides an ID for the router when describing the NoC @@ -409,14 +412,14 @@ class NocStorage { * link is returned. * * Example: - * + * ``` * ---------- ---------- * / / link 1 / / * / router / --------------------->/ router / * / a / <---------------------/ b / * / / link 2 / / * /--------/ /--------/ - * + * ``` * In the example above, link 1 and link 2 are parallel. * * @param current_link A unique identifier that represents a link diff --git a/vpr/src/noc/noc_traffic_flows.h b/vpr/src/noc/noc_traffic_flows.h index dae52b5184d..f5cedd665af 100644 --- a/vpr/src/noc/noc_traffic_flows.h +++ b/vpr/src/noc/noc_traffic_flows.h @@ -23,7 +23,7 @@ * design. * * This class will be primarily used during - * placement to identify which routers inside the NoC(NocStorage) need to be + * placement to identify which routers inside the NoC ( NocStorage ) need to be * routed to each other.This is important since the router modules can be moved * around to different tiles on the FPGA device. * @@ -46,12 +46,14 @@ * */ struct t_noc_traffic_flow { - /** stores the partial names of the router blocks communicating within this traffic flow. Names must uniquely identify router blocks in the netlist.*/ + /** stores the partial name of the source router block communicating within this traffic flow. Names must uniquely identify router blocks in the netlist.*/ std::string source_router_module_name; + /** stores the partial name of the sink router block communicating within this traffic flow. Names must uniquely identify router blocks in the netlist.*/ std::string sink_router_module_name; - /** stores the block id of the two router blocks communicating within this traffic flow. This can be used to retrieve the block information from the clustered netlist*/ + /** stores the block id of the source router block communicating within this traffic flow. This can be used to retrieve the block information from the clustered netlist*/ ClusterBlockId source_router_cluster_id; + /** stores the block id of the destination router block communicating within this traffic flow. This can be used to retrieve the block information from the clustered netlist*/ ClusterBlockId sink_router_cluster_id; /** The bandwidth of the information transferred between the two routers. Units in bytes per second. This parameters will be used to update the link usage in the noc model after routing the traffic flow.*/ diff --git a/vpr/src/noc/xy_routing.h b/vpr/src/noc/xy_routing.h index 259ea18cac8..50e06891d8c 100644 --- a/vpr/src/noc/xy_routing.h +++ b/vpr/src/noc/xy_routing.h @@ -41,7 +41,7 @@ * * Below we have an example of the path determined by this algorithm for a * 3x3 mesh NoC: - * + * ``` * --------- --------- --------- * / / / / / / * / $ / ----------------- / / ------------------ / / @@ -65,7 +65,7 @@ * / / ----------------- / / ------------------ / * / * / / / / / / * --------- --------- --------- - * + * ``` * In the example above, the router marked with the '*' character is the start * and the router marked with the '$' character is the destination. The path * determined by the XY-Routing algorithm is shown as "<++++".