[Spice-commits] 2 commits - docs/spice_protocol.txt

[GitLab Mirror]

 docs/spice_protocol.txt |   41 ++++++++++++++++++++++++++++++++---------
 1 file changed, 32 insertions(+), 9 deletions(-)

New commits:
commit aee2b91fe278fa0bdd6e8274119e37efae8323fd
Author: Frediano Ziglio <fziglio at redhat.com>
Date:   Wed Nov 21 09:12:26 2018 +0000

    docs: Document to_ptr protocol attribute
    
    Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
    Acked-by: Snir Sheriber <ssheribe at redhat.com>

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
 ~~~~~~
commit 5b6878e72c19dd032bc3e730bcbf7872a37e1826
Author: Frediano Ziglio <fziglio at redhat.com>
Date:   Wed Nov 21 09:12:08 2018 +0000

    docs: Fix typos and grammar
    
    Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
    Acked-by: Snir Sheriber <ssheribe at redhat.com>

diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
index b205743..daab7f2 100644
--- a/docs/spice_protocol.txt
+++ b/docs/spice_protocol.txt
@@ -65,7 +65,7 @@ Enumerations and flags
 ----------------------
 
 It's possible to specify enumerations and flags. The difference is that flags are defined as 2 power
-values and can combined. Enumerations and flags must have a size (`8`, `16` or `32`) specified.
+values and can be combined. Enumerations and flags must have a size (`8`, `16` or `32`) specified.
 
     enum ::= <enum_type> "{" [ <enumflag_items> ] "}" <attributes> ";" ;
     flag ::= <flag_type> "{" [ <enumflag_items> ] "}" <attributes> ";" ;
@@ -121,7 +121,7 @@ to handle not using autogenerated code and also use more space on the network.
 Arrays
 ------
 
-As seen above the easiest way to define an array size is specifiying a constant value.
+As seen above the easiest way to define an array size is specifying a constant value.
 However there are multiple way to specify the size
 
     array_size ::= <integer>|<identifier>|""|<array_size_image>|<array_size_bytes>|<array_size_cstring> ;
@@ -137,7 +137,7 @@ in another field, for instance
     int8 name[name_len];
 
 allows to put a name of `name_len` len.
-The empty value tell that the array will end when the containing message end so if we have
+The empty value tells that the array will end when the containing message end so if we have
 
     int8 name[];
 
@@ -173,7 +173,7 @@ we'll have the `foo` name. Note that the field does not need to end the message
 Structures
 ----------
 
-The simpler coumpound type is the structure. As in C is defined as a list of fields (any variable or swicth).
+The simplest coumpound type is the structure. As in C is defined as a list of fields (any variable or switch).
 But as a protocol definition there are no alignment or padding and every field (beside pointer values) follow each other.
 
     struct ::= "struct" <identifier> "{" [ <fields> ] "}" <attributes> ";" ;
@@ -190,7 +190,7 @@ Example:
 Messages
 --------
 
-Messages have the same syntax of structure (beside `message`) with the different that they can
+Messages have the same syntax of structure (beside `message`) with the difference that they can
 be used directly inside channels.
 
     message ::= "message" <identifier> "{" [ <fields> ] "}" <attributes> ";" ;
@@ -266,7 +266,7 @@ Attributes
 ----------
 
 As you probably noted attributed can be specified for lot of definitions.
-They allow to change code generated or specific contraints to the protocol.
+They allow to change code generated or specific constraints of the protocol.
 
     attributes ::= ""|<attributes><attribute>|<attribute> ;
     attribute ::= <attribute_name> [ "(" <attribute_values> ")" ] ;
@@ -302,7 +302,7 @@ will be marshalled into a C structure like
 prefix
 ~~~~~~
 
-This attribute allow to specify the prefix used for generated enumerations (both
+This attribute allows to specify the prefix used for generated enumerations (both
 protocol enumerations and flags generate C enumerations). By default the enumeration
 will use upper case of the enum/flag name prefixed with `SPICE_` and followed by item so
 
@@ -339,7 +339,7 @@ will generate
 end
 ~~~
 
-This attribute specify that the data will be appended/embedded in the final C structure.
+This attribute specifies that the data will be appended/embedded in the final C structure.
 
 Example: