1 files changed, 106 insertions, 0 deletions
diff --git a/chapters/variable.adoc b/chapters/variable.adoc
new file mode 100644
index 0000000..1f7da51
--- /dev/null
+++ b/chapters/variable.adoc
@@ -0,0 +1,106 @@
+//
+// This confidential and proprietary software may be used only as
+// authorised by a licensing agreement from ARM Limited
+// (C) COPYRIGHT 2023 ARM Limited
+// ALL RIGHTS RESERVED
+// The entire notice above must be reproduced on all authorised
+// copies and copies may only be made to the extent permitted
+// by a licensing agreement from ARM Limited.
+
+=== Variable Operators
+
+TOSA implements three variable operators for expressing persistent mutable values across multiple TOSA graph invocations.
+
+==== VARIABLE
+
+Defines a new TOSA variable.
+This is a persistent mutable value across multiple TOSA graph invocations.
+Modifications are expressed using read/write semantics.
+
+include::{generated}/operators/VARIABLE.adoc[]
+
+[source,c++]
+----
+
+tensor_t var_tensor = variable_tensor_lookup(uid);
+
+// Invocation for the first time
+if (var_tensor == NULL) {
+  // Allocate the persistent mutable memory for the variable tensor
+  tensor_t var_tensor = variable_tensor_allocate<var_t>(var_shape, uid);
+
+  if (initial_value != NULL) {
+    REQUIRE(var_t == in_t);
+    REQUIRE(var_shape == shape);
+    for_each (index in shape) {
+      // Copy data from initial_value to var_tensor
+      in_t value = tensor_read<in_t>(initial_value, shape, index);
+      tensor_write<in_t>(var_tensor.data, var_shape, index, value);
+    }
+    var_tensor.is_written = true;
+  }
+} else { // Variable tensor has already been declared
+  // It's invalid to declare the second variable with the same uid in a single graph execution,
+  REQUIRE(!var_tensor.seen);
+}
+
+var_tensor.seen = true;
+
+----
+
+==== VARIABLE_WRITE
+
+Assigns a value to the pseudo-buffer resource holding a persistent mutable tensor.
+
+include::{generated}/operators/VARIABLE_WRITE.adoc[]
+
+[source,c++]
+----
+
+tensor_t. variable_tensor = variable_tensor_lookup(uid);
+// Check this variable tensor has been declared
+REQUIRE(variable_tensor);
+// The tensor has to be seen before to be written to
+// The seen variable is cleared before each graph execution and set in declaration
+REQUIRE(variable_tensor.seen);
+//  Input tensor's shape and variable_tensor's shape have to match
+REQUIRE(variable_tensor.shape == shape);
+//  Input tensor's shape and variable_tensor's type have to match
+REQUIRE(variable_tensor.type == in_t);
+
+for_each (index in shape) {
+    // Write data from the input to the pseudo-buffer resource
+    in_t value = tensor_read<in_t>(input1, shape, index);
+    tensor_write<tensor_t>(variable_tensor.data, variable_tensor.shape, index, value);
+}
+
+variable_tensor.is_written = true;
+
+----
+
+==== VARIABLE_READ
+
+Reads the value from a pseudo-buffer resource holding a persistent mutable tensor.
+
+include::{generated}/operators/VARIABLE_READ.adoc[]
+
+[source,c++]
+----
+
+tensor_t variable_tensor = variable_tensor_lookup(uid);
+// Check this variable tensor has been decalred
+REQUIRE(variable_tensor != NULL);
+// Check this variable tensor has been written
+REQUIRE(variable_tensor.is_written);
+// Output tensor's shape and variable_tensor's shape have to match
+REQUIRE(variable_tensor.shape == shape);
+//  Output tensor's shape and variable_tensor's type have to match
+REQUIRE(variable_tensor.type == out_t);
+
+for_each (index in shape) {
+    // Read data from pseudo-buffer resource to the output
+    out_t value = tensor_read<tensor_t>(variable_tensor.data, variable_tensor.shape, index);
+    tensor_write<out_t>(input1, shape, index, value);
+}
+
+----