diff options
Diffstat (limited to 'emulator/opengl/host/tools/emugen/README')
| -rw-r--r-- | emulator/opengl/host/tools/emugen/README | 332 |
1 files changed, 0 insertions, 332 deletions
diff --git a/emulator/opengl/host/tools/emugen/README b/emulator/opengl/host/tools/emugen/README deleted file mode 100644 index 0fe85f9..0000000 --- a/emulator/opengl/host/tools/emugen/README +++ /dev/null @@ -1,332 +0,0 @@ -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 - - |