1 /* -----------------------------------------------------------------------------
2  *
3  * (c) The GHC Team, 2009
4  *
5  * RTS Object Linker
6  *
7  * Do not #include this file directly: #include "Rts.h" instead.
8  *
9  * To understand the structure of the RTS headers, see the wiki:
10  *   https://gitlab.haskell.org/ghc/ghc/wikis/commentary/source-tree/includes
11  *
12  * ---------------------------------------------------------------------------*/
13 
14 #pragma once
15 
16 #if defined(mingw32_HOST_OS)
17 typedef wchar_t pathchar;
18 #define PATH_FMT "ls"
19 #else
20 typedef char    pathchar;
21 #define PATH_FMT "s"
22 #endif
23 
24 /* Initialize the object linker. Equivalent to initLinker_(1). */
25 void initLinker (void);
26 
27 /* Initialize the object linker.
28  * The retain_cafs argument is:
29  *
30  *   non-zero => Retain CAFs unconditionally in linked Haskell code.
31  *               Note that this prevents any code from being unloaded.
32  *               It should not be necessary unless you are GHCi or
33  *               hs-plugins, which needs to be able call any function
34  *               in the compiled code.
35  *
36  *   zero     => Do not retain CAFs.  Everything reachable from foreign
37  *               exports will be retained, due to the StablePtrs
38  *               created by the module initialisation code.  unloadObj
39  *               frees these StablePtrs, which will allow the CAFs to
40  *               be GC'd and the code to be removed.
41  */
42 void initLinker_ (int retain_cafs);
43 
44 /* insert a symbol in the hash table */
45 HsInt insertSymbol(pathchar* obj_name, char* key, void* data);
46 
47 /* lookup a symbol in the hash table */
48 void *lookupSymbol( char *lbl );
49 
50 /* See Linker.c Note [runtime-linker-phases] */
51 typedef enum {
52     OBJECT_LOADED,
53     OBJECT_NEEDED,
54     OBJECT_RESOLVED,
55     OBJECT_UNLOADED,
56     OBJECT_DONT_RESOLVE,
57     OBJECT_NOT_LOADED     /* The object was either never loaded or has been
58                              fully unloaded */
59 } OStatus;
60 
61 /* check object load status */
62 OStatus getObjectLoadStatus( pathchar *path );
63 
64 /* delete an object from the pool */
65 HsInt unloadObj( pathchar *path );
66 
67 /* purge an object's symbols from the symbol table, but don't unload it */
68 HsInt purgeObj( pathchar *path );
69 
70 /* add an obj (populate the global symbol table, but don't resolve yet) */
71 HsInt loadObj( pathchar *path );
72 
73 /* add an arch (populate the global symbol table, but don't resolve yet) */
74 HsInt loadArchive( pathchar *path );
75 
76 /* resolve all the currently unlinked objects in memory */
77 HsInt resolveObjs( void );
78 
79 /* load a dynamic library */
80 const char *addDLL( pathchar* dll_name );
81 
82 /* add a path to the library search path */
83 HsPtr addLibrarySearchPath(pathchar* dll_path);
84 
85 /* removes a directory from the search path,
86    path must have been added using addLibrarySearchPath */
87 HsBool removeLibrarySearchPath(HsPtr dll_path_index);
88 
89 /* give a warning about missing Windows patches that would make
90    the linker work better */
91 void warnMissingKBLibraryPaths( void );
92 
93 /* -----------------------------------------------------------------------------
94 * Searches the system directories to determine if there is a system DLL that
95 * satisfies the given name. This prevent GHCi from linking against a static
96 * library if a DLL is available.
97 */
98 pathchar* findSystemLibrary(pathchar* dll_name);
99 
100 /* called by the initialization code for a module, not a user API */
101 StgStablePtr foreignExportStablePtr (StgPtr p);
102