Commit f60d2c16 authored by Sven Gestegård Robertz's avatar Sven Gestegård Robertz
Browse files

more tech_report cleanup

parent 598b1368
......@@ -2,8 +2,8 @@ aspect LabCommTokens {
public static final int ASTNode.LABCOMM_VERSION = 0x01;
public static final int ASTNode.LABCOMM_SAMPLE_DEF = 0x02; // The flat signature
public static final int ASTNode.LABCOMM_SAMPLE_REF = 0x03;
public static final int ASTNode.LABCOMM_TYPE_DEF = 0x04; // and type declarations, hierarchically
public static final int ASTNode.LABCOMM_TYPE_DEF = 0x03; // and type declarations, hierarchically
public static final int ASTNode.LABCOMM_TYPE_BINDING=0x04;
public static final int ASTNode.LABCOMM_ARRAY = 0x10;
public static final int ASTNode.LABCOMM_STRUCT = 0x11;
......@@ -285,9 +285,9 @@ But
With the following `` file:
and this \verb+example_encoder.c+ file
......@@ -330,6 +330,95 @@ i.e.,
<sample_data> <user_id: 40> <length: 14> <packed_sample_data>
\section{Technical details}
TODO: better section title
\subsection{Type and sample declarations}
LabComm has two constructs for declaring sample types, \emph{sample
declarations} and \emph{type declarations}. A sample declaration is used
for the concrete sample types that may be transmitted, and is always
encoded as a \emph{flattened} signature. That means that a sample
containing user types, like
typedef struct {
int x;
int y;
} point;
sample struct {
point start;
point end;
} line;
is flattened to
sample struct {
struct {
int x;
int y;
} start;
struct {
int x;
int y;
} end;
} line;
Sample declarations are always sent, and is the fundamental identity of
a type in LabComm.
Type declarations is the hierarchical counterpart to sample
declarations: here, fields of user types are encoded as a reference to
the type instead of being flattened. As the flattened sample decl is the
fundamental identity of a type, type declarations can be regarded as
meta-data, describing the internal structure of a sample. They are
intended to be read by higher-level software and human system developers
and integrators.
Sample declarations and type declarations have separate name-spaces in
the sense that the numbers assigned to them by a labcomm encoder
come from two independent number series. To identify which
\verb+TYPE_DECL+ a particular \verb+SAMPLE_DECL+ corresponds to, the
\verb+TYPE_BINDING+ packet is used.
The labcomm declaration
can be is encoded as
TYPE_DECL 0x40 "coord" <int> val
TYPE_DECL 0x41 "point" <struct> <2 fields>
"x" <type: 0x40>
"y" <type: 0x40>
TYPE_DECL 0x42 "line" <struct> <2 fields>
"start" <type: 0x41>
"end" <type: 0x41>
TYPE_DECL 0x43 "foo" <struct> <3 fields>
"a" <int>
"b" <int>
"c" <boolean>
TYPE_DECL 0x44 "twolines" <struct> <3 fields>
"l1" <type:0x42>
"l2" <type:0x42>
"f" <type:0x43>
SAMPLE_DECL 0x40 "twolines" <flat signature>
TYPE_BINDING 0x40 0x44
Note that the id 0x40 is used both for the \verb+TYPE_DECL+ of
\verb+coord+ and the \verb+SAMPLE_DECL+ of \verb+twoline+, and that the
\verb+TYPE_BINDING+ binds the sample id \verb+0x40+ to the type id
The labcomm language is more expressive than its target languages regarding data types.
......@@ -400,9 +489,9 @@ follow. The sequence of chunks are sent with the least significant chunk
The built-in data types are encoded as follows:
||Type ||Encoding/Size ||
||boolean || 8 bits ||
||byte || 8 bits ||
||short || 16 bits ||
......@@ -415,20 +504,27 @@ The built-in data types are encoded as follows:
|| || followed by encoded elements ||
||struct || concatenation of encoding of each element ||
|| || in declaration order ||
\subsection{Protocol grammar}
<packet> := ( <version> | <type_decl> | <sample_decl> | <sample_data> )*
<version> := 0x01 <length> <string>
<sample_def> := 0x02 <length> <user_id> <string> <type>
<type_def> := 0x03 <length> <user_id> <string> <type>
<packet> := <id> <length> ( <version> |
<type_decl> |
<sample_decl> |
<type_binding> |
<sample_data> )
<version> := <string>
<sample_def> := <sample_id> <string> <type>
<type_def> := <type_id> <string> <type>
<type_binding> := <sample_id> <type_id>
<user_id> := 0x40..0xffffffff
<sample_id> : <user_id>
<type_id> : <user_id>
<string> := <string_length> <char>*
<string_length> := 0x00..0xffffffff
<string_length>:= 0x00..0xffffffff
<char> := any UTF-8 char
<type> := <length> ( <basic_type> | <user_id> | <array_decl> | <struct_decl> )
<type> := <length> ( <basic_type> | <array_decl> | <struct_decl> | <type_id> )
<basic_type> := ( <boolean_type> | <byte_type> | <short_type> |
<integer_type> | <long_type> | <float_type> |
<double_type> | <string_type> )
......@@ -448,8 +544,20 @@ The built-in data types are encoded as follows:
<struct_decl> := 0x11 <number_of_fields> <field>*
<number_of_fields> := 0x00..0xffffffff
<field> := <string> <type>
<sample_data> := <user_id> <packed_sample_data>
<packed_sample_data> := is sent in network order, encoded :
<sample_data> := packed sample data sent in network order, with
primitive type elements encoded according to
the sizes above
where the \verb+<id>+ in \verb+<packet>+ signals the type of payload,
and may be either a \verb+<sample_id>+ or a system packet id.
The labcomm sytem packet ids are:
version: 0x01
sample_decl: 0x02
type_decl: 0x03
type_binding: 0x04
Note that since the signature transmitted in a \verb+<sample_def>+ is
flattened, the \verb+<type>+ transmitted in a \verb+<sample_def>+ may
not contain any \verb+<type_id>+ fields.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment