ACL 4.3 FFI compatibility issues

$Revision: 1.1 $

This document was provided to users of Allegro CL release 5.0/5.0.1 to assist in porting Allegro CL 4.3 applications to the new release. We provide it, essentially unedited, for any users of release 6.0 who might need it.

Table of Contents

• Introduction
• UNIX Symbols (exported from FF)
• UNIX Types

Introduction

To use the compatibility mode, (require :ffcompat) and use the old (Allegro CL 4.3) functionality.  Most of the Allegro CL 4.3 interface is identical, including all of the deprecations between Allegro CL 4.2 and 4.3.

The following exceptions apply:

• ff:*update-entry-points* is deleted; the functionality that it specified when true is now the only possible functionality under any foreign-loading implementation in Allegro CL 5.0. Note that the symbol no longer exists.
• The callback keyword argument to defforeign is ignored, and is assumed to be T. No warning is generated if callback is used.
• The method-index keyword argument to defforeign is added and its behavior is similar to the def-foreign-call keyword of the same name.
• The convention keyword argument to defforeign is added and its behavior is similar to the def-foreign-call keyword of the same name. Its default value is the value given or defaulted by the defforeign language keyword.
• ff:char*-to-string takes a second, optional, argument which if given should be a string large enough to hold the contents of the char*. If the string is long enough, then it is used to store the char*.  If the given string isn't long enough, an error will be signaled, unless a third argument is given and is non-nil, in which case a long enough string will be created.
• New return-types for foreign-functions:
  • The :boolean return-type converts from a C true/false value (non-zero is true) to a lisp true/false value (non-nil is true). This option works on call-direct as well as non-call-direct foreign functions.
  • The :single-float-from-double return-type causes an assumption to be made that the return value was a double-float but that the intention was to return single-float. The action taken is to convert the value from double-float to single-float. This type is intended for use with older non-ansi C compilers which return floats as doubles instead of floats.
• Foreign-function return-type change:  the :single-float return-type will now never perform a conversion from double-float to single-float (use the :single-float-from-double type described above, for that).
• Handling of foreign-callables (functions defined by ff:defun-c-callable and ff:defun-foreign-callable) is different:
  • A mechanism is in place to call such functions from lisp, as well as from C (the usual case). The mechanism is described in Calling foreign callables from Lisp in foreign-functions.htm. (4.3 and earlier had a lisp function called lisp-call, which didn't always work and does not exist in 5.0.) The purpose of this mechanism is solely to allow debugging; it is not efficient, and so is not intended for normal operation.
  • The first argument to ff:register-foreign-callable and to ff:register-function must be a foreign-callable (i.e. defined with ff:defun-foreign-callable or ff:defun-c-callable). Registering a normal function which uses ff::foreign-argument (deprecated in 4.3) is no longer allowed. See Calling foreign callables from Lisp in foreign-functions.htm.
• Foreign-functions that return type short or unsigned-short (Windows only). See the second bullet under Notes just below.

Notes:

• For ACL/WIN compatibility see the ACLWin 3.x FFI Compatibility Support document.
• If you have moved to NT or Windows 95 or 98 from a Unix machine and are using the ffcompat compatibility package, you should look for any C functions which return short or unsigned short values, and analyze whether or not the defforeign calls for them need to be changed. The Windows calling convention does not properly zero out the higher order bits of sub-integer return values, and they thus must be processed after returning.

The use of :fixnum or :integer to accept a short return value is not supported by defforeign. Therefore, use of this model to return shorts, without subsequent post-processing, is in fact a bug in user code. However, it usually did seem to work on Unix systems in 4.3. But again, it does not work in Windows and may not work in subsequent Unix versions.

To fix unsigned short returns, continue to accept the value with the :return-type of :fixnum or :integer, but wrap each call in a

(logand res #xffff) 

to get the correct bits.

To fix signed short values, you can specify :signed-short as the :return-type in the defforeign definition, even though it is not documented as part of the 4.3 defforeign interface.

UNIX Symbols (exported from FF)

UNIX Types

  :char   :byte    :unsigned-char   :unsigned-byte
  :int    :long    :unsigned-int    :unsigned-long
  :short  :unsigned-short
  :float  :double
  :bit ***
  :union  :struct  :array
  :lisp

Copyright (C) 1998-1999, Franz Inc., Berkeley, CA. All Rights Reserved.