debug/org.eclipse.ptp.debug.sdm/libaif/INTERNAL

Internal documentation for the aif library.

AIF stands for "architecture-independent form".  Any data structure in any
language should be convertable to an AIF.  The AIF may be safely shipped from
machine to machine and converted back to an equivalent data structure.

An AIF is a struct with fields for the format-descriptor string (fds) and the
data (with explicit length).  The fds uses characters to indicate the type.
All bytes are represented in the data by two hex characters, representing upper
nibble then lower nibble.  The characters and formats have changed over time.
This is the currently operative list:

address: aN
	- Represents an address value
	- N is a single digit specifying the number of bytes of data

aggregate: {ID|N1=T1,...; N2=T2,...; N3=T3,...; N4=T4,...}
	- Used for struct and class types
	- ID is an optional name for the aggregate
	- Nn is the name of the field
	- Tn is a format string representing the type of the field
	- The type specifier is divided into four sections separated by ";"
	  - The first section is used to store public access fields (eg: N1)
	  - The second section is used to store protected access fields (eg: N2)
	  - The third section is used to store private access fields (eg: N3)
	  - The fourth section is used to store package access fields (eg: N4)
	- Structures only supply fields in the public section
	  
array: [R]T
	- R is a range indicating low and high bounds. If R is empty then 
	  this is a 0 element array.
	- T is a format string representing the base type
	- Multi-dimension arrays are represented as an array of base type array
	- Itself uses 0 bytes of data, but the components may use data
		
boolean: bN
	- Represents a true/false value
	- N is a single digit specifying the number of bytes of data
	- The data for a true value is non-zero 
	- The data for a false value is 0

character: c
	- Represents a single character
	- The data size is a single byte
	- Characters are always unsigned

C-style string: paN
	- aN is an address type
	- The first N bytes of data are the address value
	- The next 2 bytes of the data indicate the length (more significant 
	  byte first) of the string in bytes.  These bytes follow immediately.
	- There is no null included in the string
	
enumeration: <ID|S1=V1,S2=V2,...>isN
	- ID is an optional name for the type
	- Sn=Vn are name/value tuples where Sn is the name of the 
	  enumerated value and Vn is the value of the enumeration. 
	- The value of the enumeration is an integer whose type 
	  is "isN" (signed integer of length N bytes)
	  
floating: fN
	- Represents a floating point value of arbitrary length
	- N is a single digit specifying the number of bytes of data

function: &A1,A2,.../T
	- Represents a function that returns type T 
	- A1, A2, ... are the types of each formal parameter
	- Data consists of a null-terminated string containing 
	  the name of the function
	  
integer: i(s|u)N
	- Represents a signed or unsigned integer value of arbitrary length
	- s means signed; u means unsigned
	- N is a single digit specifying the number of bytes of data

named component: %N/T
	- N is a number
	- T is a format string representing the component
	- Uses 0 bytes of data
	
pointer: ^aNT
	- aN is an address type
	- T is the type of the pointer target (possibly of > form)
	- The first byte in the data is a type, with value:
		0 to indicate a null pointer
		1 to indicate a normal value
		2 to indicate a normal value that will be referred to later.  
		3 to indicate that the value is a circular reference
		4 to indicate an invalid pointer value
	- A null pointer (type 0) has no data.
	- Data for a normal pointer (type 1) comprises N bytes of the
	  address value, followed by the target.
	- Data for a named pointer (type 2) comprises a name, N bytes of the
	  address value, then the target data.
	- Data for a reference pointer (type 3) comprises a name followed by
	  N bytes of the address value.
	- Data for an invalid pointer (type 4) comprises N bytes of
	  the address value.
	- Names are 4 byte unsigned integers

range: rL,NT
	- IF N>0, represents a range from L to L+N-1, inclusive
	- If N==0 the range is empty
	- L and N are integer types specified by T

reference to named component: >N/
	- Used in circular linked types to make representation finite
	- N is a number
	- Uses 0 bytes of data
	
string: s
	- Represents an arbitrary length character string
	- The first 2 bytes of the data indicate the length (more significant 
	  byte first) of the string in bytes.  These bytes follow immediately

union: (ID|N1=F1,N2=F2,...)
	- Similar to a structure, but all fields start at the same address
	- ID is the identifier for the union, it is optional
	- Nn is the name of the field
	- Fn is a format string representing the field
	- The size of the union will be max(sizeof(F1),...sizeof(FN))

void: vN
	- Represents a void type
	- N is the number of bytes of data

ZPL region: zNT
	- Represents a ZPL region of rank N. 
	- Type T is the type of the data describing
	  the bounds of each rank and must be an integer type. The data 
	  consists of pairs of integers describing the lower and upper
	  bounds of each rank respectively

invalid: ?n? 
	- n is an integer code (currently only 0)
	- 0 bytes of data

The construction routines allow a client to build most reasonable AIFs, but in
building data-circular AIFs requires using lower-level access.  For arrays, it
is necessary to generate the data portion of the array using low-level
mechanisms before using our constructors to make the final AIF.