--- /dev/null
+Introduction:
+-------------
+The emugen tool is a tool to generate a wire protocol implementation
+based on provided API. The tool generates c++ encoder code that takes
+API calls and encodes them into the wire and decoder code that decodes
+the wire stream and calls server matching API.
+The emugen tool includes additional functionality that enables to
+generate an wrapper library. The wrapper library provides entry points
+for the specified API, where each entry routes the call via a dispatch
+table. The dispatch table may be initialized as required by a specific application.
+
+The following paragraphs includes the following:
+ * Wire Protocol Description
+ * Input files description & format
+ * Generated code description.
+
+
+Note: In this document, the caller is referred to as Encoder or Client
+and the callee is referred to as the Decoder or Server. These terms
+are used interchangeably by the context.
+
+
+
+Wire Protocol packet structure:
+-------------------------------
+A general Encoder->Decoder packet is structured as following:
+struct Packet {
+ unsigned int opcode;
+ unsigned int packet_len;
+ … parameter 1
+ … parameter 2
+};
+A general Decoder->Encoder reply is expected to be received in the
+context of the ‘call’ that triggered it, thus it includes the reply
+data only, with no context headers. In precise term terms, a reply
+packet will look like:
+
+struct {
+ ...// reply data
+};
+
+consider the following function call:
+int foo(int p1, short s1)
+will be encoded into :
+{
+ 101, // foo opcode
+ 14, // sizeof(opcode) + sizeof(packet_len) + sizeof(int) + sizeof(short)
+ p1, // 4 bytes
+ s1 // 2 bytes
+}
+
+Since ‘foo’ returns value, the caller is expected to read back the return packet from the server->client stream. The return value in this example is in thus the return packet is:
+{
+ int retval;
+}
+
+
+Pointer decoding:
+----------------
+The wire protocol also allows exchanging of pointer data
+(arrays). Pointers are defined with directions:
+
+ in : Data is sent from the caller to the calle
+ out: Data is sent from the callee to the caller
+ in_out: data is sent from the caller and return in place.
+
+‘in’ and ‘in_out’ encoded with their len:
+{
+ unsinged int pointer_data_len;
+ unsigned char data[pointer_data_len];… // pointer data
+}
+
+‘out’ pointers are encoded by data length only:
+{
+unsigned int pointer_data_len;
+}
+
+‘out’ and ‘in_out’ pointer’s data is returned in the return
+packet. For example, consider the following call:
+
+int foo(int n, int *ptr); // assume that ‘data’ is in_out pointer which contains ‘n’ ints
+
+The caller packet will have the following form:
+{
+ 101, // foo opcode
+ xx, sizeof(opcode) + sizeof(datalen) + sizeof(int) + sizeof(unsigned int) + n * sizeof(int);
+ n, // the n parameter
+ n * sizeof(int), // size of the data in ptr
+ … // n* sizeof(int) bytes
+}
+
+The return packet is;
+{
+ …. // n * sizeof(int) bytes of data return in ptr
+ retval // sizeof(int) - the return value of the function;
+}
+
+Endianess
+---------
+The Wire protocol is designed to impose minimum overhead on the client
+side. Thus, the data endianness that is sent across the wire is
+determined by the ‘client’ side. It is up to the server side to
+determine the client endianess and marshal the packets as required.
+
+
+
+Emugen input files - protocol specification
+-------------------------------------------
+The protocol generated by emugen consists of two input files:
+
+1. basename.in - A sepcification of the protocol RPC procedures. This
+part of the specification is expected to be generated automatically
+from c/c++ header files or similar.
+
+‘basename’ is the basename for the protocol and will be used to prefix
+the files that are generated for this protocol. A line in the .in
+file has the following format:
+
+[prefix](retvalType, FuncName, <param type> [param name],...)
+where
+ retvalType - The function return value type
+ FuncName - function name
+ <param type> mandatory parameter type
+ [param name] - optional parameter name
+Examples:
+GL_ENTRY(void, glVertex1f, float v)
+XXX(int *, foo, int n, float, short)
+XXX(void, glFlush, void)
+
+Note: Empty lines in the file are ignored. A line starts with # is a comment
+
+2. basename.attrib - Attributes information of the API.
+This file includes additional flags, pointers datalen information and
+global attributes of the protocol. For uptodate format of the file,
+please refer to the specification file in the project source
+tree. The format of the .attrib file is described below.
+
+3. basename.types - Types information
+
+This files describes the types that are described by the API. A type
+is defined as follows:
+<type name> <size in bits> <print format string> <is a pointer? true|false>
+where:
+<type name> is the name of the type as described in the API
+<size in bits> 0, 8, 16, 32 sizes are accepted
+<print format string> a string to format the value of the type, as
+acceted by printf(3)
+<is pointer?> true or false string species whether the type should be
+treated as a pointer.
+
+example:
+GLint 32 %d false
+GLint* 32 %p true
+GLptr 32 %p true
+
+Encoder generated code files
+----------------------------
+In order to generate the encoder files, one should run the ‘emugen’
+tool as follows:
+
+emugen -i <input directory> -E <encoder files output directory> <basename>
+where:
+ <input directory> containes the api specification files (basename.in + basename.attrib)
+ <encoder directory> - a directory name to generate the encoder output files
+ basename - The basename for the api.
+
+Assuming the basename is ‘api’, The following files are generated:
+
+api_opcodes.h - defines the protocol opcodes. The first opcode value
+is 0, unless defined otherwise in the .attrib file
+
+api_entry.cpp - defines entry points for the functions that are
+defined by the protocol. this File also includes a function call
+‘setContextAccessor(void *(*f)()). This function should be used to
+provide a callback function that is used by the functions to access
+the encoder context. For example, such callback could fetch the
+context from a Thread Local Storage (TLS) location.
+
+api_client_proc.h - type defintions for the protocol procedures.
+
+api_client_context.h - defines the client side dispatch table data
+structure that stores the encoding functions. This data structure also
+includes ‘accessors’ methods such that library user can override
+default entries for special case handling.
+
+api_client_context.cpp - defines an initialization function for
+dispatch table
+
+api_enc.h - This header file defines the encoder data strcuture. The
+encoder data structure inherits its functionality from the
+‘client_context’ class above and adds encoding and streaming
+functionality.
+
+api_enc.cpp - Encoder implementation.
+
+Decoder generated files
+-----------------------
+In order to generate the decoder files, one should run the ‘emugen’
+tool as follows:
+emugen -i <input directory> -D <decoder files output directory> basename
+where:
+ <input directory> containes the api specification files (basename.in + basename.attrib)
+ <decoder directory> - a directory name to generate the decoder output files
+ basename - The basename for the api.
+
+With resepct to the example above, Emugen will generate the following
+files:
+
+api_opcodes.h - Protocol opcodes
+
+api_server_proc.h - type definitions for the server side procedures
+
+api_server_context.h - dispatch table the decoder functions
+
+api_server_context.cpp - dispatch table initialization function
+api_dec.h - Decoder header file
+
+api_dec.cpp - Decoder implementation. In addtion, this file includes
+an intiailization function that uses a user provided callback to
+initialize the API server implementation. An example for such
+initialization is loading a set of functions from a shared library
+module.
+
+Wrapper generated files
+-----------------------
+In order to generate a wrapper library files, one should run the
+'emugen' tool as follows:
+
+emugen -i <input directory> -W <wrapper files output directory> basename
+where:
+ <input directory> containes the api specification files (basename.in + basename.attrib)
+ <wrapper directory> - a directory name to generate the wrapper output files
+ basename - The basename for the api.
+
+With resepct to the example above, Emugen will generate the following
+files:
+
+api_wrapper_proc.h - type definitions for the wrapper procedures
+
+api_wrapper_context.h - dispatch table the wrapper functions
+
+api_wrapper_context.cpp - dispatch table initialization function
+api_wrapper_entry.cpp - entry points for the API
+
+
+.attrib file format description:
+-------------------------------
+The .attrib file is an input file to emugen and is used to provide
+ additional information that is required for the code generation.
+The file format is as follows:
+
+a line that starts with # is ignored (comment)
+a empty line just whitespace of (" " "\t" "\n") is ignored.
+
+The file is divided into 'sections', each describes a specific API
+function call. A section starts with the name of the function in
+column 0.
+
+A section that starts with the reserved word 'GLOBAL' provides global
+attributes.
+
+below are few sections examples:
+
+GLOBAL
+ encoder_headers string.h kuku.h
+
+glVertex3fv
+ len data (size)
+glTexImage2D
+ len pixels (pixels == NULL? 0 : (format_pixel_size(internalformat) * width * height * type_size(type)))
+
+
+Global section flags description:
+
+base_opcode
+ set the base opcode value for this api
+ format: base_opcode 100
+
+encoder_headers
+ a list of headers that will be included in the encoder header file
+ format: encoder_headers <stdio.h> "kuku.h"
+
+client_context_headers
+ a list of headers that will be included in the client context header file
+ format: client_context_headers <stdio.h> "kuku.h"
+
+decoder_headers
+ a list of headers that will be included in the decoder header file
+ format: decoder_headers <stdio.h> "kuku.h"
+
+server_context_headers
+ a list of headers that will be included in the server context header file
+ format: server_context_headers <stdio.h> "kuku.h"
+
+
+Entry point flags description:
+
+ len
+ desciption : provide an expression to calcualte an expression data len
+ format: len <var name> <c expression that calcluates the data len>
+
+custom_pack
+ description: provide an expression to pack data into the stream.
+ format: custom_pack <var name> <c++ expression that pack data from var into the stream>
+ The stream is represented by a (unsigned char *)ptr. The expression may also refer
+ to other function parameters. In addition, the expression may refer to 'void *self' which
+ is the encoding context as provided by the caller.
+
+ dir
+ description : set a pointer direction (in - for data that goes
+ to the codec, out from data that returns from the codec.
+ format: dir <varname> <[in | out | inout]>
+
+ var_flag
+ description : set variable flags
+ format: var_flag <varname> < nullAllowed | isLarge | ... >
+
+ nullAllowed -> for pointer variables, indicates that NULL is a valid value
+ isLarge -> for pointer variables, indicates that the data should be sent without an intermediate copy
+
+ flag
+ description: set entry point flag;
+ format: flag < unsupported | ... >
+ supported flags are:
+ unsupported - The encoder side implementation is pointed to "unsuppored reporting function".
+ custom_decoder - The decoder is expected to be provided with
+ custom implementation. The call to the
+ deocder function includes a pointer to the
+ context
+ not_api - the function is not native gl api
+
+
Code Review / iec.git / blobdiff