Expand hip graph documentation with memory nodes

docs/understand/hipgraph.rst

@@ -18,14 +18,22 @@ way via streams.
     supported. For a list of all currently supported functions see the
     :doc:`HIP graph API documentation<../doxygen/html/group___graph>`.
 
+Setting up HIP graphs
+================================================================================
+
+HIP graphs can be created by explicitly defining them, or using stream capture.
+For further information on how to use HIP graphs see :ref:`the how-to-chapter about HIP graphs<how_to_HIP_graph>`.
+For the available functions see the
+:doc:`HIP graph API documentation<../doxygen/html/group___graph>`.
+
 Graph format
 ================================================================================
 
 A HIP graph is made up of nodes and edges. The nodes of a HIP graph represent
 the operations performed, while the edges mark dependencies between those
 operations.
 
-The nodes can consist of:
+The nodes can be one of the following:
 
 - empty nodes
 - nested graphs
@@ -43,6 +51,35 @@ The following figure visualizes the concept of graphs, compared to using streams
           hipDeviceSynchronize, or using graphs, where the edges denote the
           dependencies.
 
+Node types
+--------------------------------------------------------------------------------
+
+The available node types are specified by :cpp:enumerator:`hipGraphNodeType`.
+
+Memory management nodes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Memory management nodes handle allocating and freeing of memory of a graph.
+Memory management nodes can be created by using the explicit API functions, or
+by capturing :cpp:func:`hipMallocAsync` or :cpp:func:`hipFreeAsync`.
+Unlike the normal memory management API, which is controlled by host-side execution,
+this enables HIP to take care of memory reuse and optimizations.
+The lifetime of memory allocated in a graph begins when the execution reaches the
+node allocating the memory, and ends when either reaching the corresponding
+free node within the graph, or after graph execution with a corresponding
+:cpp:func:`hipFreeAsync` call, or a corresponding :cpp:func:`hipFree` call.
+The memory can also be freed with a free node in a different graph that is
+associated with the same memory address.
+
+The same rules as for normal memory allocations apply for memory allocated and
+freed by nodes, meaning that the nodes that access memory allocated in a graph
+must be ordered after the allocation node and before the freeing node.
+
+These memory allocations can also be set up to allow access from multiple GPUs,
+just like normal allocations. HIP then takes care of allocating and mapping the
+memory to the GPUs. When capturing a graph from a stream, the node sets the
+accessibility according to hipMemPoolSetAccess at the time of capturing.
+
 HIP graph advantages
 ================================================================================
 
@@ -82,11 +119,3 @@ dependencies and necessary synchronizations as specified.
 
 As HIP graphs require some set up and initialization overhead before their first
 execution, they only provide a benefit for workloads that require many iterations to complete.
-
-Setting up HIP graphs
-================================================================================
-
-HIP graphs can be created by explicitly defining them, or using stream capture.
-For further information on how to use HIP graphs see :ref:`the how-to-chapter about HIP graphs<how_to_HIP_graph>`.
-For the available functions see the
-:doc:`HIP graph API documentation<../doxygen/html/group___graph>`.