From 90e1b1bc1629e3acd2518e26a7655be480604e4b Mon Sep 17 00:00:00 2001
From: rrt <unknown>
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 000000000000..a811c4fc9675
--- /dev/null
+++ b/ghc/docs/users_guide/ffi-chap.sgml
@@ -0,0 +1,6 @@
+<!-- FFI docs as a chapter -->
+
+<Chapter id="ffi">
+<Title>Foreign interface</Title>
+&ffi-body;
+</Chapter>
diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index e1467fa69ca8..904e4707d7cc 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
</VarListEntry>
<VarListEntry>
-<Term>Calling out to C:</Term>
+<Term>Foreign calling:</Term>
<ListItem>
<Para>
Just what it sounds like. We provide <Emphasis>lots</Emphasis> of rope that you
-can dangle around your neck. Please see <XRef LinkEnd="glasgow-ccalls">.
+can dangle around your neck. Please see <XRef LinkEnd="ffi">.
</Para>
</ListItem>
</VarListEntry>
@@ -1476,152 +1476,15 @@ qualifier list has just one element, a boolean expression.
</Para>
</Sect1>
-
-<Sect1 id="glasgow-ccalls">
-<Title>Calling C directly from Haskell</Title>
-
-<Para>
-<IndexTerm><Primary>C calls (Glasgow extension)</Primary></IndexTerm>
-<IndexTerm><Primary>_ccall_ (Glasgow extension)</Primary></IndexTerm>
-<IndexTerm><Primary>_casm_ (Glasgow extension)</Primary></IndexTerm>
-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.
-</Para>
-
-<Sect2 id="ccall-intro">
-<Title><Function>_ccall_</Function> and <Function>_casm_</Function>: an introduction
-</Title>
-
-<Para>
-The simplest way to use a simple C function
-</Para>
-
-<Para>
-
-<ProgramListing>
-double fooC( FILE *in, char c, int i, double d, unsigned int u )
-</ProgramListing>
-
-</Para>
-
-<Para>
-is to provide a Haskell wrapper:
-</Para>
-
-<Para>
-
-<ProgramListing>
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w
-</ProgramListing>
-
-</Para>
-
-<Para>
-The function <Function>fooH</Function> unbox all of its arguments, call the C
-function <Function>fooC</Function> and box the corresponding arguments.
-</Para>
-
-<Para>
-One of the annoyances about <Function>_ccall_</Function>s is when the C types don't quite
-match the Haskell compiler's ideas. For this, the <Function>_casm_</Function> variant
-may be just the ticket (NB: <Emphasis>no chance</Emphasis> of such code going
-through a native-code generator):
-</Para>
-
-<Para>
-
-<ProgramListing>
-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)
- )
-</ProgramListing>
-
-</Para>
-
-<Para>
-The first literal-literal argument to a <Function>_casm_</Function> is like a <Function>printf</Function>
-format: <Literal>%r</Literal> is replaced with the “result,” <Literal>%0</Literal>–<Literal>%n-1</Literal> 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 <Function>_ccall_</Function> goes
-for <Function>_casm_</Function> as well.
-</Para>
-
-<Para>
-The use of <Function>_casm_</Function> 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 <Function>_casm_</Function>, its unfolding will <Emphasis>not</Emphasis> 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 <Function>_casm_</Function>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 <Function>_casm_</Function>, 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 <Function>_casm_</Function> 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.
-</Para>
+<Sect1 id="sec-ffi">
+<Title>The foreign interface</Title>
<Para>
-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
-<Option>-funfold-casms-in-hi-file</Option> will turn off the default behaviour.
-<IndexTerm><Primary>-funfold-casms-in-hi-file option</Primary></IndexTerm>
+The foreign interface consists of language and library support. The former
+is described later in <XRef LinkEnd="ffi">; the latter is outlined below,
+and detailed in the hslibs documentation.
</Para>
-</Sect2>
-
-<Sect2 id="glasgow-literal-literals">
-<Title>Literal-literals</Title>
-
-<Para>
-<IndexTerm><Primary>Literal-literals</Primary></IndexTerm>
-The literal-literal argument to <Function>_casm_</Function> can be made use of separately
-from the <Function>_casm_</Function> construct itself. Indeed, we've already used it:
-</Para>
-
-<Para>
-
-<ProgramListing>
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w
-</ProgramListing>
-
-</Para>
-
-<Para>
-The first argument that's passed to <Function>fooC</Function> is given as a literal-literal,
-that is, a literal chunk of C code that will be inserted into the generated
-<Filename>.hc</Filename> code at the right place.
-</Para>
-
-<Para>
-A literal-literal is restricted to having a type that's an instance of
-the <Literal>CCallable</Literal> class, see <XRef LinkEnd="ccall-gotchas">
-for more information.
-</Para>
-
-<Para>
-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.
-</Para>
-
-</Sect2>
-
<Sect2 id="glasgow-foreign-headers">
<Title>Using function headers
</Title>
@@ -2340,7 +2203,7 @@ stuff is hairy with a capital H!
</Title>
<Para>
-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 <ULink
URL="http://research.microsoft.com/~simonpj/multi.ps.gz" >Type
classes: exploring the design space</ULink > (Simon Peyton Jones, Mark
diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml
index f7515e105c1b..b95b2dd6d610 100644
--- a/ghc/docs/users_guide/gone_wrong.sgml
+++ b/ghc/docs/users_guide/gone_wrong.sgml
@@ -220,11 +220,12 @@ please see <XRef LinkEnd="sooner-faster-quicker">).
</Para>
<Para>
-If your program has no <Function>_ccall_</Function>s/<Function>_casm_</Function>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 <Filename>.hi-boot</Filename> files, in which
-case these <Emphasis>must</Emphasis> 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 <Filename>.hi-boot</Filename> files, in which case
+these <Emphasis>must</Emphasis> be correct with respect to the module
+source).
</Para>
<Para>
@@ -270,7 +271,7 @@ So, before you report a bug because of a core dump, you should probably:
</Para>
<Para>
-Of course, if you have <Function>_ccall_</Function>s/<Function>_casm_</Function>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.
</Para>
diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml
index 54ad5f1ba431..c2c3333aaa43 100644
--- a/ghc/docs/users_guide/sooner.sgml
+++ b/ghc/docs/users_guide/sooner.sgml
@@ -456,7 +456,7 @@ types.
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term>Use <Function>_ccall_s</Function> (a GHC extension) to plug into fast libraries:</Term>
+<Term>Use <Literal>foreign import</Literal> (a GHC extension) to plug into fast libraries:</Term>
<ListItem>
<Para>
This may take real work, but… There exist piles of
@@ -465,7 +465,7 @@ to compete with it, but link with it.
</Para>
<Para>
-<XRef LinkEnd="glasgow-ccalls"> says a little about how to use C calls.
+<XRef LinkEnd="sec-ffi"> describes the foreign calling interface.
</Para>
</ListItem>
</VarListEntry>
diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml
index c80f33cd80ac..c2ee648ac2db 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 bd30920a3ec8..341278119d10 100644
--- a/ghc/docs/users_guide/ug-ent.sgml
+++ b/ghc/docs/users_guide/ug-ent.sgml
@@ -14,3 +14,5 @@
<!ENTITY wrong SYSTEM "gone_wrong.sgml" >
<!ENTITY utils SYSTEM "utils.sgml" >
<!ENTITY win32-dll SYSTEM "win32-dlls.sgml">
+<!ENTITY ffi-body SYSTEM "../../../docs/ffi.sgml">
+<!ENTITY ffi-chap SYSTEM "ffi-chap.sgml">
diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index cfce8853376f..4819a99337a4 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 <Emphasis>might</Emphasi
</Para>
<Para>
-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 <Function>_ccall_gc_</Function>s or
-<Function>_casm_</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
+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 <Function>_casm_</Function>s (which are utterly
+deprecated), you probably <Emphasis>have</Emphasis> to use
+<Option>-fvia-C</Option>.
</Para>
<Para>
@@ -2068,7 +2070,7 @@ THIS MAY CHANGE. Meanwhile, options so sent are:
</Para>
<Para>
-If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
+If you are compiling with lots of foreign calls, you may need to
tell the C compiler about some <Literal>#include</Literal> files. There is no real
pretty way to do this, but you can use this hack from the
command-line:
--
GitLab