X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fffi.sgml;h=fc53a3d4f02682bd8aa1878e5b457533256ddd6e;hb=8223bac632c3be67018ae6b29ceab89167dcffa5;hp=4f3e0770ba2889dd89244b03909ecaf002c1461a;hpb=05ba5565f3de8fa29e3066d97b6825d93c1f3906;p=ghc-hetmet.git
diff --git a/docs/ffi.sgml b/docs/ffi.sgml
index 4f3e077..fc53a3d 100644
--- a/docs/ffi.sgml
+++ b/docs/ffi.sgml
@@ -3,28 +3,76 @@
-The motivation behind this foreign function interface(FFI)
-specification is to make it possible to describe in Haskell source
-code the interface to foreign functionality in a Haskell system
-independent manner. It builds on experiences made with the previous
-foreign function interfaces provided by GHC and Hugs.
+The motivation behind this foreign function interface (FFI) specification is
+to make it possible to describe in Haskell source code
+the interface to foreign functionality in a Haskell system independent
+manner. It builds on experiences made with the previous foreign function
+interfaces provided by GHC and Hugs. However, the FFI specified in this
+document is not in the market of trying to completely bridge the gap between
+the actual type of an external function, and what is a
+convenient type for that function to the Haskell
+programmer. That is the domain of tools like HaskellDirect or Green Card, both
+of which are capable of generating Haskell code that uses this FFI.
-The FFI specified in this document is not in the market of trying to
-completely bridge the gap between the actual type of an external
-function, and what is a convenient type for that function to the
-Haskell programmer. That is the domain of tools like HaskellDirect or
-Green Card, both of which are capable of generating Haskell code that
-uses this FFI.
+Generally, the FFI consists of three parts:
+
+
+
+
+extensions to the base language Haskell 98 (most notably foreign
+import and foreign export declarations), which
+are specified in the present document,
+
+
+
+
+
+a low-level marshalling library, which is part of the
+Language part of the Haskell Extension
+Library (see ), and a
+
+
+
+
+
+a high-level marshalling library, which is still under development.
+
+
+
+
+Before diving into the details of the language extension coming with the FFI,
+let us briefly outline the two other components of the interface.
+
+
+
+The low-level marshalling library consists of a portion that is independent of
+the targeted foreign language and dedicated support for Haskell bindings to C
+libraries (special support for other languages may be added in the future).
+The language independent part is given by the module
+Foreign module (see ). It
+provides support for handling references to foreign structures, for passing
+references to Haskell structures out to foreign routines, and for storing
+primitive data types in raw memory blocks in a portable manner. The support
+for C libraries essentially provides Haskell representations for all basic
+types of C (see and ).
-The FFI can be split up into two complementary halves; one half that
-provides Haskell constructs for importing foreign functionality into
-Haskell, the other which lets you expose Haskell functions to the
-outside world. We start with the former, how to import external
-functionality into Haskell.
+The high-level library, of which the interface definition is not yet
+finalised, provides routines for marshalling complex Haskell structures as
+well as handling out and in-out parameters in a convenient, yet protable way.
+
+
+
+In the following, we will discuss the language extensions of the FFI (ie, the
+first point above). They can be split up into two complementary halves; one
+half that provides Haskell constructs for importing foreign functionality into
+Haskell, the other which lets you expose Haskell functions to the outside
+world. We start with the former, how to import external functionality into
+Haskell.
@@ -610,9 +658,7 @@ defines the mapping between Haskell and C types.
Mapping of Haskell types to C types
-
-
-
+
@@ -631,90 +677,80 @@ defines the mapping between Haskell and C types.
Char
HsChar
unspec. integral type
- HS_CHAR_MIN
-..
- HS_CHAR_MAX
+ HS_CHAR_MIN .. HS_CHAR_MAX
Int
HsInt
signed integral of unspec. size(4)
- HS_INT_MIN
-..
- HS_INT_MAX
+ HS_INT_MIN ..
+HS_INT_MAX
Int8 (2)
HsInt8
8 bit signed integral
- HS_INT8_MIN
-..
- HS_INT8_MAX
+ HS_INT8_MIN
+..
+HS_INT8_MAX
Int16 (2)
HsInt16
16 bit signed integral
- HS_INT16_MIN
-..
- HS_INT16_MAX
+ HS_INT16_MIN
+.. HS_INT16_MAX
Int32 (2)
HsInt32
32 bit signed integral
- HS_INT32_MIN
-..
- HS_INT32_MAX
+ HS_INT32_MIN ..
+HS_INT32_MAX
Int64 (2,3)
HsInt64
64 bit signed integral (3)
- HS_INT64_MIN
-..
- HS_INT64_MAX
+ HS_INT64_MIN ..
+HS_INT64_MAX
Word8 (2)
HsWord8
8 bit unsigned integral
- 0
-..
- HS_WORD8_MAX
+ 0 ..
+HS_WORD8_MAX
Word16 (2)
HsWord16
16 bit unsigned integral
- 0
-..
- HS_WORD16_MAX
+ 0 ..
+HS_WORD16_MAX
Word32 (2)
HsWord32
32 bit unsigned integral
- 0
-..
- HS_WORD32_MAX
+ 0 ..
+HS_WORD32_MAX
Word64 (2,3)
HsWord64
64 bit unsigned integral (3)
- 0
-..
- HS_WORD64_MAX
+ 0 ..
+HS_WORD64_MAX
@@ -722,8 +758,6 @@ defines the mapping between Haskell and C types.
HsFloat
floating point of unspec. size (5)
(10)
-
-
@@ -731,8 +765,6 @@ defines the mapping between Haskell and C types.
HsDouble
floating point of unspec. size (5)
(10)
-
-
@@ -740,8 +772,6 @@ defines the mapping between Haskell and C types.
HsBool
unspec. integral type
(11)
-
-
@@ -749,8 +779,6 @@ defines the mapping between Haskell and C types.
HsAddr
void* (6)
-
-
@@ -758,8 +786,6 @@ defines the mapping between Haskell and C types.
HsForeignObj
void* (7)
-
-
@@ -767,12 +793,6 @@ defines the mapping between Haskell and C types.
HsStablePtr
void* (8)
-
-
-
-
-
-
@@ -954,7 +974,7 @@ foreign import "mumble" mumble :: ForeignObj -> IO ()
f :: Addr -> IO ()
f ptr = do
- fo <- makeForeignObj ptr myFinalizer
+ fo <- newForeignObj ptr myFinalizer
mumble fo
@@ -1307,7 +1327,7 @@ contain the address of the label freeAtLast.
-
+