Skip to content
Snippets Groups Projects
Commit ecb1b5e0 authored by Yifan Zhao's avatar Yifan Zhao
Browse files

Fixed HPVM-spec doc structure

parent 3ab9d9d2
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
hpvm/docs/references/hpvm-specification.rst
+ 15
− 54
View file @ ecb1b5e0
.. role:: raw-html-m2r(raw) .. role:: raw-html-m2r(raw)
:format: html :format: html
HPVM Abstraction HPVM Language Reference
================ =======================
Table of Contents
------------------
* `HPVM Abstraction <#abstraction>`_
* `Dataflow Node <#node>`_
* `Dataflow Edge <#edge>`_
* `Input and Output Bind <#bind>`_
* `Host Code <#host>`_
* `HPVM Implementation <#implementation>`_
* `Intrinsics for Describing Graphs <#describing>`_ .. contents:: Table of Contents
* `Intrinsics for Querying Graphs <#querying>`_
* `Intrinsics for Memory Allocation and Synchronization <#memory>`_
* `Intrinsics for Graph Interaction <#interaction>`_
* `Implementation Limitations <#limitations>`_ HPVM Abstraction
----------------
:raw-html-m2r:`<a name="abstraction"></a>`
An HPVM program is a combination of host code plus a set of one or more distinct dataflow graphs. Each dataflow graph (DFG) is a hierarchical graph with side effects. The DFG must be acyclic. Nodes represent units of execution, and edges between nodes describe the explicit data transfer requirements. A node can begin execution once a data item becomes available on every one of its input edges. Repeated transfer of data items between nodes (if more inputs are provided) yields a pipelined execution of different nodes in the graph. The execution of a DFG is initiated and terminated by host code that launches the graph. Nodes may access globally shared memory through load and store instructions (side-effects). An HPVM program is a combination of host code plus a set of one or more distinct dataflow graphs. Each dataflow graph (DFG) is a hierarchical graph with side effects. The DFG must be acyclic. Nodes represent units of execution, and edges between nodes describe the explicit data transfer requirements. A node can begin execution once a data item becomes available on every one of its input edges. Repeated transfer of data items between nodes (if more inputs are provided) yields a pipelined execution of different nodes in the graph. The execution of a DFG is initiated and terminated by host code that launches the graph. Nodes may access globally shared memory through load and store instructions (side-effects).
:raw-html-m2r:`<a name="node"></a>`
Dataflow Node Dataflow Node
------------- ^^^^^^^^^^^^^
A *dataflow node* represents unit of computation in the DFG. A node can begin execution once a data item becomes available on every one of its input edges. A *dataflow node* represents unit of computation in the DFG. A node can begin execution once a data item becomes available on every one of its input edges.
...@@ -44,10 +26,8 @@ Leaf nodes contain code expressing actual computations. Leaf nodes may contain i ...@@ -44,10 +26,8 @@ Leaf nodes contain code expressing actual computations. Leaf nodes may contain i
Note that the graph is fully interpreted at compile-time and cannot be modified at runtime except for the number of dynamic instances, which can be data dependent. Note that the graph is fully interpreted at compile-time and cannot be modified at runtime except for the number of dynamic instances, which can be data dependent.
:raw-html-m2r:`<a name="edge"></a>`
Dataflow Edge Dataflow Edge
------------- ^^^^^^^^^^^^^
A *dataflow edge* from the output ``out`` of a source dataflow node ``Src`` to the input ``in`` of a sink dataflow node ``Dst`` describes the explicit data transfer requirements. ``Src`` and ``Dst`` node must belong to the same child graph, i.e. must be children of the same internal node. A *dataflow edge* from the output ``out`` of a source dataflow node ``Src`` to the input ``in`` of a sink dataflow node ``Dst`` describes the explicit data transfer requirements. ``Src`` and ``Dst`` node must belong to the same child graph, i.e. must be children of the same internal node.
...@@ -57,14 +37,11 @@ A static edge also represents multiple dynamic instances of that edge between th ...@@ -57,14 +37,11 @@ A static edge also represents multiple dynamic instances of that edge between th
An edge can be instantiated at runtime using one of two replication mechanisms: An edge can be instantiated at runtime using one of two replication mechanisms:
* *All-to-all*, where all dynamic instances of the source node are connected to all dynamic instances of the sink node, thus expressing a synchronization barrier between the two groups of nodes, or * *All-to-all*, where all dynamic instances of the source node are connected to all dynamic instances of the sink node, thus expressing a synchronization barrier between the two groups of nodes, or
* *One-to-one*, where each dynamic instance of the source node is connected to a single corresponding instance of the sink node. One-to-one replication requires that the grid structure (number of dimensions and the extents in each dimension) of the source and sink nodes be identical. * *One-to-one*, where each dynamic instance of the source node is connected to a single corresponding instance of the sink node. One-to-one replication requires that the grid structure (number of dimensions and the extents in each dimension) of the source and sink nodes be identical.
:raw-html-m2r:`<a name="bind"></a>`
Input and Output Bind Input and Output Bind
--------------------- ^^^^^^^^^^^^^^^^^^^^^
An internal node is responsible for mapping its inputs, provided by incoming dataflow edges, to the inputs to one or more nodes of the child graph. An internal node is responsible for mapping its inputs, provided by incoming dataflow edges, to the inputs to one or more nodes of the child graph.
...@@ -75,14 +52,11 @@ Conversely, an internal node binds output ``oc`` of its child node ``Src`` to it ...@@ -75,14 +52,11 @@ Conversely, an internal node binds output ``oc`` of its child node ``Src`` to it
A bind is always **all-to-all**. A bind is always **all-to-all**.
:raw-html-m2r:`<a name="host"></a>`
Host Code Host Code
--------- ^^^^^^^^^
In an HPVM program, the host code is responsible for setting up, initiating the execution and blocking for completion of a DFG. The host can interact with the DFG to sustain a streaming computation by sending all data required for, and receiving all data produced by, one execution of the DFG. The list of actions that can be performed by the host is described below: In an HPVM program, the host code is responsible for setting up, initiating the execution and blocking for completion of a DFG. The host can interact with the DFG to sustain a streaming computation by sending all data required for, and receiving all data produced by, one execution of the DFG. The list of actions that can be performed by the host is described below:
* **Initialization and Cleanup**: * **Initialization and Cleanup**:
All HPVM operations must be enclosed by the HPVM initialization and cleanup. These operations perform initialization and cleanup of runtime constructs that provide the runtime support for HPVM. All HPVM operations must be enclosed by the HPVM initialization and cleanup. These operations perform initialization and cleanup of runtime constructs that provide the runtime support for HPVM.
* **Track Memory**: * **Track Memory**:
...@@ -107,10 +81,8 @@ In an HPVM program, the host code is responsible for setting up, initiating the ...@@ -107,10 +81,8 @@ In an HPVM program, the host code is responsible for setting up, initiating the
* For a non-streaming DFG, the data produced by the DFG are ready to be read by the host. * For a non-streaming DFG, the data produced by the DFG are ready to be read by the host.
* For a streaming DFG, no more data may be provided for processing by the DFG. * For a streaming DFG, no more data may be provided for processing by the DFG.
:raw-html-m2r:`<a name="implementation"></a>`
HPVM Implementation HPVM Implementation
=================== -------------------
This section describes the implementation of HPVM on top of LLVM IR. This section describes the implementation of HPVM on top of LLVM IR.
...@@ -128,10 +100,8 @@ We represent nodes with opaque handles (pointers of LLVM type i8*). We represent ...@@ -128,10 +100,8 @@ We represent nodes with opaque handles (pointers of LLVM type i8*). We represent
Pointer arguments of node functions are required to be annotated with attributes in, and/or out, depending on their expected use (read only, write only, read write). Pointer arguments of node functions are required to be annotated with attributes in, and/or out, depending on their expected use (read only, write only, read write).
:raw-html-m2r:`<a name="describing"></a>`
Intrinsics for Describing Graphs Intrinsics for Describing Graphs
-------------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The intrinsics for describing graphs can only be used by internal nodes. Also, internal nodes are only allowed to have these intrinsics as part of their node function, with the exception of a return statement of the appropriate type, in order to return the result of the outgoing dataflow edges. The intrinsics for describing graphs can only be used by internal nodes. Also, internal nodes are only allowed to have these intrinsics as part of their node function, with the exception of a return statement of the appropriate type, in order to return the result of the outgoing dataflow edges.
...@@ -156,10 +126,8 @@ Bind input ``ip`` of current node to input ``ic`` of child node ``N``. Argument ...@@ -156,10 +126,8 @@ Bind input ``ip`` of current node to input ``ic`` of child node ``N``. Argument
``void llvm.hpvm.bind.output(i8* N, i32 oc, i32 op, i1 isStream)``:raw-html-m2r:`<br>` ``void llvm.hpvm.bind.output(i8* N, i32 oc, i32 op, i1 isStream)``:raw-html-m2r:`<br>`
Bind output ``oc`` of child node ``N`` to output ``op`` of current node. Field ``oc`` of the return struct in ``N``'s node function and field ``op`` of the return struct in the current node function must have matching types. ``isStream`` chooses a streaming (1) or non streaming (0) bind. Bind output ``oc`` of child node ``N`` to output ``op`` of current node. Field ``oc`` of the return struct in ``N``'s node function and field ``op`` of the return struct in the current node function must have matching types. ``isStream`` chooses a streaming (1) or non streaming (0) bind.
:raw-html-m2r:`<a name="querying"></a>`
Intrinsics for Querying Graphs Intrinsics for Querying Graphs
------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following intrinsics are used to query the structure of the DFG. They can only be used by leaf nodes. The following intrinsics are used to query the structure of the DFG. They can only be used by leaf nodes.
...@@ -178,10 +146,8 @@ Get index of current dynamic node instance of node ``N`` in dimension x, y or z ...@@ -178,10 +146,8 @@ Get index of current dynamic node instance of node ``N`` in dimension x, y or z
``i64 llvm.hpvm.getNumNodeInstances.{x,y,z}(i8* N)``:raw-html-m2r:`<br>` ``i64 llvm.hpvm.getNumNodeInstances.{x,y,z}(i8* N)``:raw-html-m2r:`<br>`
Get number of dynamic instances of node ``N`` in dimension x, y or z respectively. The dimension must be one of the dimensions in which the node is replicated. Get number of dynamic instances of node ``N`` in dimension x, y or z respectively. The dimension must be one of the dimensions in which the node is replicated.
:raw-html-m2r:`<a name="memory"></a>`
Intrinsics for Memory Allocation and Synchronization Intrinsics for Memory Allocation and Synchronization
---------------------------------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following intrinsics are used for memory allocation and synchronization. They can only be used by leaf nodes. The following intrinsics are used for memory allocation and synchronization. They can only be used by leaf nodes.
...@@ -216,10 +182,8 @@ Atomically computes the bitwise XOR of ``v`` and the value stored at memory loca ...@@ -216,10 +182,8 @@ Atomically computes the bitwise XOR of ``v`` and the value stored at memory loca
``void llvm.hpvm.barrier()``:raw-html-m2r:`<br>` ``void llvm.hpvm.barrier()``:raw-html-m2r:`<br>`
Local synchronization barrier across dynamic instances of current leaf node. Local synchronization barrier across dynamic instances of current leaf node.
:raw-html-m2r:`<a name="interaction"></a>`
Intrinsics for Graph Interaction Intrinsics for Graph Interaction
-------------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following intrinsics are for graph initialization/termination and interaction with the host code, and can be used only by the host code. The following intrinsics are for graph initialization/termination and interaction with the host code, and can be used only by the host code.
...@@ -250,14 +214,11 @@ Push set of input data ``args`` (same as type included in launch) to streaming D ...@@ -250,14 +214,11 @@ Push set of input data ``args`` (same as type included in launch) to streaming D
``i8* llvm.hpvm.pop(i8* GraphID)``:raw-html-m2r:`<br>` ``i8* llvm.hpvm.pop(i8* GraphID)``:raw-html-m2r:`<br>`
Pop and return data from streaming DFG with handle ``GraphID``. The return type is a struct containing a field for every output of DFG. Pop and return data from streaming DFG with handle ``GraphID``. The return type is a struct containing a field for every output of DFG.
:raw-html-m2r:`<a name="limitations"></a>`
Implementation Limitations Implementation Limitations
-------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^
Due to limitations of our current prototype implementation, the following restrictions are imposed: Due to limitations of our current prototype implementation, the following restrictions are imposed:
* In HPVM, a memory object is represented as a (pointer, size) pair that includes the address of memory object, and the size (in bytes) of the pointed-to object. Therefore, when an edge/bind carries a pointer, it must be followed by an i64 size value. * In HPVM, a memory object is represented as a (pointer, size) pair that includes the address of memory object, and the size (in bytes) of the pointed-to object. Therefore, when an edge/bind carries a pointer, it must be followed by an i64 size value.
* *
Pointers cannot be transferred between nodes using dataflow edges. Instead, they should be passed using the bind operation from the (common) parent of the source and sink nodes. Pointers cannot be transferred between nodes using dataflow edges. Instead, they should be passed using the bind operation from the (common) parent of the source and sink nodes.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment