ForeignCall.lhs 7.8 KB
Newer Older
1 2 3 4 5 6
%
% (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
%
\section[Foreign]{Foreign calls}

\begin{code}
7
{-# OPTIONS -w #-}
8 9 10
-- The above warning supression flag is a temporary kludge.
-- While working on this module you are encouraged to remove it and fix
-- any warnings in the module. See
Ian Lynagh's avatar
Ian Lynagh committed
11
--     http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Warnings
12 13
-- for details

14 15
module ForeignCall (
	ForeignCall(..),
16
	Safety(..), playSafe,
17

18
	CExportSpec(..), CLabelString, isCLabelString, pprCLabelString,
19
	CCallSpec(..), 
20
	CCallTarget(..), isDynamicTarget,
21 22 23
	CCallConv(..), defaultCCallConv, ccallConvToInt, ccallConvAttribute,
    ) where

24
import FastString
25
import Binary
26
import Outputable
27
import Module
Ian Lynagh's avatar
Ian Lynagh committed
28 29

import Data.Char
30 31 32 33 34 35 36 37 38 39
\end{code}


%************************************************************************
%*									*
\subsubsection{Data types}
%*									*
%************************************************************************

\begin{code}
40 41
newtype ForeignCall = CCall CCallSpec
  deriving Eq
42
  {-! derive: Binary !-}
43 44 45 46

-- We may need more clues to distinguish foreign calls
-- but this simple printer will do for now
instance Outputable ForeignCall where
chak's avatar
chak committed
47
  ppr (CCall cc)  = ppr cc		
48 49 50 51 52 53 54
\end{code}

  
\begin{code}
data Safety
  = PlaySafe		-- Might invoke Haskell GC, or do a call back, or
			-- switch threads, etc.  So make sure things are
55 56 57 58 59 60 61 62
			-- tidy before the call. Additionally, in the threaded
			-- RTS we arrange for the external call to be executed
			-- by a separate OS thread, i.e., _concurrently_ to the
			-- execution of other Haskell threads.

      Bool              -- Indicates the deprecated "threadsafe" annotation
                        -- which is now an alias for "safe". This information
                        -- is never used except to emit a deprecation warning.
63 64 65

  | PlayRisky		-- None of the above can happen; the call will return
			-- without interacting with the runtime system at all
66
  deriving ( Eq, Show )
67
	-- Show used just for Show Lex.Token, I think
68
  {-! derive: Binary !-}
69 70

instance Outputable Safety where
Ian Lynagh's avatar
Ian Lynagh committed
71 72 73
  ppr (PlaySafe False) = ptext (sLit "safe")
  ppr (PlaySafe True)  = ptext (sLit "threadsafe")
  ppr PlayRisky = ptext (sLit "unsafe")
74

sof's avatar
sof committed
75 76 77
playSafe :: Safety -> Bool
playSafe PlaySafe{} = True
playSafe PlayRisky  = False
78 79 80 81 82 83 84 85 86 87
\end{code}


%************************************************************************
%*									*
\subsubsection{Calling C}
%*									*
%************************************************************************

\begin{code}
88 89 90 91
data CExportSpec
  = CExportStatic		-- foreign export ccall foo :: ty
	CLabelString		-- C Name of exported function
	CCallConv
92
  {-! derive: Binary !-}
93

94 95 96 97 98
data CCallSpec
  =  CCallSpec	CCallTarget	-- What to call
		CCallConv	-- Calling convention to use.
		Safety
  deriving( Eq )
99
  {-! derive: Binary !-}
100 101 102 103 104
\end{code}

The call target:

\begin{code}
105

106
-- | How to call a particular function in C-land.
107
data CCallTarget
108 109 110 111 112 113 114 115 116 117 118
  -- An "unboxed" ccall# to named function in a particular package.
  = StaticTarget  
	CLabelString  			-- C-land name of label.

	(Maybe PackageId)		-- What package the function is in.
					-- If Nothing, then it's taken to be in the current package.
					-- Note: This information is only used for PrimCalls on Windows.
					--	 See CLabel.labelDynamic and CoreToStg.coreToStgApp 
					--	 for the difference in representation between PrimCalls
					--	 and ForeignCalls. If the CCallTarget is representing
					--	 a regular ForeignCall then it's safe to set this to Nothing.
119 120 121 122 123

  -- The first argument of the import is the name of a function pointer (an Addr#).
  --	Used when importing a label as "foreign import ccall "dynamic" ..."
  | DynamicTarget
  
124
  deriving( Eq )
125
  {-! derive: Binary !-}
126

127
isDynamicTarget :: CCallTarget -> Bool
128
isDynamicTarget DynamicTarget = True
Ian Lynagh's avatar
Ian Lynagh committed
129
isDynamicTarget _             = False
130 131 132
\end{code}


133 134 135 136 137 138 139 140 141 142 143
Stuff to do with calling convention:

ccall:		Caller allocates parameters, *and* deallocates them.

stdcall: 	Caller allocates parameters, callee deallocates.
		Function name has @N after it, where N is number of arg bytes
		e.g.  _Foo@8

ToDo: The stdcall calling convention is x86 (win32) specific,
so perhaps we should emit a warning if it's being used on other
platforms.
144 145
 
See: http://www.programmersheaven.com/2/Calling-conventions
146 147

\begin{code}
148
data CCallConv = CCallConv | StdCallConv | CmmCallConv | PrimCallConv
149 150
  deriving (Eq)
  {-! derive: Binary !-}
151 152

instance Outputable CCallConv where
Ian Lynagh's avatar
Ian Lynagh committed
153 154 155
  ppr StdCallConv = ptext (sLit "stdcall")
  ppr CCallConv   = ptext (sLit "ccall")
  ppr CmmCallConv = ptext (sLit "C--")
156
  ppr PrimCallConv = ptext (sLit "prim")
157 158 159 160 161 162 163 164 165 166 167 168 169 170

defaultCCallConv :: CCallConv
defaultCCallConv = CCallConv

ccallConvToInt :: CCallConv -> Int
ccallConvToInt StdCallConv = 0
ccallConvToInt CCallConv   = 1
\end{code}

Generate the gcc attribute corresponding to the given
calling convention (used by PprAbsC):

\begin{code}
ccallConvAttribute :: CCallConv -> String
171
ccallConvAttribute StdCallConv = "__attribute__((__stdcall__))"
172 173 174
ccallConvAttribute CCallConv   = ""
\end{code}

175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
\begin{code}
type CLabelString = FastString		-- A C label, completely unencoded

pprCLabelString :: CLabelString -> SDoc
pprCLabelString lbl = ftext lbl

isCLabelString :: CLabelString -> Bool	-- Checks to see if this is a valid C label
isCLabelString lbl 
  = all ok (unpackFS lbl)
  where
    ok c = isAlphaNum c || c == '_' || c == '.'
	-- The '.' appears in e.g. "foo.so" in the 
	-- module part of a ExtName.  Maybe it should be separate
\end{code}


191 192 193
Printing into C files:

\begin{code}
194 195 196
instance Outputable CExportSpec where
  ppr (CExportStatic str _) = pprCLabelString str

197
instance Outputable CCallSpec where
198 199
  ppr (CCallSpec fun cconv safety)
    = hcat [ ifPprDebug callconv, ppr_fun fun ]
200
    where
201 202 203 204 205
      callconv = text "{-" <> ppr cconv <> text "-}"

      gc_suf | playSafe safety = text "_GC"
	     | otherwise       = empty

206
      ppr_fun (StaticTarget fn Nothing)
207 208
     	= text "__pkg_ccall" <> gc_suf <+> pprCLabelString fn

209
      ppr_fun (StaticTarget fn (Just pkgId))
210 211
     	= text "__pkg_ccall" <> gc_suf <+> ppr pkgId <+> pprCLabelString fn

212 213
      ppr_fun DynamicTarget     
        = text "__dyn_ccall" <> gc_suf <+> text "\"\""
214 215 216
\end{code}


217 218 219 220 221 222
%************************************************************************
%*									*
\subsubsection{Misc}
%*									*
%************************************************************************

223 224 225
\begin{code}
{-* Generated by DrIFT-v1.0 : Look, but Don't Touch. *-}
instance Binary ForeignCall where
226 227
    put_ bh (CCall aa) = put_ bh aa
    get bh = do aa <- get bh; return (CCall aa)
228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262

instance Binary Safety where
    put_ bh (PlaySafe aa) = do
	    putByte bh 0
	    put_ bh aa
    put_ bh PlayRisky = do
	    putByte bh 1
    get bh = do
	    h <- getByte bh
	    case h of
	      0 -> do aa <- get bh
		      return (PlaySafe aa)
	      _ -> do return PlayRisky

instance Binary CExportSpec where
    put_ bh (CExportStatic aa ab) = do
	    put_ bh aa
	    put_ bh ab
    get bh = do
	  aa <- get bh
	  ab <- get bh
	  return (CExportStatic aa ab)

instance Binary CCallSpec where
    put_ bh (CCallSpec aa ab ac) = do
	    put_ bh aa
	    put_ bh ab
	    put_ bh ac
    get bh = do
	  aa <- get bh
	  ab <- get bh
	  ac <- get bh
	  return (CCallSpec aa ab ac)

instance Binary CCallTarget where
263
    put_ bh (StaticTarget aa ab) = do
264 265
	    putByte bh 0
	    put_ bh aa
266
            put_ bh ab
267 268 269 270 271 272
    put_ bh DynamicTarget = do
	    putByte bh 1
    get bh = do
	    h <- getByte bh
	    case h of
	      0 -> do aa <- get bh
273 274 275
                      ab <- get bh
		      return (StaticTarget aa ab)
	      _ -> do return DynamicTarget
276 277 278 279 280 281

instance Binary CCallConv where
    put_ bh CCallConv = do
	    putByte bh 0
    put_ bh StdCallConv = do
	    putByte bh 1
282 283
    put_ bh PrimCallConv = do
	    putByte bh 2
284 285 286 287
    get bh = do
	    h <- getByte bh
	    case h of
	      0 -> do return CCallConv
288 289
	      1 -> do return StdCallConv
	      _ -> do return PrimCallConv
290
\end{code}