Commit ca3697b6 authored by Daniel Kochmański's avatar Daniel Kochmański

new-doc: ffi: uffi step

parent 5a6ae928
@node Foreign Function Interface
@section Foreign Function Interface
@cindex Foreign function interface
@ftindex FFI
@menu
* What is a FFI? :: FFI introduciton
......@@ -8,12 +10,11 @@
* Higher level interfaces :: Usage examples
* SFFI Reference :: Static FFI reference
@c * LFFI Reference :: Library FFI reference
* DFFI Reference :: Dynamic FFI reference
@c * DFFI Reference :: Dynamic FFI reference
* UFFI Reference :: UFFI reference manual
@end menu
@node What is a FFI?
@cindex Foreign function interface
@subsection What is a FFI?
A Foreign Function Interface, or FFI for short, is a means for a programming language to
interface with libraries written in other programming languages, the foreign code. You will
......@@ -298,5 +299,5 @@ Build and load this module with (compile-file "ecl.lsp" :load t)
@end lisp
@include extensions/ffi_sffi.txi
@node DFFI Reference
@c @include extensions/ffi_dffi.txi
@include extensions/ffi_uffi.txi
......@@ -2,20 +2,19 @@
@subsection SFFI Reference
@cindex C/C++ code inlining
@subsubheading @code{ffi:clines} — Insert C declarations and definitions
@lspindex ffi:clines
@defspec ffi:clines c/c++-code*
Insert C declarations and definitions
@table @var
@item c/c++-code
One or more strings with C definitions. Not evaluated.
@item returns
No value.
@end table
@end defspec
@strong{Description}
@subsubheading Description
This special form inserts C code from strings passed in the
@var{arguments} directly in the file that results from compiling lisp
sources. Contrary to @code{ffi:c-inline}, this function may have no
......@@ -30,8 +29,7 @@ beginning of the produced header file.
compiled files as a toplevel form. Other uses will lead to an error
being signaled, either at the compilation time or when loading the file.
@strong{Examples}
@subsubheading Examples
@exindex @code{ffi:clines} adding c toplevel declarations
In this example the FFI:CLINES statement is required to get access to
the C function @code{cos}:
......@@ -40,12 +38,14 @@ the C function @code{cos}:
(defun cos (x)
(ffi:c-inline (x) (:double) :double "cos(#0)" :on-liner t))
@end lisp
@end defspec
@subsubheading @code{ffi:c-inline} — Inline C code in a lisp form
@lspindex ffi:c-inline
@defspec ffi:c-inline (lisp-values) (arg-c-types) return-type c/c++-code @
&key (side-effects t) (one-liner nil)
Inline C code in a lisp form
@table @var
@item lisp-values
One or more lisp expressions. Evaluated.
......@@ -64,10 +64,8 @@ T.
@item returns
One or more lisp values.
@end table
@end defspec
@strong{Description}
@subsubheading Description
This is a special form which can be only used in compiled code and whose
purpose is to execute some C code getting and returning values from and
to the lisp environment.
......@@ -105,8 +103,7 @@ Note that the conversion between lisp arguments and FFI types is
automatic. Note also that @code{ffi:c-inline} cannot be used in
interpreted or bytecompiled code! Such usage will signal an error.
@strong{Examples}
@subsubheading Examples
@exindex @code{ffi:c-inline} inlining c code
The following example implements the transcendental function SIN using
the C equivalent:
......@@ -152,27 +149,27 @@ and two output values:
:side-effects nil))
@end verbatim
@end lisp
@end defspec
@subsubheading ffi:c-progn – Interleave C statements with the Lisp code
@lspindex ffi:c-progn
@defspec ffi:c-progn args &body body
Interleave C statements with the Lisp code
@table @var
@item args
Lisp arguments. Evaluated.
@item returns
No value.
@end table
@end defspec
@strong{Description}
@subsubheading Description
This form is used for it's side effects. It allows for interleaving C
statements with the Lisp code. The argument types doesn't have to be
declared – in such case the objects type in the C world will be
@code{cl_object}.
@strong{Examples}
@subsubheading Examples
@exindex @code{ffi:c-progn} interleaving c and lisp code
@lisp
@verbatim
......@@ -189,57 +186,60 @@ declared – in such case the objects type in the C world will be
"}")))
@end verbatim
@end lisp
@end defspec
@c XXX: SFFI returns one-element list pointer, while DFFI returns just a
@c pointer. This is probably a bug.
@subsubheading ffi:defcallback
@lspindex ffi:defcallback
@defspec ffi:defcallback name ret-type arg-desc &body body
@table @var
@item name
Name of the lisp function.
@item ret-type
Declaration of the return type which function returns.
@item arg-desc
List of pairs @code{(arg-name arg-type)}.
@item body
Function body.
@item returns
Pointer to the defined callback.
@end table
@end defspec
@strong{Description}
@subsubheading Description
Defines Lisp function and generates a callback for the C world, which
may be passed to these functions. Note, that this special operator has
also a dynamic variant (with the same name and interface).
@end defspec
@subsubheading ffi:defcbody
@lspindex ffi:defcbody
@defmac ffi:defcbody name arg-types result-type c-expression
@end defmac
@strong{Description}
Define C function under the lisp name
@table @var
@item name
Defined function name.
@item arg-types
Argument types of the defined Lisp function.
@item result-type
Result type of the C function (may be @code{(values ...)}.
@item returns
Defined function name.
@end table
@subsubheading Description
The compiler defines a Lisp function named by NAME whose body consists
of the C code of the string C-EXPRESSION. In the C-EXPRESSION one can
reference the arguments of the function as @code{#0}, @code{#1}, etc.
The interpreter ignores this form. ARG-TYPES are argument types of the
defined Lisp function and RESULT-TYPE is its return type.
The interpreter ignores this form.
@end defmac
@subsubheading ffi:defentry
@lspindex ffi:defentry
@defmac ffi:defentry name arg-types c-name &key no-interrupts
@table @var
@item name
Lisp name for the function.
......@@ -257,21 +257,19 @@ name is @code{(STRING C-NAME)}.
@item returns
Lisp function @code{NAME}.
@end table
@end defmac
@strong{Description}
@subsubheading Description
The compiler defines a Lisp function named by NAME whose body consists
of a calling sequence to the C language function named by FUNCTION-NAME.
The interpreter ignores this form. ARG-TYPES are argument types of the
C function and RESULT-TYPE is its return type. Symbols OBJECT, INT,
CHAR, CHAR*, FLOAT, DOUBLE are allowed for these types.
@end defmac
@c XXX> note sure if this works
@c @subsubheading ffi:definline
@c @subsubheading @code{definline}
@c @lspindex ffi:definline
@c @defmac ffi:definline fun arg-types result-type code
@c @table @var
......@@ -282,20 +280,19 @@ CHAR, CHAR*, FLOAT, DOUBLE are allowed for these types.
@c @end table
@c @end defmac
@c @strong{Description}
@c @subsubheading Description
@c DEFINLINE behaves like a DEFCBODY (see), but also instructs the LISP
@c compiler to expand inline any call to function SYMBOL into code
@c corresponding to the C language expression C/C++-CODE, whenever it can
@c determine that the actual arguments are of the specified type.
@c <XXX
@subsubheading ffi:defla
@lspindex ffi:defla
@defmac ffi:defla name lambda-list &body body
@end defmac
@defmac ffi:defla name args &body body
@strong{Description}
Provide Lisp alternative for interpreted code.
@subsubheading Description
Used to DEFine Lisp Alternative. For the interpreter, DEFLA is equivalent to
DEFUN, but the compiler ignores this form.
@end defmac
......@@ -2,9 +2,297 @@
@subsection UFFI Reference
@menu
@c * Primitive Types
@c * Aggregate Types
* Primitive Types ::
* Aggregate Types ::
@c * Objects
@c * Strings
@c * Functions and Libraries
@end menu
@node Primitive Types
@subsubsection Primitive Types
@cindex Foreign primitive types
@subsubheading Overview
Primitive types have a single value, these include characters, numbers,
and pointers. They are all symbols in the keyword package.
@lspindex :char
@lspindex :unsigned-char
@lspindex :byte
@lspindex :unsigned-byte
@lspindex :short
@lspindex :unsigned-short
@lspindex :int
@lspindex :unsigned-int
@lspindex :long
@lspindex :unsigned-long
@lspindex :int16_t
@lspindex :uint16_t
@lspindex :int32_t
@lspindex :uint32_t
@lspindex :int64_t
@lspindex :uint64_t
@lspindex :float
@lspindex :double
@c @lspindex :long-double
@lspindex :cstring
@lspindex :void
@lspindex :pointer-void
@lspindex :*
@ftindex LONG-LONG
@ftindex UINT16-T
@ftindex UINT32-T
@ftindex UINT64-T
@ftindex LONG-FLOAT
@table @samp
@item :char
@itemx :unsigned-char
Signed/unsigned 8-bits. Dereferenced pointer returns a character.
@item :byte
@itemx :unsigned-byte
Signed/unsigned 8-bits. Dereferenced pointer returns an integer.
@item :short
@itemx :unsigned-short
@itemx :int
@itemx :unsigned-int
@itemx :long
@itemx :unsigned-long
Standard integer types (16-bit, 32-bit and 32/64-bit).
@item :int16_t
@itemx :uint16_t
@itemx :int32_t
@itemx :uint32_t
@itemx :int64_t
@itemx :uint64_t
Integer types with guaranteed bitness.
@item :float
@itemx :double
Floating point numerals (32-bit and 64-bit).
@c XXX>
@c @item :long-double
@c Floating point numeral (usually 80-bit, at least 64-bit, exact
@c bitness is compiler/architecture/platform dependant).
@c XXX<
@item :cstring
A @code{NULL} terminated string used for passing and returning
characters strings with a C function.
@item :void
The absence of a value. Used to indicate that a function does not return
a value.
@item :pointer-void
Points to a generic object.
@item *
Used to declare a pointer to an object.
@end table
@lspindex ffi:def-constant
@defmac ffi:def-constant name value &key (export nil)
Binds a symbol to a constant.
@table @var
@item name
A symbol that will be bound to the value.
@item value
An evaluated form that is bound the the name.
@item export
When @code{T}, the name is exported from the current package. Defaults
to @code{NIL}.
@item returns
Constant name.
@end table
@subsubheading Description
This is a thin wrapper around @code{defconstant}. It evaluates at
compile-time and optionally exports the symbol from the package.
@subsubheading Examples
@exindex @code{ffi:def-constant} defining constants
@lisp
(ffi:def-constant pi2 (* 2 pi))
(ffi:def-constant exported-pi2 (* 2 pi) :export t)
@end lisp
@subsubheading Side Effects
Creats a new special variable.
@end defmac
@lspindex ffi:def-foreign-type
@defmac ffi:def-foreign-type name definition
Defines a new foreign type
@table @var
@item name
A symbol naming the new foreign type.
@item value
A form that is not evaluated that defines the new foreign type.
@item returns
Foreign type designator (@var{value}).
@end table
@subsubheading Description
Defines a new foreign type
@subsubheading Examples
@exindex @code{ffi:def-foreign-type} examples
@lisp
(def-foreign-type my-generic-pointer :pointer-void)
(def-foreign-type a-double-float :double-float)
(def-foreign-type char-ptr (* :char))
@end lisp
@subsubheading Side effects
Defines a new foreign type.
@end defmac
@lspindex ffi:null-char-p
@defmac ffi:null-char-p char
Tests a character for NULL value
@table @var
@item char
A character or integer.
@item returns
A boolean flag indicating if @var{char} is a NULL value.
@end table
@subsubheading Description
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.
@subsubheading Examples
@exindex @code{ffi:null-char-p} example
@lisp
(ffi:def-array-pointer ca :unsigned-char)
(let ((fs (ffi:convert-to-foreign-string "ab")))
(values (ffi:null-char-p (ffi:deref-array fs 'ca 0))
(ffi:null-char-p (ffi:deref-array fs 'ca 2))))
;; => NIL T
@end lisp
@end defmac
@node Aggregate Types
@subsubsection Aggregate Types
@cindex Foreign aggregate types
@subsubheading Overview
Aggregate types are comprised of one or more primitive types.
@lspindex ffi:def-enum
@defmac ffi:def-enum name fields &key separator-key
Defines a C enumeration
@table @var
@item name
A symbol that names the enumeration.
@item 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.
@item returns
A string that governs the creation of constants. The default is "#".
@end table
@subsubheading 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.
@subsubheading Examples
@exindex @code{ffi:def-enum} sample enumerations
@lisp
(ffi: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
(ffi: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
@end lisp
@subsubheading Side effects
Creates a @code{:int} foreign type, defines constants.
@end defmac
@defmac ffi:def-struct name &rest fields
Defines a C structure
@table @var
@item name
A symbol that names the structure.
@item fields
A variable number of field defintions. Each definition is a list
consisting of a symbol naming the field followed by its foreign type.
@end table
@subsubheading 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 @code{:pointer-self}.
@subsubheading Examples
@exindex @code{ffi:def-struct} defining C structure
@lisp
(ffi:def-struct foo (a :unsigned-int)
(b (* :char))
(c (:array :int 10))
(next :pointer-self))
@end lisp
@subsubheading Side effects
Creates a foreign type.
@end defmac
@lspindex ffi:get-slot-value
@defmac ffi:get-slot-value obj type field
Retrieves a value from a slot of a structure
@table @var
@item obj
A pointer to foreign structure.
@item type
A name of the foreign structure.
@item field
A name of the desired field in foreign structure.
@item returns
The value of the @code{field} in the structure @code{obj}.
@end table
@subsubheading Description
Accesses a slot value from a structure. This is generalized and can be
used with @code{setf}.
@subsubheading Examples
@exindex @code{ffi:get-slot-value} getting and setting C structure field
@lisp
(get-slot-value foo-ptr 'foo-structure 'field-name)
(setf (get-slot-value foo-ptr 'foo-structure 'field-name) 10)
@end lisp
@end defmac
......@@ -73,3 +73,5 @@ Many nodes, moderate amount of content (deviations from the standard)
(ffi:definline …)
#+END_SRC
* Things to fix
- [ ] Add :long-double to the UFFI interface
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment