Skip to content

Commit c42a5af

Browse files
a-sullya-sully
committed
remove MLCommandEncoder
1 parent 7ec2e18 commit c42a5af

File tree

1 file changed

+2
-151
lines changed

1 file changed

+2
-151
lines changed

‎index.bs

+2-151
Original file line numberDiff line numberDiff line change
@@ -672,7 +672,7 @@ Note: The group is <a href="https://github.com/webmachinelearning/webnn/issues/8
672672

673673
Unlike WebGPU, this API does not intrinsically support custom shader authoring; and as a result is not prone to timing attacks that rely on shader caches, or other persistent data. The API builds upon pre-existing shaders and lower level primitives of the browser or the underlying OS. Web developers who interface with {{GPUDevice}} are expected to be aware of <a href="https://gpuweb.github.io/gpuweb/#privacy-user-agent-state">WebGPU compilation cache considerations</a>.
674674

675-
The WebGPU API identifies <a href="https://gpuweb.github.io/gpuweb/#privacy-machine-artifacts">machine-specific artifacts</a> as a privacy consideration. Given the WebNN API defines means to record an ML workload onto a WebGPU-compatible {{GPUCommandBuffer}}, compute unit scheduling may under certain circumstances introduce a fingerprint. However, similarly to WebGPU, such fingerprints are identical across most or all of the devices of each vendor, mitigating the concern. Furthermore, software implementations can be used to further eliminate such artifacts.
675+
The WebGPU API identifies <a href="https://gpuweb.github.io/gpuweb/#privacy-machine-artifacts">machine-specific artifacts</a> as a privacy consideration. Similarly, the WebNN API's compute unit scheduling may under certain circumstances introduce a fingerprint. However, similarly to WebGPU, such fingerprints are identical across most or all of the devices of each vendor, mitigating the concern. Furthermore, software implementations can be used to further eliminate such artifacts.
676676

677677
The WebNN API defines two developer-settable preferences to help inform [[#programming-model-device-selection]] and allow the implementation to better select the most appropriate underlying execution device for the workload. [=Device type=] normatively indicates the kind of device and is either {{MLDeviceType/"cpu"}} or {{MLDeviceType/"gpu"}}. If this type cannot be satisfied, an "{{OperationError}}" {{DOMException}} is thrown, thus this type can in some cases add two bits of entropy to the fingerprint. [=Power preference=] indicates preference as related to the power consumption and is considered a hint only and as such does not increase entropy of the fingerprint.
678678

@@ -746,13 +746,6 @@ In both the {{MLContext}}.{{MLContext/compute()}} and {{MLContext}}.{{MLContext/
746746
the input values using {{MLNamedArrayBufferViews}}, binding the input {{MLOperand}}s to their values. The caller
747747
then supplies pre-allocated buffers for output {{MLOperand}}s using {{MLNamedArrayBufferViews}}.
748748

749-
The {{MLCommandEncoder}} interface created by the {{MLContext}}.{{MLContext/createCommandEncoder()}} method supports
750-
a graph execution method that provides the maximum flexibility to callers that also utilize WebGPU in their
751-
application. It does this by placing the workload required to initialize and compute the results of the
752-
operations in the graph onto a {{GPUCommandBuffer}}. The callers are responsible for the eventual submission
753-
of this workload on the {{GPUQueue}} through the WebGPU queue submission mechanism. Once the submitted workload
754-
is completely executed, the result is avaialble in the bound output buffers.
755-
756749
## Device Selection ## {#programming-model-device-selection}
757750

758751
An {{MLContext}} interface represents a global state of neural network execution. One of the important context states is the underlying execution device that manages the resources and facilitates the compilation and the eventual execution of the neural network graph. In addition to the default method of creation with {{MLContextOptions}}, an {{MLContext}} could also be created from a specific {{GPUDevice}} that is already in use by the application, in which case the corresponding {{GPUBuffer}} resources used as graph constants, as well as the {{GPUTexture}} as graph inputs must also be created from the same device. In a multi-adapter configuration, the device used for {{MLContext}} must be created from the same adapter as the device used to allocate the resources referenced in the graph.
@@ -950,135 +943,6 @@ The {{MLActivation}} objects (including the ones passed as input to methods) are
950943
</div>
951944
</details>
952945

953-
## {{MLCommandEncoder}} interface ## {#api-mlcommandencoder}
954-
The {{MLCommandEncoder}} interface represents a method of execution that synchronously records the computational workload of a compiled {{MLGraph}} to a {{GPUCommandBuffer}} on the calling thread. Since the workload is not immediately executed, just recorded, this method allows more flexibility for the caller to determine how and when the recorded commands will be submitted for execution on the GPU relative to other GPU workload on the same or different queue.
955-
956-
<script type=idl>
957-
typedef (GPUBuffer or GPUTexture) MLGPUResource;
958-
959-
typedef record<DOMString, MLGPUResource> MLNamedGPUResources;
960-
961-
[SecureContext, Exposed=(Window, DedicatedWorker)]
962-
interface MLCommandEncoder {};
963-
</script>
964-
965-
<div class=internal-slots>
966-
{{MLCommandEncoder}} has the following internal slots:
967-
<dl dfn-type=attribute dfn-for="MLCommandEncoder">
968-
: <dfn>\[[context]]</dfn> of type {{MLContext}}
969-
::
970-
The context of type {{MLContext}} associated with this {{MLCommandEncoder}}.
971-
972-
: <dfn>\[[implementation]]</dfn>
973-
::
974-
The underlying implementation provided by the User Agent.
975-
</dl>
976-
</div>
977-
978-
### Graph Initialization ### {#api-mlcommandencoder-graph-initialization}
979-
Record the initialization of the {{MLGraph}}. This is a necessary step for optimal performance during graph execution as it gives the platform an opportunity to prepare and optimize constant input data for the subsequent execution of the graph. This method should only be called once per graph.
980-
981-
<script type=idl>
982-
partial interface MLCommandEncoder {
983-
undefined initializeGraph(MLGraph graph);
984-
};
985-
</script>
986-
987-
<div>
988-
**Arguments:**
989-
- *graph*: an {{MLGraph}}. The compiled graph to be initialized with graph constant inputs.
990-
991-
**Returns:** {{undefined}}.
992-
</div>
993-
994-
<details open algorithm>
995-
<summary>
996-
The <dfn method for=MLCommandEncoder>initializeGraph(<var ignore>graph</var>)</dfn> method steps are:
997-
</summary>
998-
<div>
999-
<div class="note">
1000-
Graph initialization stage typically involves a process known as "weight preprocessing" where all the constant inputs to the graph are preprocessed and cached at the operating system level for subsequent graph execution calls. The initializing inputs are typically the constant weight data specified through the {{MLGraphBuilder/constant(descriptor, bufferView)|MLGraphBuilder/constant(value, type)}} method as constant operands during graph construction time.
1001-
</div>
1002-
</div>
1003-
</details>
1004-
1005-
### Dispatch Execution Commands ### {#api-mlcommandencoder-dispatch-commands}
1006-
Record the {{MLGraph}} execution with the inputs {{MLNamedGPUResources}} and outputs {{MLNamedGPUResources}}.
1007-
1008-
<script type=idl>
1009-
partial interface MLCommandEncoder {
1010-
undefined dispatch(MLGraph graph, MLNamedGPUResources inputs, MLNamedGPUResources outputs);
1011-
};
1012-
</script>
1013-
1014-
<div>
1015-
**Arguments:**
1016-
- *graph*: an {{MLGraph}}. The compiled graph to be executed.
1017-
- *inputs*: an {{MLNamedGPUResources}}. The resources of inputs.
1018-
- *outputs*: an {{MLNamedGPUResources}}. The pre-allocated resources of required outputs.
1019-
1020-
**Returns:** {{undefined}}.
1021-
</div>
1022-
1023-
<details open algorithm>
1024-
<summary>
1025-
The <dfn method for=MLCommandEncoder>dispatch(|graph|, |inputs|, |outputs|)</dfn> method steps are:
1026-
</summary>
1027-
<div class=algorithm-steps>
1028-
1. If any of the following requirements are unmet, then [=exception/throw=] a "{{DataError}}" {{DOMException}}.
1029-
<div class=validusage>
1030-
1. [=map/For each=] |name| &rarr; |input| of |inputs|:
1031-
1. |graph|.{{MLGraph/[[inputDescriptors]]}}[|name|] must [=map/exist=].
1032-
1. Let |inputDesc| be |graph|.{{MLGraph/[[inputDescriptors]]}}[|name|].
1033-
1. If |input| is a {{GPUBuffer}}, then:
1034-
1. |input|.{{GPUBuffer/size}} must equal to [=byte length=] of |inputDesc|.
1035-
1. [=map/For each=] |name| &rarr; |output| of |outputs|:
1036-
1. |graph|.{{MLGraph/[[outputDescriptors]]}}[|name|] must [=map/exist=].
1037-
1. Let |outputDesc| be |graph|.{{MLGraph/[[outputDescriptors]]}}[|name|].
1038-
1. If |output| is a {{GPUBuffer}}, then:
1039-
1. |output|.{{GPUBuffer/size}} must equal to [=byte length=] of |outputDesc|.
1040-
</div>
1041-
1. [=map/For each=] |name| &rarr; |input| of |inputs|:
1042-
1. Set the input of |graph|.{{MLGraph/[[implementation]]}} that is associated with |name| to |input|.
1043-
1. [=map/For each=] |name| &rarr; |output| of |outputs|:
1044-
1. Set the output of |graph|.{{MLGraph/[[implementation]]}} that is associated with |name| to |output|.
1045-
1. Issue a compute request of |graph|.{{MLGraph/[[implementation]]}}.
1046-
1. If there is an error returned by |graph|.{{MLGraph/[[implementation]]}}, then:
1047-
1. Throw an "{{OperationError}}" {{DOMException}}.
1048-
1. Return {{undefined}}.
1049-
</div>
1050-
</details>
1051-
1052-
### Generate GPU Command Buffer ### {#api-mlcommandencoder-generate-gpu-command-buffer}
1053-
Complete the recording of ML workload and return a WebGPU-compatible {{GPUCommandBuffer}} containing the recorded workload.
1054-
1055-
<script type=idl>
1056-
partial interface MLCommandEncoder {
1057-
GPUCommandBuffer finish(optional GPUCommandBufferDescriptor descriptor = {});
1058-
};
1059-
</script>
1060-
1061-
<div>
1062-
**Arguments:**
1063-
- *descriptor*: an optional {{GPUCommandBufferDescriptor}}. Descriptor of the command buffer.
1064-
1065-
**Returns:** {{GPUCommandBuffer}}.
1066-
</div>
1067-
1068-
<details open algorithm>
1069-
<summary>
1070-
The <dfn method for=MLCommandEncoder>finish(|descriptor|)</dfn> method steps are:
1071-
</summary>
1072-
<div class=algorithm-steps>
1073-
1. If any of the following sub-steps fail, [=exception/throw=] an "{{OperationError}}" {{DOMException}}.
1074-
1. Make a request to the underlying platform to complete the recording of the ML workload, given |descriptor|.
1075-
<div class="note">
1076-
See the related <a href="https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-finish">WebGPU steps</a>.
1077-
</div>
1078-
1. Return a {{GPUCommandBuffer}} containing the recorded workload.
1079-
</div>
1080-
</details>
1081-
1082946
## {{MLContext}} interface ## {#api-mlcontext}
1083947
The {{MLContext}} interface represents a global state of neural network compute workload and execution processes. Each {{MLContext}} object has associated [=context type=], [=device type=] and [=power preference=].
1084948

@@ -1355,19 +1219,6 @@ partial interface MLContext {
13551219
</details>
13561220
</div>
13571221

1358-
### WebGPU Interoperability ### {#api-mlcontext-webgpu-interop}
1359-
Create {{MLCommandEncoder}} interface used to record the ML workload onto a WebGPU-compatible {{GPUCommandBuffer}} to allow mixing of ML workload with other GPU workload in an application that leverages WebGPU. This method only succeeds on an {{MLContext}} created with {{GPUDevice}}. Otherwise, it [=exception/throws=] an "{{OperationError}}" {{DOMException}}.
1360-
1361-
<script type=idl>
1362-
partial interface MLContext {
1363-
MLCommandEncoder createCommandEncoder();
1364-
};
1365-
</script>
1366-
1367-
<div algorithm=mlcontext.createcommandencoder>
1368-
**Returns:** {{MLCommandEncoder}}. The command encoder used to record ML workload on the GPU.
1369-
</div>
1370-
13711222
## {{MLGraph}} interface ## {#api-mlgraph}
13721223
The {{MLGraph}} interface represents a compiled computational graph. A compiled graph once constructed is immutable and cannot be subsequently changed.
13731224

@@ -1436,7 +1287,7 @@ interface MLGraphBuilder {
14361287
</script>
14371288

14381289
<div class="note">
1439-
Both {{MLGraphBuilder}}.{{MLGraphBuilder/build()}} and {{MLGraphBuilder}}.{{MLGraphBuilder/buildSync()}} methods compile the graph builder state up to the specified output operands into a compiled graph according to the type of {{MLContext}} that creates it. Since this operation can be costly in some machine configurations, the calling thread of the {{MLGraphBuilder}}.{{MLGraphBuilder/buildSync()}} method must only be a worker thread to avoid potential disruption of the user experience. When the {{[[contextType]]}} of the {{MLContext}} is set to "[=context type/default=]", the compiled graph is initialized right before the {{MLGraph}} is returned. This graph initialization stage is important for optimal performance of the subsequent graph executions. See [[#api-mlcommandencoder-graph-initialization]] for more detail.
1290+
Both {{MLGraphBuilder}}.{{MLGraphBuilder/build()}} and {{MLGraphBuilder}}.{{MLGraphBuilder/buildSync()}} methods compile the graph builder state up to the specified output operands into a compiled graph according to the type of {{MLContext}} that creates it. Since this operation can be costly in some machine configurations, the calling thread of the {{MLGraphBuilder}}.{{MLGraphBuilder/buildSync()}} method must only be a worker thread to avoid potential disruption of the user experience. When the {{[[contextType]]}} of the {{MLContext}} is set to "[=context type/default=]", the compiled graph is initialized right before the {{MLGraph}} is returned. This graph initialization stage is important for optimal performance of the subsequent graph executions.
14401291
</div>
14411292

14421293
{{MLBufferResourceView}} has the following members:

0 commit comments

Comments
 (0)