Skip to content

Commit 8adc5b9

Browse files
alexcrichtonabrown
authored andcommitted
Update the wasi-nn witx files
1 parent 7380a0a commit 8adc5b9

File tree

4 files changed

+91
-48
lines changed

4 files changed

+91
-48
lines changed

phases/ephemeral/docs.md

Lines changed: 69 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1209,15 +1209,15 @@ Size: 4
12091209

12101210
Alignment: 4
12111211

1212-
## <a href="#nn_errno" name="nn_errno"></a> `nn_errno`: Enum(`u16`)
1212+
## <a href="#nn_errno" name="nn_errno"></a> `nn_errno`: `Variant`
12131213
Error codes returned by functions in this API. This is prefixed to avoid conflicts with the `$errno` in
12141214
`typenames.witx`.
12151215

12161216
Size: 2
12171217

12181218
Alignment: 2
12191219

1220-
### Variants
1220+
### Variant cases
12211221
- <a href="#nn_errno.success" name="nn_errno.success"></a> `success`
12221222
No error occurred.
12231223

@@ -1230,7 +1230,7 @@ Caller module is missing a memory export.
12301230
- <a href="#nn_errno.busy" name="nn_errno.busy"></a> `busy`
12311231
Device or resource busy.
12321232

1233-
## <a href="#tensor_dimensions" name="tensor_dimensions"></a> `tensor_dimensions`: `Array<u32>`
1233+
## <a href="#tensor_dimensions" name="tensor_dimensions"></a> `tensor_dimensions`: `List<u32>`
12341234
The dimensions of a tensor.
12351235

12361236
The array length matches the tensor rank and each element in the array
@@ -1240,14 +1240,14 @@ Size: 8
12401240

12411241
Alignment: 4
12421242

1243-
## <a href="#tensor_type" name="tensor_type"></a> `tensor_type`: Enum(`u8`)
1243+
## <a href="#tensor_type" name="tensor_type"></a> `tensor_type`: `Variant`
12441244
The type of the elements in a tensor.
12451245

12461246
Size: 1
12471247

12481248
Alignment: 1
12491249

1250-
### Variants
1250+
### Variant cases
12511251
- <a href="#tensor_type.f16" name="tensor_type.f16"></a> `f16`
12521252

12531253
- <a href="#tensor_type.f32" name="tensor_type.f32"></a> `f32`
@@ -1256,7 +1256,7 @@ Alignment: 1
12561256

12571257
- <a href="#tensor_type.i32" name="tensor_type.i32"></a> `i32`
12581258

1259-
## <a href="#tensor_data" name="tensor_data"></a> `tensor_data`: `Array<u8>`
1259+
## <a href="#tensor_data" name="tensor_data"></a> `tensor_data`: `List<u8>`
12601260
The tensor data
12611261

12621262
Initially conceived as a sparse representation, each empty cell would be filled with zeroes and
@@ -1269,14 +1269,14 @@ Size: 8
12691269

12701270
Alignment: 4
12711271

1272-
## <a href="#tensor" name="tensor"></a> `tensor`: Struct
1272+
## <a href="#tensor" name="tensor"></a> `tensor`: `Record`
12731273
A tensor.
12741274

12751275
Size: 20
12761276

12771277
Alignment: 4
12781278

1279-
### Struct members
1279+
### Record members
12801280
- <a href="#tensor.dimensions" name="tensor.dimensions"></a> `dimensions`: [`tensor_dimensions`](#tensor_dimensions)
12811281
Describe the size of the tensor (e.g. 2x2x2x2 -> [2, 2, 2, 2]). To represent a tensor containing a single value,
12821282
use `[1]` for the tensor dimensions.
@@ -1292,55 +1292,55 @@ Contains the tensor data.
12921292

12931293
Offset: 12
12941294

1295-
## <a href="#graph_builder" name="graph_builder"></a> `graph_builder`: `Array<u8>`
1295+
## <a href="#graph_builder" name="graph_builder"></a> `graph_builder`: `List<u8>`
12961296
The graph initialization data. This consists of an array of buffers because implementing backends may encode their
12971297
graph IR in parts (e.g. OpenVINO stores its IR and weights separately).
12981298

12991299
Size: 8
13001300

13011301
Alignment: 4
13021302

1303-
## <a href="#graph_builder_array" name="graph_builder_array"></a> `graph_builder_array`: `Array<graph_builder>`
1303+
## <a href="#graph_builder_array" name="graph_builder_array"></a> `graph_builder_array`: `List<graph_builder>`
13041304

13051305
Size: 8
13061306

13071307
Alignment: 4
13081308

1309-
## <a href="#graph" name="graph"></a> `graph`
1309+
## <a href="#graph" name="graph"></a> `graph`: `Handle`
13101310
An execution graph for performing inference (i.e. a model).
13111311

13121312
Size: 4
13131313

13141314
Alignment: 4
13151315

13161316
### Supertypes
1317-
## <a href="#graph_encoding" name="graph_encoding"></a> `graph_encoding`: Enum(`u8`)
1317+
## <a href="#graph_encoding" name="graph_encoding"></a> `graph_encoding`: `Variant`
13181318
Describes the encoding of the graph. This allows the API to be implemented by various backends that encode (i.e.
13191319
serialize) their graph IR differently.
13201320

13211321
Size: 1
13221322

13231323
Alignment: 1
13241324

1325-
### Variants
1325+
### Variant cases
13261326
- <a href="#graph_encoding.openvino" name="graph_encoding.openvino"></a> `openvino`
13271327
TODO document buffer order
13281328

1329-
## <a href="#execution_target" name="execution_target"></a> `execution_target`: Enum(`u8`)
1329+
## <a href="#execution_target" name="execution_target"></a> `execution_target`: `Variant`
13301330
Define where the graph should be executed.
13311331

13321332
Size: 1
13331333

13341334
Alignment: 1
13351335

1336-
### Variants
1336+
### Variant cases
13371337
- <a href="#execution_target.cpu" name="execution_target.cpu"></a> `cpu`
13381338

13391339
- <a href="#execution_target.gpu" name="execution_target.gpu"></a> `gpu`
13401340

13411341
- <a href="#execution_target.tpu" name="execution_target.tpu"></a> `tpu`
13421342

1343-
## <a href="#graph_execution_context" name="graph_execution_context"></a> `graph_execution_context`
1343+
## <a href="#graph_execution_context" name="graph_execution_context"></a> `graph_execution_context`: `Handle`
13441344
A $graph_execution_context allows for attaching inputs prior to calling [`compute`](#compute) on a graph and retrieving outputs after
13451345
the computation has completed. TODO a handle may not be the right type but we want it to be opaque to users.
13461346

@@ -2705,7 +2705,7 @@ Which channels on the socket to shut down.
27052705

27062706
---
27072707

2708-
#### <a href="#load" name="load"></a> `load(builder: graph_builder_array, encoding: graph_encoding, target: execution_target) -> (nn_errno, graph)`
2708+
#### <a href="#load" name="load"></a> `load(builder: graph_builder_array, encoding: graph_encoding, target: execution_target) -> Result<graph, nn_errno>`
27092709
Load an opaque sequence of bytes to use for inference.
27102710

27112711
This allows runtime implementations to support multiple graph encoding formats. For unsupported graph encodings,
@@ -2722,14 +2722,21 @@ The encoding of the graph.
27222722
Where to execute the graph.
27232723

27242724
##### Results
2725-
- <a href="#load.error" name="load.error"></a> `error`: [`nn_errno`](#nn_errno)
2725+
- <a href="#load.error" name="load.error"></a> `error`: `Result<graph, nn_errno>`
2726+
2727+
###### Variant Layout
2728+
- size: 8
2729+
- align: 4
2730+
- tag_size: 4
2731+
###### Variant cases
2732+
- <a href="#load.error.ok" name="load.error.ok"></a> `ok`: [`graph`](#graph)
27262733

2727-
- <a href="#load.graph" name="load.graph"></a> `graph`: [`graph`](#graph)
2734+
- <a href="#load.error.err" name="load.error.err"></a> `err`: [`nn_errno`](#nn_errno)
27282735

27292736

27302737
---
27312738

2732-
#### <a href="#init_execution_context" name="init_execution_context"></a> `init_execution_context(graph: graph) -> (nn_errno, graph_execution_context)`
2739+
#### <a href="#init_execution_context" name="init_execution_context"></a> `init_execution_context(graph: graph) -> Result<graph_execution_context, nn_errno>`
27332740
TODO Functions like `describe_graph_inputs` and `describe_graph_outputs` (returning
27342741
an array of `$tensor_description`s) might be useful for introspecting the graph but are not yet included here.
27352742
Create an execution instance of a loaded graph.
@@ -2739,14 +2746,21 @@ TODO this may need to accept flags that might affect the compilation or executio
27392746
- <a href="#init_execution_context.graph" name="init_execution_context.graph"></a> `graph`: [`graph`](#graph)
27402747

27412748
##### Results
2742-
- <a href="#init_execution_context.error" name="init_execution_context.error"></a> `error`: [`nn_errno`](#nn_errno)
2749+
- <a href="#init_execution_context.error" name="init_execution_context.error"></a> `error`: `Result<graph_execution_context, nn_errno>`
2750+
2751+
###### Variant Layout
2752+
- size: 8
2753+
- align: 4
2754+
- tag_size: 4
2755+
###### Variant cases
2756+
- <a href="#init_execution_context.error.ok" name="init_execution_context.error.ok"></a> `ok`: [`graph_execution_context`](#graph_execution_context)
27432757

2744-
- <a href="#init_execution_context.context" name="init_execution_context.context"></a> `context`: [`graph_execution_context`](#graph_execution_context)
2758+
- <a href="#init_execution_context.error.err" name="init_execution_context.error.err"></a> `err`: [`nn_errno`](#nn_errno)
27452759

27462760

27472761
---
27482762

2749-
#### <a href="#set_input" name="set_input"></a> `set_input(context: graph_execution_context, index: u32, tensor: tensor) -> nn_errno`
2763+
#### <a href="#set_input" name="set_input"></a> `set_input(context: graph_execution_context, index: u32, tensor: tensor) -> Result<(), nn_errno>`
27502764
Define the inputs to use for inference.
27512765

27522766
This should return an $nn_errno (TODO define) if the input tensor does not match the expected dimensions and type.
@@ -2761,12 +2775,21 @@ The index of the input to change.
27612775
The tensor to set as the input.
27622776

27632777
##### Results
2764-
- <a href="#set_input.error" name="set_input.error"></a> `error`: [`nn_errno`](#nn_errno)
2778+
- <a href="#set_input.error" name="set_input.error"></a> `error`: `Result<(), nn_errno>`
2779+
2780+
###### Variant Layout
2781+
- size: 8
2782+
- align: 4
2783+
- tag_size: 4
2784+
###### Variant cases
2785+
- <a href="#set_input.error.ok" name="set_input.error.ok"></a> `ok`
2786+
2787+
- <a href="#set_input.error.err" name="set_input.error.err"></a> `err`: [`nn_errno`](#nn_errno)
27652788

27662789

27672790
---
27682791

2769-
#### <a href="#get_output" name="get_output"></a> `get_output(context: graph_execution_context, index: u32, out_buffer: Pointer<u8>, out_buffer_max_size: buffer_size) -> (nn_errno, buffer_size)`
2792+
#### <a href="#get_output" name="get_output"></a> `get_output(context: graph_execution_context, index: u32, out_buffer: Pointer<u8>, out_buffer_max_size: buffer_size) -> Result<buffer_size, nn_errno>`
27702793
Extract the outputs after inference.
27712794

27722795
This should return an $nn_errno (TODO define) if the inference has not yet run.
@@ -2785,15 +2808,22 @@ tensor metadata (i.e. dimension, element type) but this should be added at some
27852808
- <a href="#get_output.out_buffer_max_size" name="get_output.out_buffer_max_size"></a> `out_buffer_max_size`: [`buffer_size`](#buffer_size)
27862809

27872810
##### Results
2788-
- <a href="#get_output.error" name="get_output.error"></a> `error`: [`nn_errno`](#nn_errno)
2789-
2790-
- <a href="#get_output.bytes_written" name="get_output.bytes_written"></a> `bytes_written`: [`buffer_size`](#buffer_size)
2811+
- <a href="#get_output.error" name="get_output.error"></a> `error`: `Result<buffer_size, nn_errno>`
27912812
The number of bytes of tensor data written to the `$out_buffer`.
27922813

2814+
###### Variant Layout
2815+
- size: 8
2816+
- align: 4
2817+
- tag_size: 4
2818+
###### Variant cases
2819+
- <a href="#get_output.error.ok" name="get_output.error.ok"></a> `ok`: [`buffer_size`](#buffer_size)
2820+
2821+
- <a href="#get_output.error.err" name="get_output.error.err"></a> `err`: [`nn_errno`](#nn_errno)
2822+
27932823

27942824
---
27952825

2796-
#### <a href="#compute" name="compute"></a> `compute(context: graph_execution_context) -> nn_errno`
2826+
#### <a href="#compute" name="compute"></a> `compute(context: graph_execution_context) -> Result<(), nn_errno>`
27972827
Compute the inference on the given inputs (see [`set_input`](#set_input)).
27982828

27992829
This should return an $nn_errno (TODO define) if the inputs are not all defined.
@@ -2802,5 +2832,14 @@ This should return an $nn_errno (TODO define) if the inputs are not all defined.
28022832
- <a href="#compute.context" name="compute.context"></a> `context`: [`graph_execution_context`](#graph_execution_context)
28032833

28042834
##### Results
2805-
- <a href="#compute.error" name="compute.error"></a> `error`: [`nn_errno`](#nn_errno)
2835+
- <a href="#compute.error" name="compute.error"></a> `error`: `Result<(), nn_errno>`
2836+
2837+
###### Variant Layout
2838+
- size: 8
2839+
- align: 4
2840+
- tag_size: 4
2841+
###### Variant cases
2842+
- <a href="#compute.error.ok" name="compute.error.ok"></a> `ok`
2843+
2844+
- <a href="#compute.error.err" name="compute.error.err"></a> `err`: [`nn_errno`](#nn_errno)
28062845

phases/ephemeral/witx/wasi_ephemeral_nn.witx

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
;;; Error codes returned by functions in this API. This is prefixed to avoid conflicts with the `$errno` in
1616
;;; `typenames.witx`.
1717
(typename $nn_errno
18-
(enum u16
18+
(enum (@witx tag u16)
1919
;;; No error occurred.
2020
$success
2121
;;; Caller module passed an invalid argument.
@@ -31,11 +31,11 @@
3131
;;;
3232
;;; The array length matches the tensor rank and each element in the array
3333
;;; describes the size of each dimension.
34-
(typename $tensor_dimensions (array u32))
34+
(typename $tensor_dimensions (list u32))
3535

3636
;;; The type of the elements in a tensor.
3737
(typename $tensor_type
38-
(enum u8
38+
(enum (@witx tag u8)
3939
$f16
4040
$f32
4141
$u8
@@ -50,11 +50,11 @@
5050
;;; tensor with 4-byte f32 elements would have a data array of length 16). Naturally, this representation requires
5151
;;; some knowledge of how to lay out data in memory--e.g. using row-major ordering--and could perhaps be improved
5252
;;; by future witx features (TODO).
53-
(typename $tensor_data (array u8))
53+
(typename $tensor_data (list u8))
5454

5555
;;; A tensor.
5656
(typename $tensor
57-
(struct
57+
(record
5858
;;; Describe the size of the tensor (e.g. 2x2x2x2 -> [2, 2, 2, 2]). To represent a tensor containing a single value,
5959
;;; use `[1]` for the tensor dimensions.
6060
(field $dimensions $tensor_dimensions)
@@ -69,24 +69,24 @@
6969

7070
;;; The graph initialization data. This consists of an array of buffers because implementing backends may encode their
7171
;;; graph IR in parts (e.g. OpenVINO stores its IR and weights separately).
72-
(typename $graph_builder (array u8))
73-
(typename $graph_builder_array (array $graph_builder))
72+
(typename $graph_builder (list u8))
73+
(typename $graph_builder_array (list $graph_builder))
7474

7575
;;; An execution graph for performing inference (i.e. a model).
7676
(typename $graph (handle))
7777

7878
;;; Describes the encoding of the graph. This allows the API to be implemented by various backends that encode (i.e.
7979
;;; serialize) their graph IR differently.
8080
(typename $graph_encoding
81-
(enum u8
81+
(enum (@witx tag u8)
8282
;;; TODO document buffer order
8383
$openvino
8484
)
8585
)
8686

8787
;;; Define where the graph should be executed.
8888
(typename $execution_target
89-
(enum u8
89+
(enum (@witx tag u8)
9090
$cpu
9191
$gpu
9292
$tpu
@@ -113,8 +113,7 @@
113113
;;; Where to execute the graph.
114114
(param $target $execution_target)
115115

116-
(result $error $nn_errno)
117-
(result $graph $graph)
116+
(result $error (expected $graph (error $nn_errno)))
118117
)
119118

120119
;;; TODO Functions like `describe_graph_inputs` and `describe_graph_outputs` (returning
@@ -124,8 +123,7 @@
124123
;;; TODO this may need to accept flags that might affect the compilation or execution of the graph.
125124
(@interface func (export "init_execution_context")
126125
(param $graph $graph)
127-
(result $error $nn_errno)
128-
(result $context $graph_execution_context)
126+
(result $error (expected $graph_execution_context (error $nn_errno)))
129127
)
130128

131129
;;; Define the inputs to use for inference.
@@ -138,7 +136,7 @@
138136
;;; The tensor to set as the input.
139137
(param $tensor $tensor)
140138

141-
(result $error $nn_errno)
139+
(result $error (expected (error $nn_errno)))
142140
)
143141

144142
;;; Extract the outputs after inference.
@@ -154,16 +152,15 @@
154152
(param $out_buffer (@witx pointer u8))
155153
(param $out_buffer_max_size $buffer_size)
156154

157-
(result $error $nn_errno)
158155
;;; The number of bytes of tensor data written to the `$out_buffer`.
159-
(result $bytes_written $buffer_size)
156+
(result $error (expected $buffer_size (error $nn_errno)))
160157
)
161158

162159
;;; Compute the inference on the given inputs (see `set_input`).
163160
;;;
164161
;;; This should return an $nn_errno (TODO define) if the inputs are not all defined.
165162
(@interface func (export "compute")
166163
(param $context $graph_execution_context)
167-
(result $error $nn_errno)
164+
(result $error (expected (error $nn_errno)))
168165
)
169166
)

tools/witx/tests/wasi-docs.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ fn validate_docs() {
99
witx::phases::ephemeral().unwrap(),
1010
witx::phases::old::snapshot_0().unwrap(),
1111
] {
12-
let doc = witx::load(&phase).unwrap_or_else(|e| panic!("failed to parse: {}", e));
12+
let doc = witx::load(&phase).unwrap_or_else(|e| panic!("failed to parse: {:?}", e));
1313
diff_against_filesystem(&doc.to_md(), &witx::phases::docs_path(&phase));
1414
}
1515
}

tools/witx/tests/witxt/wasi.witxt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,10 @@
2424
(witx
2525
(load
2626
"../../../../phases/ephemeral/witx/wasi_ephemeral_fd.witx"))
27+
28+
;; wasi-nn should work
29+
(witx
30+
(load
31+
"../../../../phases/ephemeral/witx/wasi_ephemeral_nn.witx"
32+
)
33+
)

0 commit comments

Comments
 (0)