android/android-emugl/host/tools/emugen/README

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