docs: Document to_ptr protocol attribute

Signed-off-by: Frediano Ziglio <fziglio@redhat.com>
Acked-by: Snir Sheriber <ssheribe@redhat.com>

1 files changed, 24 insertions, 1 deletions

diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
index daab7f2..97beea7 100644
--- a/docs/spice_protocol.txt
+++ b/docs/spice_protocol.txt
@@ -365,7 +365,30 @@ the attribute was attached to a `len`-sized array).
 to_ptr
 ~~~~~~
 
-TODO
+This specifies that the corresponding C structure field contains a pointer to
+the data. On marshalling the pointer is used, on demarshalling the data is
+allocated in the memory block that holds the returned structure.
+The type of this field must be a structure.
+
+Example:
+
+    struct test {
+        uint16 num;
+    };
+
+    struct msg {
+        test ptr @to_ptr;
+    };
+
+Output C structure:
+
+    struct test {
+        uint16_t num;
+    };
+
+    struct msg {
+        struct test *ptr;
+    };
 
 nocopy
 ~~~~~~