From 90e1b1bc1629e3acd2518e26a7655be480604e4b Mon Sep 17 00:00:00 2001 From: rrt Date: Thu, 8 Jun 2000 14:36:13 +0000 Subject: [PATCH] [project @ 2000-06-08 14:36:13 by rrt] Added new FFI story from fptools/docs, and removed ccall docs. Pls mrg --- ghc/docs/users_guide/ffi-chap.sgml | 6 ++ ghc/docs/users_guide/glasgow_exts.sgml | 153 ++------------------------------ ghc/docs/users_guide/gone_wrong.sgml | 13 +-- ghc/docs/users_guide/sooner.sgml | 4 +- ghc/docs/users_guide/ug-book.sgml | 1 + ghc/docs/users_guide/ug-ent.sgml | 2 + ghc/docs/users_guide/using.sgml | 12 +-- 7 files changed, 33 insertions(+), 158 deletions(-) create mode 100644 ghc/docs/users_guide/ffi-chap.sgml diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml new file mode 100644 index 0000000..a811c4f --- /dev/null +++ b/ghc/docs/users_guide/ffi-chap.sgml @@ -0,0 +1,6 @@ + + + +Foreign interface +&ffi-body; + diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index e1467fa..904e470 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -85,11 +85,11 @@ Instead of being a boolean expression, a guard is a list of qualifiers, exactly -Calling out to C: +Foreign calling: Just what it sounds like. We provide lots of rope that you -can dangle around your neck. Please see . +can dangle around your neck. Please see . @@ -1476,152 +1476,15 @@ qualifier list has just one element, a boolean expression. - - -Calling C directly from Haskell - - -C calls (Glasgow extension) -_ccall_ (Glasgow extension) -_casm_ (Glasgow extension) -GOOD ADVICE: Because this stuff is not Entirely Stable as far as names -and things go, you would be well-advised to keep your C-callery -corraled in a few modules, rather than sprinkled all over your code. -It will then be quite easy to update later on. - - - -<Function>_ccall_</Function> and <Function>_casm_</Function>: an introduction - - - -The simplest way to use a simple C function - - - - - -double fooC( FILE *in, char c, int i, double d, unsigned int u ) - - - - - -is to provide a Haskell wrapper: - - - - - -fooH :: Char -> Int -> Double -> Word -> IO Double -fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w - - - - - -The function fooH unbox all of its arguments, call the C -function fooC and box the corresponding arguments. - - - -One of the annoyances about _ccall_s is when the C types don't quite -match the Haskell compiler's ideas. For this, the _casm_ variant -may be just the ticket (NB: no chance of such code going -through a native-code generator): - - - - - -import Addr -import CString - -oldGetEnv name - = _casm_ “%r = getenv((char *) %0);” name >>= \ litstring -> - return ( - if (litstring == nullAddr) then - Left ("Fail:oldGetEnv:"++name) - else - Right (unpackCString litstring) - ) - - - - - -The first literal-literal argument to a _casm_ is like a printf -format: %r is replaced with the “result,” %0–%n-1 are -replaced with the 1st–nth arguments. As you can see above, it is an -easy way to do simple C casting. Everything said about _ccall_ goes -for _casm_ as well. - - - -The use of _casm_ in your code does pose a problem to the compiler -when it comes to generating an interface file for a freshly compiled -module. Included in an interface file is the unfolding (if any) of a -declaration. However, if a declaration's unfolding happens to contain -a _casm_, its unfolding will not be emitted into the interface -file even if it qualifies by all the other criteria. The reason why -the compiler prevents this from happening is that unfolding _casm_s -into an interface file unduly constrains how code that import your -module have to be compiled. If an imported declaration is unfolded and -it contains a _casm_, you now have to be using a compiler backend -capable of dealing with it (i.e., the C compiler backend). If you are -using the C compiler backend, the unfolded _casm_ may still cause you -problems since the C code snippet it contains may mention CPP symbols -that were in scope when compiling the original module are not when -compiling the importing module. - + +The foreign interface -If you're willing to put up with the drawbacks of doing cross-module -inlining of C code (GHC - A Better C Compiler :-), the option - will turn off the default behaviour. --funfold-casms-in-hi-file option +The foreign interface consists of language and library support. The former +is described later in ; the latter is outlined below, +and detailed in the hslibs documentation. - - - -Literal-literals - - -Literal-literals -The literal-literal argument to _casm_ can be made use of separately -from the _casm_ construct itself. Indeed, we've already used it: - - - - - -fooH :: Char -> Int -> Double -> Word -> IO Double -fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w - - - - - -The first argument that's passed to fooC is given as a literal-literal, -that is, a literal chunk of C code that will be inserted into the generated -.hc code at the right place. - - - -A literal-literal is restricted to having a type that's an instance of -the CCallable class, see -for more information. - - - -Notice that literal-literals are by their very nature unfriendly to -native code generators, so exercise judgement about whether or not to -make use of them in your code. - - - - Using function headers @@ -2340,7 +2203,7 @@ stuff is hairy with a capital H! -This section documents GHC's implementation of multi-paramter type +This section documents GHC's implementation of multi-parameter type classes. There's lots of background in the paper Type classes: exploring the design space (Simon Peyton Jones, Mark diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index f7515e1..b95b2dd 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -220,11 +220,12 @@ please see ). -If your program has no _ccall_s/_casm_s in it, then a crash is -always a BUG in the GHC system, except in one case: If your program is -made of several modules, each module must have been compiled after any -modules on which it depends (unless you use .hi-boot files, in which -case these must be correct with respect to the module source). +If your program has no foreign calls in it, then a crash is always a BUG in +the GHC system, except in one case: If your program is made of several +modules, each module must have been compiled after any modules on which it +depends (unless you use .hi-boot files, in which case +these must be correct with respect to the module +source). @@ -270,7 +271,7 @@ So, before you report a bug because of a core dump, you should probably: -Of course, if you have _ccall_s/_casm_s in your program then all +Of course, if you have foreign calls in your program then all bets are off, because you can trash the heap, the stack, or whatever. diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml index 54ad5f1..c2c3333 100644 --- a/ghc/docs/users_guide/sooner.sgml +++ b/ghc/docs/users_guide/sooner.sgml @@ -456,7 +456,7 @@ types. -Use _ccall_s (a GHC extension) to plug into fast libraries: +Use foreign import (a GHC extension) to plug into fast libraries: This may take real work, but… There exist piles of @@ -465,7 +465,7 @@ to compete with it, but link with it. - says a little about how to use C calls. + describes the foreign calling interface. diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml index c80f33c..c2ee648 100644 --- a/ghc/docs/users_guide/ug-book.sgml +++ b/ghc/docs/users_guide/ug-book.sgml @@ -13,6 +13,7 @@ &prof &sooner &lang-features +&ffi-chap &wrong &utils &win32-dll diff --git a/ghc/docs/users_guide/ug-ent.sgml b/ghc/docs/users_guide/ug-ent.sgml index bd30920..3412781 100644 --- a/ghc/docs/users_guide/ug-ent.sgml +++ b/ghc/docs/users_guide/ug-ent.sgml @@ -14,3 +14,5 @@ + + diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index cfce885..4819a99 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -1570,10 +1570,12 @@ Here are some “dangerous” optimisations you might -Compile via C, and don't use the native-code generator. (There are -many cases when GHC does this on its own.) You might pick up a little -bit of speed by compiling via C. If you use _ccall_gc_s or -_casm_s, you probably have to use . +Compile via C, and don't use the native-code generator. (There are many +cases when GHC does this on its own.) You might pick up a little bit of +speed by compiling via C (e.g. for floating-point intensive code on Intel). +If you use _casm_s (which are utterly +deprecated), you probably have to use +. @@ -2068,7 +2070,7 @@ THIS MAY CHANGE. Meanwhile, options so sent are: -If you are compiling with lots of ccalls, etc., you may need to +If you are compiling with lots of foreign calls, you may need to tell the C compiler about some #include files. There is no real pretty way to do this, but you can use this hack from the command-line: -- 1.7.10.4