Update of /project/cells/cvsroot/cells-gtk/cffi/doc In directory clnet:/tmp/cvs-serv9292/cffi/doc

Added Files: Makefile allegro-internals.txt cffi-manual.texinfo cffi-sys-spec.texinfo colorize-lisp-examples.lisp gendocs.sh gendocs_template mem-vector.txt shareable-vectors.txt style.css Log Message:

--- /project/cells/cvsroot/cells-gtk/cffi/doc/Makefile 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/Makefile 2008/01/28 23:59:26 1.1 # -*- Mode: Makefile; tab-width: 3; indent-tabs-mode: t -*- # # Makefile --- Make targets for generating the documentation. # # Copyright (C) 2005-2006, Luis Oliveira <loliveira at common-lisp.net> # # Permission is hereby granted, free of charge, to any person # obtaining a copy of this software and associated documentation # files (the "Software"), to deal in the Software without # restriction, including without limitation the rights to use, copy, # modify, merge, publish, distribute, sublicense, and/or sell copies # of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be # included in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # DEALINGS IN THE SOFTWARE. #

all: docs

docs: sh gendocs.sh -o manual --html "--css-include=style.css" cffi-manual "CFFI User Manual" sh gendocs.sh -o spec --html "--css-include=style.css" cffi-sys-spec "CFFI-SYS Interface Specification"

clean: find . ( -name "*.info" -o -name "*.aux" -o -name "*.cp" -o -name "*.fn" -o -name "*.fns" -o -name "*.ky" -o -name "*.log" -o -name "*.pg" -o -name "*.toc" -o -name "*.tp" -o -name "*.vr" -o -name "*.dvi" -o -name "*.cps" -o -name "*.vrs" ) -exec rm {} ; rm -rf manual spec

upload-docs: rsync -av --delete -e ssh manual spec common-lisp.net:/project/cffi/public_html/ # scp -r manual spec common-lisp.net:/project/cffi/public_html/

# vim: ft=make ts=3 noet --- /project/cells/cvsroot/cells-gtk/cffi/doc/allegro-internals.txt 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/allegro-internals.txt 2008/01/28 23:59:26 1.1 July 2005 These details were kindly provided by Duane Rettig of Franz.

Regarding the following snippet of the macro expansion of FF:DEF-FOREIGN-CALL:

(SYSTEM::FF-FUNCALL (LOAD-TIME-VALUE (EXCL::DETERMINE-FOREIGN-ADDRESS '("foo" :LANGUAGE :C) 2 NIL)) '(:INT (INTEGER * *)) ARG1 '(:DOUBLE (DOUBLE-FLOAT * *)) ARG2 '(:INT (INTEGER * *)))

" ... in Allegro CL, if you define a foreign call FOO with C entry point "foo" and with :call-direct t in the arguments, and if other things are satisfied, then if a lisp function BAR is compiled which has a call to FOO, that call will not go through ff-funcall (and thus a large amount of argument manipulation and processing) but will instead set up its arguments directly on the stack, and will then perform the "call" more or less directly, through the "entry vec" (a small structure which keeps track of a foreign entry's address and status)."

This is the code that generates what the compiler expects to see:

(setq call-direct-form (if* call-direct then `(setf (get ',lispname 'sys::direct-ff-call) (list ',external-name ,callback ,convention ',returning ',arg-types ,arg-checking ,entry-vec-flags)) else `(remprop ',lispname 'sys::direct-ff-call)))

Thus generating something like:

(EVAL-WHEN (COMPILE LOAD EVAL) (SETF (GET 'FOO 'SYSTEM::DIRECT-FF-CALL) (LIST '("foo" :LANGUAGE :C) T :C '(:INT (INTEGER * *)) '((:INT (INTEGER * *)) (:FLOAT (SINGLE-FLOAT * *))) T 2 ; this magic value is explained later )))

" (defun determine-foreign-address (name &optional (flags 0) method-index) ;; return an entry-vec struct suitable for the foreign-call of name. ;; ;; name is either a string, which is taken without conversion, or ;; a list consisting of a string to convert or a conversion function ;; call. ;; flags is an integer representing the flags to place into the entry-vec. ;; method-index, if non-nil, is a word-index into a vtbl (virtual table). ;; If method-index is true, then the name must be a string uniquely ;; represented by the index and by the flags field.

Note that not all architectures implement the :method-index argument to def-foreign-call, but your interface likely won't support it anyway, so just leave it nil. As for the flags, they are constants stored into the entry-vec returned by d-f-a and are given here:

(defconstant ep-flag-call-semidirect 1) ; Real address stored in alt-address slot (defconstant ep-flag-never-release 2) ; Never release the heap (defconstant ep-flag-always-release 4) ; Always release the heap (defconstant ep-flag-release-when-ok 8) ; Release the heap unless without-interrupts

(defconstant ep-flag-tramp-calls #x70) ; Make calls through special trampolines (defconstant ep-flag-tramp-shift 4)

(defconstant ep-flag-variable-address #x100) ; Entry-point contains address of C var (defconstant ep-flag-strings-convert #x200) ; Convert strings automatically

(defconstant ep-flag-get-errno #x1000) ;; [rfe5060]: Get errno value after call (defconstant ep-flag-get-last-error #x2000) ;; [rfe5060]: call GetLastError after call ;; Leave #x4000 and #x8000 open for expansion

Mostly, you'll give the value 2 (never release the heap), but if you give 4 or 8, then d-f-a will automatically set the 1 bit as well, which takes the call through a heap-release/reacquire process.

Some docs for entry-vec are:

;; -- entry vec -- ;; An entry-vec is an entry-point descriptor, usually a pointer into ;; a shared-library. It is represented as a 5-element struct of type ;; foreign-vector. The reason for this represntation is ;; that it allows the entry point to be stored in a table, called ;; the .saved-entry-points. table, and to be used by a foreign ;; function. When the location of the foreign function to which the entry ;; point refers changes, it is simply a matter of changing the value in entry ;; point vector and the foreign call code sees it immediately. There is ;; even an address that can be put in the entry point vector that denotes ;; a missing foreign function, thus lookup can happen dynamically.

(defstruct (entry-vec (:type (vector excl::foreign (*))) (:constructor make-entry-vec-boa ())) name ; entry point name (address 0) ; jump address for foreign code (handle 0) ; shared-lib handle (flags 0) ; ep-* flags (alt-address 0) ; sometimes holds the real func addr )

[...] "

Regarding the arguments to SYSTEM::FF-FUNCALL: '(:int (integer * *)) argN

"The type-spec is as it is given in the def-foreign-call syntax, with a C type optionally followed by a lisp type, followed optionally by a user-conversion function name[...]"

Getting the alignment:

CL-USER(2): (ff:get-foreign-type :int) #S(FOREIGN-FUNCTIONS::IFOREIGN-TYPE :ATTRIBUTES NIL :SFTYPE #S(FOREIGN-FUNCTIONS::SIZED-FTYPE-PRIM :KIND :INT :WIDTH 4 :OFFSET 0 :ALIGN 4) ...) --- /project/cells/cvsroot/cells-gtk/cffi/doc/cffi-manual.texinfo 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/cffi-manual.texinfo 2008/01/28 23:59:26 1.1 \input texinfo @c -*- Mode: Texinfo; Mode: auto-fill -*- @c %**start of header @setfilename cffi.info @settitle CFFI User Manual @exampleindent 2

@c @documentencoding utf-8

@ignore Style notes:

* The reference section names and "See Also" list are roman, not @code. This is to follow the format of CLHS.

* How it looks in HTML is the priority. @end ignore

@c ============================= Macros ============================= @c The following macros are used throughout this manual.

@macro Function {args} @defun \args\ @end defun @end macro

@macro Macro {args} @defmac \args\ @end defmac @end macro

@macro Accessor {args} @deffn {Accessor} \args\ @end deffn @end macro

@macro GenericFunction {args} @deffn {Generic Function} \args\ @end deffn @end macro

@macro ForeignType {args} @deftp {Foreign Type} \args\ @end deftp @end macro

@macro Variable {args} @defvr {Special Variable} \args\ @end defvr @end macro

@macro Condition {args} @deftp {Condition Type} \args\ @end deftp @end macro

@macro cffi @acronym{CFFI} @end macro

@macro impnote {text} @quotation @strong{Implementor's note:} @emph{\text} @end quotation @end macro

@c Info "requires" that x-refs end in a period or comma, or ) in the @c case of @pxref. So the following implements that requirement for @c the "See also" subheadings that permeate this manual, but only in @c Info mode. @ifinfo @macro seealso {name} @ref{\name}. @end macro @end ifinfo

@ifnotinfo @alias seealso = ref @end ifnotinfo

@c Set ROMANCOMMENTS to get comments in roman font. @ifset ROMANCOMMENTS @alias lispcmt = r @end ifset @ifclear ROMANCOMMENTS @alias lispcmt = asis @end ifclear

@c ============================= Macros =============================

@c Show types, functions, and concepts in the same index. @syncodeindex tp cp @syncodeindex fn cp

@copying Copyright @copyright{} 2005 James Bielman <jamesjb at jamesjb.com> @* Copyright @copyright{} 2005, 2006 Lu@'{@dotless{i}}s Oliveira <loliveira at common-lisp.net> @* Copyright @copyright{} 2006 Stephen Compall <s11 at member.fsf.org>

@quotation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ``Software''), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

@sc{The software is provided ``as is'', without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.} @end quotation @end copying @c %**end of header

@titlepage @title CFFI User Manual @c @subtitle Version X.X @c @author James Bielman

@page @vskip 0pt plus 1filll @insertcopying @end titlepage

@contents

@ifnottex @node Top @top cffi @insertcopying @end ifnottex

@menu * Introduction:: What is CFFI? * Implementation Support:: * Tutorial:: Interactive intro to using CFFI. * Wrapper generators:: CFFI forms from munging C source code. * Foreign Types:: * Pointers:: * Strings:: * Variables:: * Functions:: * Libraries:: * Callbacks:: * Finalizers:: * Limitations:: * Platform-specific features:: Details about the underlying system. * Glossary:: List of CFFI-specific terms and meanings. * Comprehensive Index::

@detailmenu --- Dictionary ---

Foreign Types

* convert-from-foreign:: Outside interface to backward type translator. * convert-to-foreign:: Outside interface to forward type translator. * defbitfield:: Defines a bitfield. * defcstruct:: Defines a C structure type. * defcunion:: Defines a C union type. * defctype:: Defines a foreign typedef. * defcenum:: Defines a C enumeration. @c * define-type-spec-parser:: <should be exported?> * define-foreign-type:: Defines a foreign type specifier. @c * explain-foreign-slot-value:: <unimplemented> * foreign-bitfield-symbols:: Returns a list of symbols for a bitfield type. * foreign-bitfield-value:: Calculates a value for a bitfield type. * foreign-enum-keyword:: Finds a keyword in an enum type. * foreign-enum-value:: Finds a value in an enum type. * foreign-slot-names:: Returns a list of slot names in a foreign struct. * foreign-slot-offset:: Returns the offset of a slot in a foreign struct. * foreign-slot-pointer:: Returns a pointer to a slot in a foreign struct. * foreign-slot-value:: Returns the value of a slot in a foreign struct. * foreign-type-alignment:: Returns the alignment of a foreign type. * foreign-type-size:: Returns the size of a foreign type. * free-converted-object:: Outside interface to typed object deallocators. * free-translated-object:: Free a type translated foreign object. * translate-from-foreign:: Translate a foreign object to a Lisp object. * translate-to-foreign:: Translate a Lisp object to a foreign object. * with-foreign-object:: Allocates a foreign object with dynamic extent. * with-foreign-slots:: Access the slots of a foreign structure.

Pointers

* foreign-free:: Deallocates memory. * foreign-alloc:: Allocates memory. * foreign-symbol-pointer:: Returns a pointer to a foreign symbol. * inc-pointer:: Increments the address held by a pointer. * make-pointer:: Returns a pointer to a given address. * mem-aref:: Accesses the value of an index in an array. * mem-ref:: Dereferences a pointer. * null-pointer:: Returns a NULL pointer. * null-pointer-p:: Tests a pointer for NULL value. * pointerp:: Tests whether an object is a pointer or not. * pointer-address:: Returns the address pointed to by a pointer. * pointer-eq:: Tests if two pointers point to the same address. * with-foreign-pointer:: Allocates memory with dynamic extent.

Strings

* foreign-string-alloc:: Converts a Lisp string to a foreign string. * foreign-string-free:: Deallocates memory used by a foreign string. * foreign-string-to-lisp:: Converts a foreign string to a Lisp string. * lisp-string-to-foreign:: Copies a Lisp string into a foreign string. * with-foreign-string:: Allocates a foreign string with dynamic extent. * with-foreign-pointer-as-string:: Similar to CL's with-output-to-string.

Variables

* defcvar:: Defines a C global variable. * get-var-pointer:: Returns a pointer to a defined global variable.

Functions

* defcfun:: Defines a foreign function. * foreign-funcall:: Performs a call to a foreign function.

[5407 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/cffi-sys-spec.texinfo 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/cffi-sys-spec.texinfo 2008/01/28 23:59:26 1.1

[5718 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/colorize-lisp-examples.lisp 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/colorize-lisp-examples.lisp 2008/01/28 23:59:26 1.1

[6769 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/gendocs.sh 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/gendocs.sh 2008/01/28 23:59:26 1.1

[7079 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/gendocs_template 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/gendocs_template 2008/01/28 23:59:26 1.1

[7338 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/mem-vector.txt 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/mem-vector.txt 2008/01/28 23:59:26 1.1

[7413 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/shareable-vectors.txt 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/shareable-vectors.txt 2008/01/28 23:59:26 1.1

[7457 lines skipped] --- /project/cells/cvsroot/cells-gtk/cffi/doc/style.css 2008/01/28 23:59:26 NONE +++ /project/cells/cvsroot/cells-gtk/cffi/doc/style.css 2008/01/28 23:59:26 1.1

[7505 lines skipped]