X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fffi.sgml;h=5f11eabebbebd742da6ad968749112bbb18fc586;hb=d4b738d6c0b354de817fa490b50814e40872b3d0;hp=e48d16cf77df9b57a23a1a90292a7af2d87feb41;hpb=b624a686af5426145841a597bdb96b27d5bd042e;p=sbcl.git
diff --git a/doc/ffi.sgml b/doc/ffi.sgml
index e48d16c..5f11eab 100644
--- a/doc/ffi.sgml
+++ b/doc/ffi.sgml
@@ -42,13 +42,13 @@ are three common approaches to establishing communication:
-&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>.
@@ -294,6 +294,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
@@ -363,7 +366,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 +429,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 +438,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,
@@ -688,19 +721,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
@@ -864,15 +901,30 @@ 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.
+