Appendix 3: Intgen

Previous Section | Next Section | Table of Contents | Index | Title Page

Appendix 3: Intgen

This documentation describes Intgen, a program for generating XLISP to C interfaces. Intgen works by scanning .h files with special comments in them. Intgen builds stubs that implement XLISP SUBR's. When the SUBR is called, arguments are type-checked and passed to the C routine declared in the .h file. Results are converted into the appropriate XLISP type and returned to the calling XLISP function. Intgen lets you add C functions into the XLISP environment with very little effort.

The interface generator will take as command-line input:

the name of the .c file to generate (do not include the .c extension; e.g. write xlexten, not xlexten.c);
a list of .h files.

Alternatively, the command line may specify a command file from which to read file names. The command file name should be preceded by "@", for example:

intgen @sndfns.cl

reads sndfns.cl to get the command-line input. Only one level of indirection is allowed.

The output is:

a single .c file with one SUBR defined for each designated routine in a .h file.
a .h file that declares each new C routine. E.g. if the .c file is named xlexten.c, this file will be named xlextendefs.h;
a .h file that extends the SUBR table used by Xlisp. E.g. if the .c file is named xlexten.c, then this file is named xlextenptrs.h;
a .lsp file with lisp initialization expressions copied from the .h files. This file is only generated if at least one initialization expression is encountered.

For example, the command line

intgen seint ~setypes.h access.h

generates the file seint.c, using declarations in setypes.h and access.h. Normally, the .h files are included by the generated file using #include commands. A ~ before a file means do not include the .h file. (This may be useful if you extend xlisp.h, which will be included anyway). Also generated will be setintdefs.h and seintptrs.h.

Extending Xlisp

Any number of .h files may be named on the command line to Intgen, and Intgen will make a single .c file with interface routines for all of the .h files. On the other hand, it is not necessary to put all of the extensions to Xlisp into a single interface file. For example, you can run Intgen once to build interfaces to window manager routines, and again to build interfaces to a new data type. Both interfaces can be linked into Xlisp.

To use the generated files, you must compile the .c files and link them with all of the standard Xlisp object files. In addition, you must edit the file localdefs.h to contain an #include for each *defs.h file, and edit the file localptrs.h to include each *ptrs.h file. For example, suppose you run Intgen to build soundint.c, fugueint.c, and tableint.c. You would then edit localdefs.h to contain the following:

#include "soundintdefs.h"
#include "fugueintdefs.h"
#include "tableintdefs.h"

and edit localptrs.h to contain:

#include "soundintptrs.h"
#include "fugueintptrs.h"
#include "tableintptrs.h"

These localdefs.h and localptrs.h files are in turn included by xlftab.c which is where Xlisp builds a table of SUBRs.

To summarize, building an interface requires just a few simple steps:

Write C code to be called by Xlisp interface routines. This C code does the real work, and in most cases is completely independent of Xlisp.
Add comments to .h files to tell Intgen which routines to build interfaces to, and to specify the types of the arguments.
Run Intgen to build interface routines.
Edit localptrs.h and localdefs.h to include generated .h files.
Compile and link Xlisp, including the new C code.

Header file format

Each routine to be interfaced with Xlisp must be declared as follows:

type-name routine-name(); /* LISP: (func-name type1 type2 ...) */

The comment may be on the line following the declaration, but the declaration and the comment must each be on no more than one line. The characters LISP: at the beginning of the comment mark routines to put in the interface. The comment also gives the type and number of arguments. The function, when accessed from lisp will be known as func-name, which need not bear any relationship to routine-name. By convention, underscores in the C routine-name should be converted to dashes in func-name, and func-name should be in all capitals. None of this is enforced or automated though.

Legal type_names are:

LVAL: returns an Xlisp datum.
atom_type: equivalent to LVAL, but the result is expected to be an atom.
value_type: a value as used in Dannenberg's score editor.
event_type: an event as used in Dannenberg's score editor.
int: interface will convert int to Xlisp FIXNUM.
boolean: interface will convert int to T or nil.
float or double: interface converts to FLONUM.
char * or string or string_type: interface converts to STRING. The result string will be copied into the XLISP heap.
void: interface will return nil.

It is easy to extend this list. Any unrecognized type will be coerced to an int and then returned as a FIXNUM, and a warning will be issued.

The "*" after char must be followed by routine-name with no intervening space.

Parameter types may be any of the following:

FIXNUM: C routine expects an int.
FLONUM or FLOAT: C routine expects a double.
STRING: C routine expects char *, the string is not copied.
VALUE: C routine expects a value_type. (Not applicable to Fugue.)
EVENT: C routine expects an event_type. (Not applicable to Fugue.)
ANY: C routine expects LVAL.
ATOM: C routine expects LVAL which is a lisp atom.
FILE: C routine expects FILE *.
SOUND: C routine expects a SoundPtr.

Any of these may be followed by "*": FIXNUM*, FLONUM*, STRING*, ANY*, FILE*, indicating C routine expects int *, double *, char **, LVAL *, or FILE ** . This is basically a mechanism for returning more than one value, not a mechanism for clobbering XLisp values. In this spirit, the interface copies the value (an int, double, char *, LVAL, or FILE *) to a local variable and passes the address of that variable to the C routine. On return, a list of resulting "*" parameters is constructed and bound to the global XLisp symbol *RSLT*. (Strings are copied.) If the C routine is void, then the result list is also returned by the corresponding XLisp function.

Note 1: this does not support C routines like strcpy that modify strings, because the C routine gets a pointer to the string in the XLisp heap. However, you can always add an intermediate routine that allocates space and then calls strcpy, or whatever.

Note 2: it follows that a new XLisp STRING will be created for each STRING* parameter.

Note 3: putting results on a (global!) symbol seems a bit unstructured, but note that one could write a multiple-value binding macro that hides this ugliness from the user if desired. In practice, I find that pulling the extra result values from *RSLT* when needed is perfectly acceptable.

For parameters that are result values only, the character "^" may be substituted for "*". In this case, the parameter is not to be passed in the XLisp calling site. However, the address of an initialized local variable of the given type is passed to the corresponding C function, and the resulting value is passed back through *RSLT* as ordinary result parameter as described above. The local variables are initialized to zero or NULL.

Using #define'd macros

If a comment of the form:

/* LISP: type-name (routine-name-2 type-1 type-2 ...) */

appears on a line by itself and there was a #define on the previous line, then the preceding #define is treated as a C routine, e.g.

#define leftshift(val, count) ((val) << (count))
/* LISP: int (LOGSHIFT INT INT) */

will implement the LeLisp function LOGSHIFT.

The type-name following "LISP:" should have no spaces, e.g. use ANY*, not ANY *.

Lisp Include Files

Include files often define constants that we would like to have around in the Lisp world, but which are easier to initialize just by loading a text file. Therefore, a comment of the form:

/* LISP-SRC: (any lisp expression) */

will cause Intgen to open a file name.lsp and append

(any lisp expression)

to name.lsp, where name is the interface name passed on the command line. If none of the include files examined have comments of this form, then no name.lsp file is generated. Note: the LISP-SRC comment must be on a new line.

Example

This file was used for testing Intgen. It uses a trick (ok, it's a hack) to interface to a standard library macro (tolower). Since tolower is already defined, the macro ToLower is defined just to give Intgen a name to call. Two other routines, strlen and tough, are interfaced as well.

/* igtest.h -- test interface for intgen */

#define ToLower(c) tolower(c)
/* LISP: int (TOLOWER FIXNUM) */

int strlen();	/* LISP: (STRLEN STRING) */

void tough(); 
  /* LISP: (TOUGH FIXNUM* FLONUM* STRING ANY FIXNUM) */

More Details

Intgen has some compiler switches to enable/disable the use of certain types, including VALUE and EVENT types used by Dannenberg's score editing work, the SOUND type used by Fugue, and DEXT and SEXT types added for Dale Amon. Enabling all of these is not likely to cause problems, and the chances of an accidental use of these types getting through the compiler and linker seems very small.

Previous Section | Next Section | Table of Contents | Index | Title Page