X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fffi.sgml;h=b36026189715e9280029f5036ba13fffedef6d72;hb=592ecf78ec904eea390ca67dbacf00d486276c58;hp=e48d16cf77df9b57a23a1a90292a7af2d87feb41;hpb=b624a686af5426145841a597bdb96b27d5bd042e;p=sbcl.git
diff --git a/doc/ffi.sgml b/doc/ffi.sgml
index e48d16c..b360261 100644
--- a/doc/ffi.sgml
+++ b/doc/ffi.sgml
@@ -41,14 +41,15 @@ are three common approaches to establishing communication:
objects through the use of extensions to the Lisp language.
+
-&SBCL;, like &CMUCL; before it,
-relies primarily on the automatic conversion and direct manipulation
-approaches. Foreign values of simple scalar types are automatically
-converted, complex types are directly manipulated in their foreign
-representation. Furthermore, Lisp strings are represented internally
-with null termination bytes so that they can be passed directly to
-C interfaces without allocating new zero-terminated copies.
+&SBCL;, like &CMUCL; before it, relies primarily on the
+automatic conversion and direct manipulation approaches. The SB-ALIEN
+package provices a facility wherein foreign values of simple scalar
+types are automatically converted and complex types are directly
+manipulated in their foreign representation. Additionally the
+lower-level System Area Pointers (or SAPs) can be used where
+necessary to provide untyped access to foreign memory.
Any foreign objects that can't automatically be converted into
Lisp values are represented by objects of type alien-value>.
@@ -207,7 +208,7 @@ These are the basic foreign type specifiers:
value> is an integer. If value> is not
supplied, then it defaults to one greater than the value for
the preceding spec (or to zero if it is the first spec.)
-
+
@@ -294,6 +295,9 @@ These are the basic foreign type specifiers:
null-terminated string, and is automatically converted into a
Lisp string when accessed; or if the pointer is C NULL>
or 0>, then accessing it gives Lisp nil>.
+ Lisp strings are stored with a trailing NUL termination, so no
+ copying (either by the user or the implementation) is necessary
+ when passing them to foreign code.
Assigning a Lisp string to a c-string> structure field or
@@ -330,6 +334,10 @@ These are the basic foreign type specifiers:
+
+
+
+
Operations On Foreign Values>
@@ -363,7 +371,41 @@ a new value. Note that slot-name> is evaluated, and need
not be a compile-time constant (but only constant slot accesses are
efficiently compiled.)
-
+Untyped memory>
+
+As noted at the beginning of the chapter, the System Area
+Pointer facilities allow untyped access to foreign memory. SAPs can
+be converted to and from the usual typed foreign values using
+sap-alien and alien-sap
+(described elsewhere), and also to and from integers - raw machine
+addresses. They should thus be used with caution; corrupting the Lisp
+heap or other memory with SAPs is trivial.
+
+(sb-sys:int-sap machine-address)>
+
+Creates a SAP pointing at the virtual address
+machine-address.
+
+(sb-sys:sap-ref-32 sap offset)>
+
+Access the value of the memory location at
+offset bytes from sap. This form
+may also be used with setf to alter the memory at
+that location.
+
+(sb-sys:sap= sap1 sap2)>
+
+Compare sap1 and sap2 for
+equality.
+
+Similarly named functions exist for accessing other sizes of
+word, other comparisons, and other conversions. The reader is invited
+to use apropos and describe
+for more details
+
+(apropos "sap" :sb-sys)
+
+
Coercing Foreign Values>
@@ -392,8 +434,6 @@ argument, but it does refer to the same foreign data bits.
The sb-alien:sap-alien> function converts sap>
(a system area pointer) to a foreign value with the specified
type>. type> is not evaluated.
-As of &SBCL; 0.7.6, it looks as though this and other SAP functionality
-may become deprecated, since it shouldn't be needed by user code.
The type> must be some foreign pointer, array, or
@@ -403,8 +443,6 @@ record type.
The sb-alien:alien-sap> function
returns the SAP which points to alien-value>'s data.
-As of &SBCL; 0.7.6, it looks as though this and other SAP functionality
-may become deprecated, since it shouldn't be needed by user code.
The foreign-value> must be of some foreign pointer,
@@ -465,6 +503,8 @@ or C malloc>.
See also the sb-alien:with-alien> macro, which
allocates foreign values on the stack.
+
+
Foreign Variables>
@@ -528,6 +568,7 @@ macros extern-alien>, define-alien-variable> and
separately specified by using a list of the form
(alien-string lisp-symbol)>
+
(sb-alien:define-alien-variable name type)>
@@ -579,6 +620,8 @@ and may be either a string or a symbol. type> is
an unevaluated alien type specifier.
+
+
Foreign Data Structure Examples>
@@ -688,19 +731,23 @@ code when a saved core is loaded.
The foreign function call interface allows a Lisp program to call
-functions written in other languages using the C calling convention.
+many functions written in languages that use the C calling convention.
-Lisp sets up various interrupt handling routines and other environment
+Lisp sets up various signal handling routines and other environment
information when it first starts up, and expects these to be in place
-at all times. The C functions called by Lisp should either not change
-the environment, especially the interrupt entry points, or should make
-sure that these entry points are restored when the C function returns
-to Lisp. If a C function makes changes without restoring things to the
-way they were when the C function was entered, there is no telling
-what will happen.
-
+at all times. The C functions called by Lisp should not change the
+environment, especially the signal handlers: the signal handlers
+installed by Lisp typically have interesting flags set (e.g to request
+machine context information, or for signal delivery on an alternate
+stack) which the Lisp runtime relies on for correct operation.
+Precise details of how this works may change without notice between
+versions; the source, or the brain of a friendly &SBCL; developer,
+is the only documentation. Users of a Lisp built with the :sb-thread
+feature should also read the Threading section
+
+of this manual
The alien-funcall> Primitive
@@ -728,6 +775,7 @@ known-type calls are efficiently compiled. Limitations:
Structure type return values are not implemented.>>
Passing of structures by value is not implemented.>>
+
Here is an example which allocates a (struct foo)>, calls a foreign
@@ -851,6 +899,7 @@ This can be described by the following call to
The Lisp function cfoo> will have
two arguments (str> and a>)
and two return values (a> and i>).
+
@@ -864,15 +913,32 @@ the runtime system. The
arguments must be valid &SBCL; object descriptors (so that
e.g. fixnums must be
left-shifted by 2.) As of &SBCL; 0.7.5, the format
-of object descriptors is documented only by the source code and
+of object descriptors is documented only by the source code and, in parts,
by the old &CMUCL; "INTERNALS" documentation.
Note that the garbage collector moves objects, and won't be
-able to fix up any references in C variables, so either turn GC off or
-don't keep Lisp pointers in C data unless they are to statically
-allocated objects. It is possible to use the
-sb-ext:purify> function to place live data structures in
-static space so that they won't move during GC.
+able to fix up any references in C variables. There are three
+mechanisms for coping with this:
+
+
+The sb-ext:purify> moves all live Lisp
+data into static or read-only areas such that it will never be moved
+(or freed) again in the life of the Lisp session
+
+sb-sys:with-pinned-objects is a
+macro which arranges for some set of objects to be pinned in memory
+for the dynamic extent of its body forms. On ports which use the
+generational garbage collector (as of &SBCL; 0.8.3, only the x86) this
+has a page granularity - i.e. the entire 4k page or pages containing
+the objects will be locked down. On other ports it is implemented by
+turning off GC for the duration (so could be said to have a
+whole-world granularity).
+
+Disable GC, using the without-gcing
+macro or gc-off call.
+
+
+
+
+
Step-By-Step Example of the Foreign Function Interface>
@@ -1041,7 +1115,7 @@ struct c_struct *c_function (i, s, r, a)
printf("s = %s\n", s);
printf("r->x = %d\n", r->x);
printf("r->s = %s\n", r->s);
- for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
+ for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
r2->x = i + 5;
r2->s = "a C string";
@@ -1118,6 +1192,7 @@ Within Lisp,
compile the Lisp file. (This step can be done separately. You don't
have to recompile every time.)
(compile-file "test.lisp")>
+
Within Lisp, load the foreign object file to define the necessary
@@ -1125,7 +1200,7 @@ symbols:
(load-foreign "test.o")>.
This must be done before loading any code that refers
to these symbols.
-
+
Now you can load the compiled Lisp ("fasl") file into Lisp: