diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc index 4ed2abdf0e880..6d791adac50b1 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc @@ -1691,45 +1691,79 @@ Exceptions: |=== -=== Features Still in Development - ==== Memory Allocation Nodes -There is no provided interface for users to define a USM allocation/free -operation belonging to the scope of the graph. It would be error prone and -non-performant to allocate or free memory as a node executed during graph -submission. Instead, such a memory allocation API needs to provide a way to -return a pointer which won't be valid until the allocation is made on graph -finalization, as allocating at finalization is the only way to benefit from -the known graph scope for optimal memory allocation, and even optimize to -eliminate some allocations entirely. - -Such a deferred allocation strategy presents challenges however, and as a result -we recommend instead that prior to graph construction users perform core SYCL -USM allocations to be used in the graph submission. Before to coming to this -recommendation we considered the following explicit graph building interfaces -for adding a memory allocation owned by the graph: - -1. Allocation function returning a reference to the raw pointer, i.e. `void*&`, - which will be instantiated on graph finalization with the location of the - allocated USM memory. - -2. Allocation function returning a handle to the allocation. Applications use - the handle in node command-group functions to access memory when allocated. - -3. Allocation function returning a pointer to a virtual allocation, only backed - with an actual allocation when graph is finalized or submitted. - -Design 1) has the drawback of forcing users to keep the user pointer variable -alive so that the reference is valid, which is unintuitive and is likely to -result in bugs. - -Design 2) introduces a handle object which has the advantages of being a less -error prone way to provide the pointer to the deferred allocation. However, it -requires kernel changes and introduces an overhead above the raw pointers that -are the advantage of USM. - -Design 3) needs specific backend support for deferred allocation. +Support depends on the availablity of backend support for deferred allocation: +link:../experimental/sycl_ext_oneapi_virtual_mem.asciidoc[sycl_ext_oneapi_virtual_mem] + +The following interfaces enables users to define a memory allocation/free operation +belonging to the scope of the graph. It would be error prone and non-performant +to allocate or free memory as a node executed during graph submission. Instead, +such a memory allocation API needs to provide a way to return a pointer which +won't be valid until the allocation is made on graph finalization, as allocating +at finalization is the only way to benefit from the known graph scope for optimal +memory allocation, and even optimize to eliminate some allocations entirely. + +Table {counter: tableNumber}. Member functions of the `command_graph` class (memory allocation). +[cols="2a,a"] +|=== +|Member function|Description + +| +[source, c++] +---- +std::pair +add_malloc_device(size_t num_bytes, const property_list& propList = {}); +---- + + +| +Returns a pair of a pointer to memory and a node. The pointer is allocated on the `device` +that is associated with current graph by first execution of the `command_graph`. +All nodes that depend on this node and are thereby executed after have access to the allocated memory. +The allocation size is specified in bytes. + +Preconditions: + +* This member function is only available when the `command_graph` state is + `graph_state::modifiable`. + +Parameters: + +* `num_bytes` - allocation size in bytes. + +* `propList` - Zero or more properties can be provided to the constructed node + via an instance of `property_list`. The `property::node::depends_on` property + can be passed here with a list of nodes to create dependency edges on. + +Exceptions: + +* Throws synchronously with error code `feature_not_supported` if any devices in `context` +does not have `aspect::usm_device_allocations`. +| + +[source, c++] +---- +node +add_free(void* ptr, const property_list& propList = {}); +---- + + +| +Returns a free node that has been added to the graph. Accesses of nodes that depend of this node +(predecessors) to the allocated memory are undefined behavior. + +Parameters: + +* `ptr` - memory pointed to by. Must be allocated by `add_malloc_device`. + +* `propList` - Zero or more properties can be provided to the constructed node + via an instance of `property_list`. The `property::node::depends_on` property + can be passed here with a list of nodes to create dependency edges on. + +|=== + +=== Features Still in Development ==== Device Specific Graph