+10 Mar 2002
+
+ * Modified input parameters to load-foreign-library
+
+ * Added to documention
+
9 Mar 2002
* Added to documentation
# Programer: Kevin M. Rosenberg, M.D.
# Date Started: Mar 2002
#
-# CVS Id: $Id: Makefile,v 1.9 2002/03/10 11:14:39 kevin Exp $
+# CVS Id: $Id: Makefile,v 1.10 2002/03/10 21:48:50 kevin Exp $
#
# Copyright (c) 2002 by Kevin M. Rosenberg
#
docs:
@(cd doc; make dist-doc)
-VERSION=0.2.1
+VERSION=0.2.2
DISTDIR=uffi-${VERSION}
DIST_TARBALL=${DISTDIR}.tar.gz
DIST_ZIP=${DISTDIR}.zip
--- /dev/null
+<!-- -*- DocBook -*- -->
+
+<chapter>
+ <title>Programming Notes</title>
+
+ <sect1>
+ <title>Implementation Specific Notes</title>
+ <para>
+ </para>
+ <sect2>
+ <title>&acl;</title>
+ <para>
+ </para>
+ </sect2>
+ <sect2>
+ <title>&lw;</title>
+ <para>
+ </para>
+ </sect2>
+ <sect2>
+ <title>&cmucl;</title>
+ <para>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Foreign Object Representation and Access</title>
+ <para> There are two main approaches used to represent foreign
+ objects: an integer that represents an address in memory, and a
+ object that also includes run-time typing. The advantage of
+ run-time typing is the system can dereference pointers and perform
+ array access without those functions requiring a type at the cost
+ of additional overhead to generate and store the run-time
+ typing. The advantage of integer representation, at least for
+ &acl;, is that the compiler can generate inline code to
+ dereference pointers. Further, the overhead of the run-time type
+ information is eliminated. The disadvantage is the program must
+ then supply
+ the type to the functions to dereference objects and array.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Optimizing Code Using UFFI</title>
+ <sect2>
+ <title>Background</title>
+ <para>
+ Two implementions have different techniques to optimize
+ (open-code) foreign objects. &acl; can open-code foreign
+ object
+ access if pointers are integers and the type of object is
+ specified in the access function. Thus, &uffi; represents objects
+ in &acl; as integers which don't have type information.
+ </para> <para>
+ &cmucl; works best when keeping objects as typed
+ objects. However, it's compiler can open-code object access when
+ the object type is specified in <function>declare</function>
+ commands and in <varname>:type</varname> specifiers in
+ <function>defstruct</function> and <function>defclass</function>.
+ </para> <para> &lw;, in converse to &acl; and &cmucl; does not do
+ any open coding of object access. &lw;, by default, maintains
+ objects with run-time typing. </para>
+ </sect2>
+ <sect2>
+ <title>Cross-Implementation Optimization</title>
+<para>To fully optimize across platforms, both explicit type information
+must be passed to dereferencing of pointers and arrays. Though this
+optimization only helps with &acl;, &uffi; is designed to require this
+type information be passed the dereference functions. Second, declarations
+of type should be made in functions, structures, and classes where
+foreign objects will be help. This will optimize access for &lw;
+</para>
+</sect2>
+ </sect1>
+
+</chapter>
</sect1>
<sect1>
- <title>Immediate Types</title>
+ <title>Primitive Types</title>
<sect2>
<title>Overview</title>
<para>
- Immediate types have a single value, these include
+ Primitive types have a single value, these include
characters, numbers, and pointers. They are all symbols in
the keyword package.
</para>
<!ENTITY defsystem "<application>defsystem</application>">
<!ENTITY bookinfo SYSTEM "bookinfo.sgml">
<!ENTITY intro SYSTEM "intro.sgml">
+<!ENTITY notes SYSTEM "notes.sgml">
<!ENTITY ref SYSTEM "ref.sgml">
]>
<book>
&bookinfo;
&intro;
+¬es;
&ref;
</book>
+++ /dev/null
-;;;; -*- Mode: LISP; Syntax: ANSI-Common-Lisp; Base: 10 -*-
-;;;; *************************************************************************
-;;;; FILE IDENTIFICATION
-;;;;
-;;;; Name: immediates.cl
-;;;; Purpose: UFFI source to handle immediate types
-;;;; Programmer: Kevin M. Rosenberg
-;;;; Date Started: Feb 2002
-;;;;
-;;;; Copyright (c) 2002 Kevin M. Rosenberg
-;;;;
-;;;; $Id: immediates.cl,v 1.4 2002/03/10 17:42:35 kevin Exp $
-;;;;
-;;;; This file is part of the UFFI.
-;;;;
-;;;; UFFI is free software; you can redistribute it and/or modify
-;;;; it under the terms of the GNU General Public License (version 2) as
-;;;; published by the Free Software Foundation.
-;;;;
-;;;; UFFI is distributed in the hope that it will be useful,
-;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
-;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-;;;; GNU General Public License for more details.
-;;;;
-;;;; You should have received a copy of the GNU General Public License
-;;;; along with UFFI; if not, write to the Free Software
-;;;; Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-;;;; *************************************************************************
-
-(declaim (optimize (debug 3) (speed 3) (safety 1) (compilation-speed 0)))
-(in-package :uffi)
-
-(defmacro def-constant (name value)
- "Macro to define a constant and to export it"
- `(eval-when (:compile-toplevel :load-toplevel :execute)
- (defconstant ,name ,value)
- (export ',name)))
-
-(defmacro uffi-declare (type name)
- "Generates a declare statement for CL. Currently, only CMUCL
-supports this."
- #+(or lispworks allegro)
- (declare (ignore type name))
- #+cmu
- `(declare (type (alien ,type) ,name))
- )
-
-(defmacro slot-type (type)
- #+(or lispworks allegro)
- (declare (ignore type))
- #+(or lispworks allegro)
- t
- #+cmu `'(alien:alien ,type))
-
-(defmacro null-char-p (val)
- `(if (or (eql ,val 0)
- (eq ,val #\Null))
- t
- nil))
-
-
-(defmacro def-type (name type)
- #+lispworks `(fli:define-c-typedef ,name ,(convert-from-uffi-type type :type))
- #+allegro `(ff:def-foreign-type ,name ,(convert-from-uffi-type type :type))
- #+cmu `(alien:def-alien-type ,name ,(convert-from-uffi-type type :type))
- )
-
-(eval-when (:compile-toplevel :load-toplevel :execute)
- (defvar +type-conversion-hash+ (make-hash-table :size 20))
- #+cmu (defvar +cmu-def-type-hash+ (make-hash-table :size 20))
- )
-
-#+cmu
-(defconstant +cmu-def-type-list+
- '((:char . (alien:signed 8))
- (:unsigned-char . (alien:unsigned 8))
- (:byte . (alien:unsigned 8))
- (:short . (alien:signed 16))
- (:unsigned-short . (alien:unsigned 16))
- (:int . (alien:signed 32))
- (:unsigned-int . (alien:unsigned 32))
- (:long . (alien:signed 32))
- (:unsigned-long . (alien:unsigned 32))
- (:float . alien:single-float)
- (:double . alien:double-float)
- ))
-
-#+cmu
-(defconstant +type-conversion-list+
- '((* . *) (:void . c-call:void)
- (:short . c-call:short)
- (:pointer-void . (* t))
- (:cstring . c-call:cstring)
- (:char . c-call:char)
- (:unsigned-char . (alien:unsigned 8))
- (:byte . (alien:unsigned 8))
- (:int . alien:integer) (:unsigned-int . c-call:unsigned-int)
- (:long . c-call:long) (:unsigned-long . c-call:unsigned-long)
- (:float . c-call:float) (:double . c-call:double)
- (:array . alien:array)))
-#+allegro
-(defconstant +type-conversion-list+
- '((* . *) (:void . :void)
- (:short . :short)
- (:pointer-void . (* :void))
- (:cstring . (* :char))
- (:char . :char)
- (:unsigned-char . :unsigned-char)
- (:byte . :byte)
- (:int . :int) (:unsigned-int . :unsigned-int)
- (:long . :long) (:unsigned-long . :unsigned-long)
- (:float . :float) (:double . :double)
- (:array . :array)))
-#+lispworks
-(defconstant +type-conversion-list+
- '((* . :pointer) (:void . :void)
- (:short . :short)
- (:pointer-void . (:pointer :void))
- (:cstring . (:pointer :char))
- (:char . :char)
- (:unsigned-char . (:unsigned :char))
- (:int . :int) (:unsigned-int . (:unsigned :int))
- (:long . :long) (:unsigned-long . (:unsigned :long))
- (:float . :float) (:double . :double)
- (:array . :c-array)))
-
-(dolist (type +type-conversion-list+)
- (setf (gethash (car type) +type-conversion-hash+) (cdr type)))
-
-#+cmu
-(dolist (type +cmu-def-type-list+)
- (setf (gethash (car type) +cmu-def-type-hash+) (cdr type)))
-
-(defun ph (&optional (os *standard-output*))
- (maphash #'(lambda (k v) (format os "~&~S => ~S" k v)) +type-conversion-hash+))
-
-(defun convert-from-uffi-type (type context)
- "Converts from a uffi type to an implementation specific type"
- (if (atom type)
- (cond
- #+allegro
- ((and (or (eq context :routine) (eq context :return))
- (eq type :cstring))
- (setq type '((* :char) integer)))
- #+cmu
- ((eq context :type)
- (let ((cmu-type (gethash type +cmu-def-type-hash+)))
- (if cmu-type
- cmu-type
- (let ((found-type (gethash type +type-conversion-hash+)))
- (if found-type
- found-type
- type)))))
- (t
- (let ((found-type (gethash type +type-conversion-hash+)))
- (if found-type
- found-type
- type))))
- (cons (convert-from-uffi-type (first type) context)
- (convert-from-uffi-type (rest type) context))))
-
-
-
-
-
-
--- /dev/null
+;;;; -*- Mode: LISP; Syntax: ANSI-Common-Lisp; Base: 10 -*-
+;;;; *************************************************************************
+;;;; FILE IDENTIFICATION
+;;;;
+;;;; Name: primitives.cl
+;;;; Purpose: UFFI source to handle immediate types
+;;;; Programmer: Kevin M. Rosenberg
+;;;; Date Started: Feb 2002
+;;;;
+;;;; Copyright (c) 2002 Kevin M. Rosenberg
+;;;;
+;;;; $Id: primitives.cl,v 1.1 2002/03/10 21:48:50 kevin Exp $
+;;;;
+;;;; This file is part of the UFFI.
+;;;;
+;;;; UFFI is free software; you can redistribute it and/or modify
+;;;; it under the terms of the GNU General Public License (version 2) as
+;;;; published by the Free Software Foundation.
+;;;;
+;;;; UFFI is distributed in the hope that it will be useful,
+;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;;;; GNU General Public License for more details.
+;;;;
+;;;; You should have received a copy of the GNU General Public License
+;;;; along with UFFI; if not, write to the Free Software
+;;;; Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+;;;; *************************************************************************
+
+(declaim (optimize (debug 3) (speed 3) (safety 1) (compilation-speed 0)))
+(in-package :uffi)
+
+(defmacro def-constant (name value)
+ "Macro to define a constant and to export it"
+ `(eval-when (:compile-toplevel :load-toplevel :execute)
+ (defconstant ,name ,value)
+ (export ',name)))
+
+(defmacro uffi-declare (type name)
+ "Generates a declare statement for CL. Currently, only CMUCL
+supports this."
+ #+(or lispworks allegro)
+ (declare (ignore type name))
+ #+cmu
+ `(declare (type (alien ,type) ,name))
+ )
+
+(defmacro slot-type (type)
+ #+(or lispworks allegro)
+ (declare (ignore type))
+ #+(or lispworks allegro)
+ t
+ #+cmu `'(alien:alien ,type))
+
+(defmacro null-char-p (val)
+ `(if (or (eql ,val 0)
+ (eq ,val #\Null))
+ t
+ nil))
+
+
+(defmacro def-type (name type)
+ #+lispworks `(fli:define-c-typedef ,name ,(convert-from-uffi-type type :type))
+ #+allegro `(ff:def-foreign-type ,name ,(convert-from-uffi-type type :type))
+ #+cmu `(alien:def-alien-type ,name ,(convert-from-uffi-type type :type))
+ )
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+ (defvar +type-conversion-hash+ (make-hash-table :size 20))
+ #+cmu (defvar +cmu-def-type-hash+ (make-hash-table :size 20))
+ )
+
+#+cmu
+(defconstant +cmu-def-type-list+
+ '((:char . (alien:signed 8))
+ (:unsigned-char . (alien:unsigned 8))
+ (:byte . (alien:unsigned 8))
+ (:short . (alien:signed 16))
+ (:unsigned-short . (alien:unsigned 16))
+ (:int . (alien:signed 32))
+ (:unsigned-int . (alien:unsigned 32))
+ (:long . (alien:signed 32))
+ (:unsigned-long . (alien:unsigned 32))
+ (:float . alien:single-float)
+ (:double . alien:double-float)
+ ))
+
+#+cmu
+(defconstant +type-conversion-list+
+ '((* . *) (:void . c-call:void)
+ (:short . c-call:short)
+ (:pointer-void . (* t))
+ (:cstring . c-call:cstring)
+ (:char . c-call:char)
+ (:unsigned-char . (alien:unsigned 8))
+ (:byte . (alien:unsigned 8))
+ (:int . alien:integer) (:unsigned-int . c-call:unsigned-int)
+ (:long . c-call:long) (:unsigned-long . c-call:unsigned-long)
+ (:float . c-call:float) (:double . c-call:double)
+ (:array . alien:array)))
+#+allegro
+(defconstant +type-conversion-list+
+ '((* . *) (:void . :void)
+ (:short . :short)
+ (:pointer-void . (* :void))
+ (:cstring . (* :char))
+ (:char . :char)
+ (:unsigned-char . :unsigned-char)
+ (:byte . :byte)
+ (:int . :int) (:unsigned-int . :unsigned-int)
+ (:long . :long) (:unsigned-long . :unsigned-long)
+ (:float . :float) (:double . :double)
+ (:array . :array)))
+#+lispworks
+(defconstant +type-conversion-list+
+ '((* . :pointer) (:void . :void)
+ (:short . :short)
+ (:pointer-void . (:pointer :void))
+ (:cstring . (:pointer :char))
+ (:char . :char)
+ (:unsigned-char . (:unsigned :char))
+ (:int . :int) (:unsigned-int . (:unsigned :int))
+ (:long . :long) (:unsigned-long . (:unsigned :long))
+ (:float . :float) (:double . :double)
+ (:array . :c-array)))
+
+(dolist (type +type-conversion-list+)
+ (setf (gethash (car type) +type-conversion-hash+) (cdr type)))
+
+#+cmu
+(dolist (type +cmu-def-type-list+)
+ (setf (gethash (car type) +cmu-def-type-hash+) (cdr type)))
+
+(defun ph (&optional (os *standard-output*))
+ (maphash #'(lambda (k v) (format os "~&~S => ~S" k v)) +type-conversion-hash+))
+
+(defun convert-from-uffi-type (type context)
+ "Converts from a uffi type to an implementation specific type"
+ (if (atom type)
+ (cond
+ #+allegro
+ ((and (or (eq context :routine) (eq context :return))
+ (eq type :cstring))
+ (setq type '((* :char) integer)))
+ #+cmu
+ ((eq context :type)
+ (let ((cmu-type (gethash type +cmu-def-type-hash+)))
+ (if cmu-type
+ cmu-type
+ (let ((found-type (gethash type +type-conversion-hash+)))
+ (if found-type
+ found-type
+ type)))))
+ (t
+ (let ((found-type (gethash type +type-conversion-hash+)))
+ (if found-type
+ found-type
+ type))))
+ (cons (convert-from-uffi-type (first type) context)
+ (convert-from-uffi-type (rest type) context))))
+
+
+
+
+
+
;;;;
;;;; Copyright (c) 2002 Kevin M. Rosenberg
;;;;
-;;;; $Id: uffi.system,v 1.2 2002/03/09 21:53:58 kevin Exp $
+;;;; $Id: uffi.system,v 1.3 2002/03/10 21:48:50 kevin Exp $
;;;;
;;;; This file is part of UFFI.
;;;;
:binary-pathname "UFFI:src;bin;"
:components
((:file "package")
- (:file "immediates" :depends-on ("package"))
- (:file "strings" :depends-on ("immediates"))
- (:file "objects" :depends-on ("immediates"))
- (:file "aggregates" :depends-on ("immediates"))
- (:file "functions" :depends-on ("immediates"))
- (:file "libraries" :depends-on ("package")))
- )
+ (:file "primitives" :depends-on ("package"))
+ (:file "strings" :depends-on ("primitives"))
+ (:file "objects" :depends-on ("primitives"))
+ (:file "aggregates" :depends-on ("primitives"))
+ (:file "functions" :depends-on ("primitives"))
+ (:file "libraries" :depends-on ("package"))))
+
+
projects / uffi.git / commitdiff