From d5d0bfb15f7a30ac5398211708f5f5d9d4a95e04 Mon Sep 17 00:00:00 2001 From: "Kevin M. Rosenberg" Date: Fri, 15 Mar 2002 11:38:13 +0000 Subject: [PATCH] r1573: *** empty log message *** --- ChangeLog | 24 +- Makefile | 4 +- doc/appendix.sgml | 20 + doc/intro.sgml | 28 +- doc/ref.sgml | 1706 ++++++++++++++++++++++++++++++++++++++++----- src/primitives.cl | 12 +- 6 files changed, 1560 insertions(+), 234 deletions(-) diff --git a/ChangeLog b/ChangeLog index fb8b0cf..5ffd8ed 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,58 +1,40 @@ +15 Mar 2002 + * Finished basic documentation. + 14 Mar 2002 - * Changed license to more liberal Lisp Lessor GNU Public License - * Fixed problem with including uffi.system in distribution (Thanks John DeSoi) - * Fixed compiler warnings 11 Mar 2002 - * Changed def-type to def-foreign-type - * Created new macro def-type to generate cl:deftype forms. Removed uffi-declare and uffi-slot-type as they are no longer necessary. 10 Mar 2002 - * Modified input parameters to load-foreign-library - * Added to documention - * Changed parameter order in get-slot-value and deref-array 9 Mar 2002 - * Added to documentation - * Made Allegro CL array access more efficient - * Changed def-routine name to def-function - * Fixed bug in def-function for Lispworks] - * Fixed error in +null-c-string-pointer+ name - * Fixed error in (make-null-pointer) for Lispworks - * Reworked Lispwork c-strings to be (* :char) rather than the implementation default of (* (:unsigned :char)) to be consistent with CMUCL. Bumped version to 0.2.0 because of change this change. - * Renamed c-string to cstring to emphasize it as a basic type - * Modified getenv.cl example to avoid name collison with LW - * Modified compress.cl to setup output buffer as :unsigned*char - * Added test-all-examples function. All routines tested okay with ACL, LW, and CMUCL 8 Mar 2002 - * Added ZIP file output with LF->CRLF translations to distribution - * Modified def-enum to use uffi:def-constant rather than cl:defconstant diff --git a/Makefile b/Makefile index 4ac6c40..a090fcb 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ # Programer: Kevin M. Rosenberg, M.D. # Date Started: Mar 2002 # -# CVS Id: $Id: Makefile,v 1.14 2002/03/14 21:32:23 kevin Exp $ +# CVS Id: $Id: Makefile,v 1.15 2002/03/15 11:38:13 kevin Exp $ # # This file, part of UFFI, is Copyright (c) 2002 by Kevin M. Rosenberg # @@ -31,7 +31,7 @@ realclean: clean docs: @(cd doc; make dist-doc) -VERSION=0.2.5 +VERSION=0.2.6x DISTDIR=uffi-${VERSION} DIST_TARBALL=${DISTDIR}.tar.gz DIST_ZIP=${DISTDIR}.zip diff --git a/doc/appendix.sgml b/doc/appendix.sgml index 3e8c989..a888a5a 100644 --- a/doc/appendix.sgml +++ b/doc/appendix.sgml @@ -5,6 +5,26 @@ Download &uffi; +You need to download the &uffi; package from its web +home. +You also need to have a copy of &defsystem;. If you need a copy of +&defsystem;, it is included in the + + CLOCC package. You can download +the file defsystem.lisp from the CVS +tree. + + + + Installation + + After downloading and installing &defsystem;, simply + push the + directory containing &uffi; into + mk:*central-registry* variable. Whenever you +want to load the &uffi; package, use the function + (mk:load-system :uffi). diff --git a/doc/intro.sgml b/doc/intro.sgml index d432b9f..23b4c7c 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -45,20 +45,16 @@ - - Installation - - Installation is fairly simple. The main requirement is that you - have a copy of &defsystem;. You can download the latest version - of &defsystem; from the - CLOCC - CVS tree. After installing &defsystem;, simply - push the - directory containing &uffi; into - mk:*central-registry*. Whenever you -want to load the &uffi; package, use the function - (mk:load-system :uffi). - - + + Design Overview + + &uffi; was designed as a cross-implementation compatible + Foreign Function Interface. Necessarily, + only a common subset of functionality can be + provided. Likewise, not every optimization for that a specific + implementation provides can be supported. Wherever possible, + though, implementation-specific optimizations are invoked. + + + diff --git a/doc/ref.sgml b/doc/ref.sgml index aaf1fea..252bdc5 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -1,51 +1,86 @@ - - Programming Reference + + Declarations + - Design Overview - - &uffi; was designed as a cross-implementation compatible - Foreign Function Interface. Necessarily, - only a common subset of functionality can be - provided. Likewise, not every optimization for that a specific - implementation provides can be supported. Wherever possible, - though, implementation-specific optimizations are invoked. - - - - - Declarations - - Overview - Declarations are used to give the compiler optimizing + Overview + Declarations are used to give the compiler optimizing information about foreign types. Currently, only &cmucl; supports declarations. On &acl; and &lw;, these expressions declare the type generically as &t; - - + + + - - def-type - - This is used wherever a &cl; deftype - expression can be placed. Used to declare types to -the compiler for optimization. Currently, on &cmucl; takes advantage -of this. - - -(uffi:def-type my-struct-def my-struct-foreign-type) - + + + def-type + Defines a Common Lisp type. + + Macro + + + Syntax + + def-type name type + + + + Arguments and Values + + + name + + A symbol naming the type + + + + type + + A form that is evaluated that specifies the &uffi; type. + + + + + + + Description + Defines a Common Lisp type based on a &uffi; type. - - + + + Examples + +(def-type char-ptr '(* :char)) +... +(defun foo (ptr) + (declare (type char-ptr ptr)) + ... + + + + Side Effects + Defines a new &cl; type. + + + Affected by + None. + + + Exceptional Situations + None. + + + - - Primitive Types - - Overview + + + Primitive Types + + Overview Primitive types have a single value, these include characters, numbers, and pointers. They are all symbols in @@ -95,148 +130,1080 @@ The absence of a value. Used in generic pointers and in return types from functi * - Used to declare a pointer to an object - - - def-constant + + + + + def-constant + Binds a symbol to a constant. + + Macro + + + Syntax + + def-constant name value &key export + + + + Arguments and Values + + + name + + A symbol that will be bound to the value. + + + + + value + + An evaluated form that is bound the the name. + + + + + export + + When &t;, the name is exported from the current package. The default is &nil; + + + + + + Description This is a thin wrapper around defconstant. It evaluates at - compile-time and exports the symbol from the package. - - - - def-type - - This is the main function for creating new types. - - - Examples - - -(def-type my-generic-pointer (* :void)) -(def-type a-double-float :double-float) -(def-type char-ptr (* :char)) - - - - - - null-char-p - - A predicate testing if a pointer object is &null; + compile-time and optionally exports the symbol from the package. - - + + + Examples + +(def-constant pi2 (* 2 pi)) +(def-constant exported-pi2 (* 2 pi) :export t) + + + + Side Effects + Creates a new special variable.. + + + Affected by + None. + + + Exceptional Situations + None. + + - - Aggregate Types - - def-enum - - Declares a &c; enumeration. It generates constants for the - elements of the enumeration. - - - - def-struct - - Declares a structure. A special type is available as a slot in the field. It is - a pointer that points to an instance of the parent structure. It's type is - :pointer-self. - - - Examples - - -(def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self)) - - - - - - get-slot-value - - Accesses a slot value from a structure. - - - - get-slot-pointer - - This is similar to get-slot-value. It - is used when the value of a slot is a pointer type. - - - - def-array - - Defines an array. + + + def-foreign-type + Defines a new foreign type. + + Macro + + + Syntax + + def-foreign-type name type + + + + Arguments and Values + + + name + + A symbol naming the new foreign type. + + + + + value + + A form that is not evaluated that defines the new +foreign type. + + + + + + + Description + Defines a new foreign type. - - - deref-array - - Accesses an element of an array. + + + Examples + +(def-foreign-type my-generic-pointer (* :void)) +(def-foreign-type a-double-float :double-float) +(def-foreign-type char-ptr (* :char)) + + + + Side Effects + Defines a new foreign type. - - + + + Affected by + None. + + + Exceptional Situations + None. + + - - Objects - - Overview + + + null-char-p + Tests a character for &null; value. + + Macro + + + Syntax + + null-char-p char => is-null + + + + Arguments and Values + + + char + + A character or integer. + + + + + is-null + + A boolean flag indicating if char is a &null; value. + + + + + + + Description - Objects are entities that can allocated and freed. + A predicate testing if a character or integer is &null;. This +abstracts the difference in implementations where some return a +character and some return a +integer whence dereferencing a +C character pointer. - - - allocate-foreign-object - - Allocates an instance of a foreign object. It returns a pointer to the object. + + + Examples + +(def-array ca :char) +(let ((fs (convert-to-foreign-string "ab"))) + (values (null-char-p (deref-array fs 'ca 0)) + (null-char-p (deref-array fs 'ca 2)))) +=> &nil; + &t; + + + + Side Effects + None. - - - free-foreign-object + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + ensure-char + Ensures value is a character. + + Macro + + + Syntax + + ensure-char obj => char + + + + Arguments and Values + + + obj + + A character or integer. + + + + + char + + A character value. + + + + + + + Description - Frees the memory used by a foreign object. + Enscapsulates the fact that some implementations return a character +and others return an integer when dereferencing a character pointer. - - - pointer-address + + + Examples - Returns the address as an integer of a pointer. + +(let ((fs (convert-to-foreign-string "a"))) + (prog1 + (ensure-char (deref-pointer fs :char)) + (free-foreign-object fs))) +=> #\a + - - - deref-pointer - - Returns the object to which a pointer points. + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + Signals an error if obj is not +an integer or character. + + + + + + Aggregate Types + + Overview + + Aggregate types are comprised of one or more primitive types. + + + + + + def-enum + Defines a &c; enumeration. + + Macro + + + Syntax + + def-enum name fields &key separator-string + + + + Arguments and Values + + + name + + A symbol that names the enumeration. + + + + + fields + + A list of field defintions. Each definition can be +a symbol or a list of two elements. Symbols get assigned a value of the +current counter which starts at 0 and +increments by 1 for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second +position is the value to assign the the symbol. The current counter gets set +to 1+ this value. + + + + + separator-string + + A string that governs the creation of constants. The +default is "#". + + + + + + Description + + Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant +values are created by the concatenation of the +enumeration name, separator-string, and field symbol. Also creates +a foreign type with the name name of type +:int. + + + + Examples + +(def-enum abc (:a :b :c)) +;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines +;; the foreign type "abc" to be :int + +(def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-") +;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines +;; the foreign type efoo to be :int + + + + Side Effects + Creates a :int foreign type, defines constants. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-struct + Defines a &c; structure. + + Macro + + + Syntax + + def-struct name &rest fields + + + + Arguments and Values + + + name + + A symbol that names the structure. + + + + + fields + + A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type. + + + + + + + Description + + Declares a structure. A special type is available as a slot +in the field. It is a pointer that points to an instance of the parent +structure. It's type is :pointer-self. + + + + + Examples + +(def-struct foo (a :unsigned-int) + (b (* :char)) + (c (:array :int 10)) + (next :pointer-self)) + + + + Side Effects + Creates a foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-slot-value + Retrieves a value from a slot of a structure. + + Macro + + + Syntax + + get-slot-value obj type field => value + + + + Arguments and Values + + + obj + + A pointer to foreign structure. + + + + + type + + A name of the foreign structure. + + + + + field + + A name of the desired field in foreign structure. + + + + + value + + The value of the field in the structure. + + + + + + + Description + + Accesses a slot value from a structure. + + + + Examples + +(get-slot-value foo-ptr 'foo-structure 'field-name) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + get-slot-pointer + Retrieves a pointer from a slot of a structure. + + Macro + + + Syntax + + get-slot-pointer obj type field => pointer + + + + Arguments and Values + + + obj + + A pointer to foreign structure. + + + + + type + + A name of the foreign structure. + + + + + field + + A name of the desired field in foreign structure. + + + + + pointer + + The value of the field in the structure. + + + + + + + Description + + This is similar to get-slot-value. It + is used when the value of a slot is a pointer type. + + + + Examples + +(get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-array + Defines a foreign array type. + + Macro + + + Syntax + + def-array name type + + + + Arguments and Values + + + name + + A name of the new foreign type. + + + + + type + + The foreign type of the array elements. + + + + + + + Description + + Defines a foreign array type. + + + + Examples + +(def-array byte-array :unsigned-char) + + + + Side Effects + Defines a new foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + deref-array + Deference an array. + + Macro + + + Syntax + + deref-array array type positon => value + + + + Arguments and Values + + + array + + A foreign array. + + + + + type + + The foreign type of the array. + + + + + position + + An integer specifying the position to retrieve from +the array. + + + + + value + + The value stored in the position of the array. + + + + + + + Description + + Dereferences (retrieves) the value of an array element. + + + + Examples + +(def-array ca :char) +(let ((fs (convert-to-foreign-string "ab"))) + (values (null-char-p (deref-array fs 'ca 0)) + (null-char-p (deref-array fs 'ca 2)))) +=> &nil; + &t; + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + Objects + +Overview + + Objects are entities that can allocated and freed. + + + + + + + allocate-foreign-object + Allocates an instance of a foreign object. + + Macro + + + Syntax + + allocate-foreign-object type => ptr + + + + Arguments and Values + + + type + + A type of foreign object to allocate. + + + + + ptr + + A pointer to the foreign object. + + + + + + + Description + + Allocates an instance of a foreign object. It returns a pointer to the object. + + + + Examples + +(def-struct ab (a :int) (b :double)) +(allocate-foreign-object 'ab) +=> #<ptr> + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + free-foreign-object + Frees memory that was allocated for a foreign boject. + + Macro + + + Syntax + + free-foreign-object ptr + + + + Arguments and Values + + + ptr + + A pointer to the allocated foreign object to free. + + + + + + + Description + + Frees the memory used by the allocation of a foreign object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + pointer-address + Returns the address of a pointer. + + Macro + + + Syntax + + pointer-address ptr => address + + + + Arguments and Values + + + ptr + + A pointer to a foreign object. + + + + + address + + An integer representing the pointer's address. + + + + + + + Description + + Returns the address as an integer of a pointer. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + deref-pointer + Deferences a pointer. + + Macro + + + Syntax + + def-pointer ptr type => value + + + + Arguments and Values + + + ptr + + A pointer to a foreign object. + + + + + type + + A foreign type of the object being pointed to. + + + + + value + + The value of the object where the pointer points. + + + + + + + Description + + Returns the object to which a pointer points. + + + + Examples + + +(let ((fs (convert-to-foreign-string "a"))) + (prog1 + (ensure-char (deref-pointer fs :char)) + (free-foreign-object fs))) +=> #\a + - - - make-null-pointer + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + make-null-pointer + Create a &null; pointer. + + Macro + + + Syntax + + make-null-pointer type => ptr + + + + Arguments and Values + + + type + + A type of object to which the pointer refers. + + + + + ptr + + The &null; pointer of type type. + + + + + + + Description Creates a &null; pointer of a specified type. - - - null-pointer-p + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + null-pointer-p + Tests a pointer for &null; value. + + Macro + + + Syntax + + null-pointer-p ptr => is-null + + + + Arguments and Values + + + ptr + + A foreign object pointer. + + + + + is-null + + The boolean flag. + + + + + + + Description A predicate testing if a pointer is has a &null; value. - - - +null-cstring-pointer+ + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + +null-cstring-pointer+ + A constant &null; cstring pointer. + + Constant + + + Description - A constant &null; character pointer. + A &null; cstring pointer. This can be used for testing +if a cstring returned by a function is &null;. - - + + - + + + Strings - - Overview - + +Overview + &uffi; has functions to two types of C-compatible strings, cstring and foreign strings. cstrings are used as parameters to and from functions. An implementation, such as CMUCL, @@ -244,37 +1211,214 @@ may not convert these to a foreign type for efficiency sake. Thus, it is not possible to "allocate" a cstring. In contrast, foreign strings always need to have memory for them. - - - convert-from-cstring + + + + + convert-from-cstring + Converts a cstring to a Lisp string. + + Macro + + + Syntax + + convert-from-cstring cstring => string + + + + Arguments and Values + + + cstring + + A cstring. + + + + + string + + A Lisp string. + + + + + + + Description - Converts a Lisp string to a cstring. + Converts a Lisp string to a cstring. This is +most often used when processing the results of a foreign function +that returns a cstring. - - - convert-to-cstring + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-cstring + Converts a Lisp string to a cstring. + + Macro + + + Syntax + + convert-to-cstring string => cstring + + + + Arguments and Values + + + string + + A Lisp string. + + + + + cstring + + A cstring. + + + + + + + Description Converts a Lisp string to a cstring. The cstring should be freed with free-cstring. - - - free-cstring + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + free-cstring + Free memory used by cstring. + + Macro + + + Syntax + + free-cstring cstring + + + + Arguments and Values + + + cstring + + A cstring. + + + + + + + Description Frees any memory possibly allocated by convert-to-cstring. - - - with-cstring + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + with-cstring + Binds a newly created cstring. + + Macro + + + Syntax + + with-cstring (cstring string) {body} + + + + Arguments and Values + + + cstring + + A symbol naming the cstring to be created. + + + + + string + + A Lisp string that will be translated to a cstring. + + + + + body + + The body of where the cstring will be bound. + + + + + + + Description Binds a lexical variable to a newly allocated cstring. Automatically frees cstring. - - Examples - + + + Examples + (def-function ("getenv" c-getenv) ((name :cstring)) @@ -285,35 +1429,216 @@ always need to have memory for them. (check-type key string) (with-cstring (key-cstring key) (convert-from-cstring (c-getenv key-cstring)))) - - - - - - convert-from-foreign-string + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-from-foreign-string + Converts a foreign string into a Lisp string. + + Macro + + + Syntax + + convert-from-foreign-string foreign-string &key length null-terminated-p => string + + + + Arguments and Values + + + foreign-string + + A foreign string. + + + + + length + + The length of the foreign string to +convert. The default is the length of the string until a &null; +character is reached. + + + + + null-terminated-p + + A boolean flag with a default value of &t; When true, +the string is converted until the first &null; character is reached. + + + + + string + + A Lisp string. + + + + + + + Description - Returns a Lisp string from a foreign string. Has parameters - to handle ASCII versus binary strings. + Returns a Lisp string from a foreign string. +Can translated ASCII and binary strings. - - - convert-to-foreign-string + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-foreign-string + Converts a Lisp string to a foreign string. + + Macro + + + Syntax + + convert-to-foreign-string string => foreign-string + + + + Arguments and Values + + + string + + A Lisp string. + + + + + foreign-string + + A foreign string. + + + + + + + Description Converts a Lisp string to a foreign string. Memory should be freed with free-foreign-object. - - - allocate-foreign-string + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + + allocate-foreign-string + Allocates space for a foreign string. + + Macro + + + Syntax + + allocate-foreign-string size &key unsigned => foreign-string + + + + Arguments and Values + + + size + + The size of the space to be allocated in bytes. + + + + + unsigned + + A boolean flag with a default value of &nil;. When true, +marks the pointer as an :unsigned-char. + + + + + foreign-string + + A foreign string which has undefined contents. + + + + + + + Description Allocates space for a foreign string. Memory should be freed with free-foreign-object. - - + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + Functions & Libraries - - Functions def-function @@ -387,10 +1712,7 @@ foreign function. None. - - - Libraries load-foreign-library @@ -473,7 +1795,7 @@ a session. None. - - + + diff --git a/src/primitives.cl b/src/primitives.cl index ee52980..294dcdc 100644 --- a/src/primitives.cl +++ b/src/primitives.cl @@ -7,7 +7,7 @@ ;;;; Programmer: Kevin M. Rosenberg ;;;; Date Started: Feb 2002 ;;;; -;;;; $Id: primitives.cl,v 1.5 2002/03/14 21:32:23 kevin Exp $ +;;;; $Id: primitives.cl,v 1.6 2002/03/15 11:38:13 kevin Exp $ ;;;; ;;;; This file, part of UFFI, is Copyright (c) 2002 by Kevin M. Rosenberg ;;;; @@ -19,11 +19,11 @@ (declaim (optimize (debug 3) (speed 3) (safety 1) (compilation-speed 0))) (in-package :uffi) -(defmacro def-constant (name value) +(defmacro def-constant (name value &key (export nil)) "Macro to define a constant and to export it" `(eval-when (:compile-toplevel :load-toplevel :execute) (defconstant ,name ,value) - (export ',name))) + ,(if export (list 'export `(quote ,name)) (values)))) (defmacro def-type (name type) "Generates a (deftype) statement for CL. Currently, only CMUCL @@ -42,6 +42,12 @@ supports takes advantage of this optimization." t nil)) +(defmacro ensure-char (val) + `(etypecase ,val + (integer + (code-char ,val)) + (character + ,val))) (defmacro def-foreign-type (name type) #+lispworks `(fli:define-c-typedef ,name ,(convert-from-uffi-type type :type)) -- 2.34.1