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

[Frediano Ziglio]

 docs/spice_protocol.txt |   56 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 50 insertions(+), 6 deletions(-)

New commits:
commit e5a03766ec36ade3a1b6ea4711c3939fbebdb89b
Author: Frediano Ziglio <fziglio at redhat.com>
Date:   Tue Oct 18 10:20:24 2016 +0100

    Add protocol documentation for "channel" and "protocol"
    
    Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
    Acked-by: Victor Toso <victortoso at redhat.com>

diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
index c2f2dbe..53700db 100644
--- a/docs/spice_protocol.txt
+++ b/docs/spice_protocol.txt
@@ -216,7 +216,51 @@ Example:
 Channels
 --------
 
-TODO
+    channel ::= "channel" <identifier> [ ":" <identifier> ] "{" <channel_messages> "}" <attributes> ";" ;
+    channel_messages ::= <channel_message>|<channel_messages><channel_message> ;
+    channel_message ::= "server:" | "client:" | "message" <identifier> [ "=" <integer> ] ;
+
+Example:
+
+    channel ExampleChannel {
+    server:
+       message {
+          uint32 dummy;
+       } Dummy;
+    };
+
+Note that every message is associated with a number which is used in the protocol.
+The assignment work in a similar way to enumeration in C beside first message is
+assigned 1 value and not 0. So first message (if no integer is specified) is assigned
+1, second 2 and so on.
+
+`server:` or `client:` specify the direction of messages following, `server` specify
+messages from server while `client` from client. If not specified is assumed from
+server.
+
+For each channel you can specify a parent channel. Derived channel inherite all
+messages specified in the parent.
+Note that messages from parent can be overrided by derived channels.
+
+Protocol
+--------
+
+    protocol ::= "protocol" <identifier> "{" <protocol_channels> "}" ";" ;
+    protocol_channels ::= <protocol_channel>|<protocol_channels><protocol_channel> ;
+    protocol_channel ::= <identifier> <identifier> [ "=" <integer> ] ";" ;
+
+Example:
+
+    protocol Example {
+        ExampleChannel first = 1001;
+    };
+
+Protocol specify the list of channel supported. Channel have an associated number
+assigned in a similar way of channels (incremented from one to the next with
+first starting from 0 if not specified).
+
+*NOTE*: Due to the way currently code is generate you should use
+small numbers.
 
 Attributes
 ----------
commit ced5c559256bd44654aafe6ff950cc641c91475e
Author: Frediano Ziglio <fziglio at redhat.com>
Date:   Tue Oct 18 10:20:00 2016 +0100

    Fix BNF notation in documentation
    
    Definition names have no angular brackets.
    
    Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
    Acked-by: Victor Toso <victortoso at redhat.com>

diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
index 13506f1..c2f2dbe 100644
--- a/docs/spice_protocol.txt
+++ b/docs/spice_protocol.txt
@@ -176,9 +176,9 @@ Structures
 The simpler coumpound type is the structure. As in C is defined as a list of fields (any variable or swicth).
 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> ";" ;
-    <fields> ::= <field>|<fields><field> ;
-    <field> ::= <variable>|<switch>
+    struct ::= "struct" <identifier> "{" [ <fields> ] "}" <attributes> ";" ;
+    fields ::= <field>|<fields><field> ;
+    field ::= <variable>|<switch>
 
 Example:
 
@@ -193,7 +193,7 @@ Messages
 Messages have the same syntax of structure (beside `message`) with the different that they can
 be used directly inside channels.
 
-    <message> ::= "message" <identifier> "{" [ <fields> ] "}" <attributes> ";" ;
+    message ::= "message" <identifier> "{" [ <fields> ] "}" <attributes> ";" ;
 
 Switches
 --------
@@ -205,7 +205,7 @@ Type definitions
 
 Like C type definition allow to short types defining new ones.
 
-    <typedef> ::= "typedef" <identifier> <type>`<attributes> ;
+    typedef ::= "typedef" <identifier> <type> <attributes> ;
 
 note that unlike C name came before the type.