ArmElvesRulesBody

Elves Code Rules

In order for Elves to function the library source code must follow certain rules as described below. As will be seen these rules do not change the code generated and can easily be followed by the user. Thus the system is useful for libraries supplied by vendors as well as those generated by users.

Files.

The library source code can be in any folder of the users system.

Each function is contained in a separate file from which libraries are built containing many functions. Related functions should be combined in one library. For the peripheral libraries this is achieved by having a separate library for each peripheral. In these libraries every function name starts with 3 digits indicating the peripheral (e.g. Dac) followed by 2 to 4 digits indicating the specific function (e.g. DacOut( ) for DAC Output). The Library name also contains the 3 digits for the peripheral (e.g. LibDac.r79). Associated with each library must be a .h file to indicate to Elves which functions belong to which library.

This same .h file should be in a #include in your source code.

Function Delimiters.

Within the libraries each function has to have specific start and end identifiers. The start of a function is a line of the following format:

; C Function prototype: int DacOut(int iChan, int iValue);

The start must be exactly "; C Function prototype: " as shown. Then follows the function return type and the function name followed (in braces) by the parameter types and names and finaly a closing semicolon (;).

The function prototype in the associated .h file must match this exactly.

The function end is marked by the end of file or a line of the following format:

                 ENDMOD  DacOut

The first word must be ENDMOD which must be followed by the function name.

The information between the two delimiters will be shown to the user when he has selected the function.

Parameter Details.

Directly after the start delimiter must be one line for each parameter giving details of possible values. Below are typical lines.

;iValue:{}
;iAddr:{0-0xf7ff}
;iChan:{0,1,2,3}
;iFormat:{URT_68|URT_78|URT_STP2|URT_PE|URT_PODD|URT_PS|URT_BR}
;iExe:{PlaTool.exe}

The lines consist of a semicolon followed by the parameter name followed by a colon followed by a pair of braces with the following possible contents with the indicated effects:

No contents -- the user must type in a value for this parameter.
Two numeric values separated by "-" -- Elves will give a warning if a value outside this range was entered.
A comma separated list of values -- Elves will present this list to the user for ease of selecting a value.
A list with "|" as separator -- Elves will put this list in a multiselection list box for the user to select multiple items. This is mostly used to set individual bits of a word.
An executable application -- Elves will launch the application if its executable is in the same folder as the library.

For these lists to be meaningful, numeric constants must be defined. Typically this will be done in the same header file in which the function prototypes are defined.

The above scheme is naturally applicable to assembly code but can just as well be used for libraries written in C. Just include the details described above inside comment blocks using the /* */ comment delimiters.

The Elves Dialog description shows a typical example. The exact details will vary depending on the number and types of parameters involved.