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.
The file
extension should be as required by the library compiler e.g. .s79.
As Elves will list the functions of the selected library, 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. Out for Output). The Library name also contains the 3 digits
for the
peripheral plus the numeric part of the device name (e.g. LibDac7024).
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 brackets)
by the parameter
types and names and finaly a closing semicolon (;).
The function end is marked by 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 a line for each parameter giving
details of possible
values. Below are typical lines.
;iChan:{0,1,2,3}
;iValue:{}
;iAddr:{0-0xf7ff}
;
iFormat:{URT_68|URT_78|URT_STP2|URT_PE|URT_PODD|URT_PS|URT_BR}
The lines consist of a semicolon followed by the parameter name followed by a
colon.
This can be followed by empty braces if the user must type in a value for
this
parameter.
If the braces are filled by two values separated by " - " the
Elves will give
a warning if a value outside this range was entered.
If the braces are filled with a comma separated list of values then the
elves
will present this list to the user for ease of selection.
If the braces are filled with a list with " | " as separator the 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.
For these lists to be meaningful, the user must define the items in his source
code. Typically this will be done in a header file. For the ADI supplied
functions this is done in the file adi7024c.h.
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.