[WebAssembly] Move Emscripten-specific behavior under a --emscripten flag

[sunfish]

Summary

This adds a --emscripten command-line option to lld, for use by Emscripten.

Issue an error if -shared or -export-dynamic are used without --emscripten, as the current infrastructure for dynamic linking is specific to Emscripten. We've had reports of users attempting to use these options outside of Emscripten, so it's desirable to diagnose this.

And, don't default to exporting heap_base or data_end without --emscripten. Exporting these exposes implementation details. Embeddings which need them exported can use -Wl,--export=__heap_base and -Wl,--export=__data_end as needed to request this explicitly. With this change, statically-linked WASI executables only export "memory" and "_start".

[carlokok]

imo export-dynamic should still work? All it does it export all symbols that are linked in. My compiler uses and depends on that feature (though I can add emscripten as a flag to the linker, I don't think I should).

[sunfish]

In D62443#1517831, @carlokok wrote:

imo export-dynamic should still work? All it does it export all symbols that are linked in. My compiler uses and depends on that feature (though I can add emscripten as a flag to the linker, I don't think I should).

Can you use --export-all instead of --export-dynamic? On other platforms --export-dynamic exports symbols in the dynamic symbol table, which is not something that wasm has currently. When we do design dynamic linking for wasm, we may have a need for an option like --export-dynamic, and it would be unfortunate if it already means something different.

[carlokok]

I suppose I could; do note they do quite different things:

if (ForceExport || Config->ExportAll)
  return true;

if (Config->ExportDynamic && !isHidden())
  return true;

the nice thing about the dynamic option was to not expose hidden symbols.

[sunfish]

This patch now depends on a corresponding LLVM patch: https://reviews.llvm.org/D62542

This new patch reverts the change to --export-dynamic, to address review feedback. So now, this patch just:

• Makes data_end and heap_base hidden, so that they're not automatically exported if they're just used.
• Adds --emscripten to enable Emscripten compatibility mode, and restricts -shared and -pie to --emscripten mode.
• Adds support for the IMPLICITLY_USED flag added in D62542.

[sbc100]

Wouldn't it be better to try to avoid adding a --emscripten?

I think for heap_base/data_end we should change emscripten to export them explicitly. (I'll look into doing that).

Once we do that then this change only removes the -pie -shared behaviour, right?

docs/WebAssembly.rst

135

The `__attribute__((used))` behaviour is depend on the compiler time triple isn't it ? Not the linker flag?

[sunfish]

In D62443#1520146, @sbc100 wrote:

Wouldn't it be better to try to avoid adding a --emscripten?

I think for heap_base/data_end we should change emscripten to export them explicitly. (I'll look into doing that).

Sounds good.

Once we do that then this change only removes the -pie -shared behaviour, right?

Right, those are the original motivation for the --emscripten option. I'm open to other options here.

[sbc100]

I have proposed https://reviews.llvm.org/D62744 which covers most of the changes here.

For -pie/-shared I'd rather not add a --emscripten flag. In fact I'd rather not have such a flag at all. Some background that might help here: The PIC support in LLVM conforms to the (admittedly unstable/experimental) spec specified in https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md. Note that this document includes both the "emscripten" way of doing things and the future "Planned Changes" way of doing things which is implemented in LLVM. emscripten-wasm-finalize, which is part of binaryen, then converts from the LLVM/official ABI to the emscripten ABI for dynamic linking. I will update the docs to be more clear but as I see it non of the PIC support in LLVM is emscripten-specific.

If you really want to add a new flag I'd be OK with "--experimental".. but I'd rather not have either. Have you been experiencing issues with people passing -pie/-shared this flag and getting unexpected results?

[sunfish]

In D62443#1525418, @sbc100 wrote:

I have proposed https://reviews.llvm.org/D62744 which covers most of the changes here.

For -pie/-shared I'd rather not add a --emscripten flag. In fact I'd rather not have such a flag at all. Some background that might help here: The PIC support in LLVM conforms to the (admittedly unstable/experimental) spec specified in https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md. Note that this document includes both the "emscripten" way of doing things and the future "Planned Changes" way of doing things which is implemented in LLVM. emscripten-wasm-finalize, which is part of binaryen, then converts from the LLVM/official ABI to the emscripten ABI for dynamic linking. I will update the docs to be more clear but as I see it non of the PIC support in LLVM is emscripten-specific.

I agree that the design isn't necessarily specific to Emscripten. My concern is that it seems to have some limitations, which I've been assuming mean that we'd want to design a new system when it comes time to add dynamic linking outside of Emscripten anyway. I've commented on other issues about the specific concerns, so we can follow up there.

If you really want to add a new flag I'd be OK with "--experimental".. but I'd rather not have either. Have you been experiencing issues with people passing -pie/-shared this flag and getting unexpected results?

Yes, we have reports both of people using -Wl,--shared and having things not work, and of people compiling with -fPIC and having things not work. These are what prompted me to write this patch and the LLVM one.

[sbc100]

Can you rebase now that https://reviews.llvm.org/D62744 has landed?

Maybe worth splitting out the isImplicitlyUsed part of this change too? especially since the llvm side of that is still being discussed.

[ruiu]

I'm not in favor of this patch. Adding a blanket option for emscripten seems too specific to one use case. If you really need a special feature for emscripten, you probably should decompose it to fine-grained features and pass command line flags to enable the features from emscripten compiler driver.

[sunfish]

• Rebase
• Rename IMPLICITLY_USED to NO_STRIP

Talking with @sbc100 offline, an alternative to the --emscripten command-line flag would be to write the target triple into .o files, so that the linker can determine if it should enable Emscripten-specific behavior based on that, rather than needing a command-line flag.

The patch here just rebases the earlier patch and updates the name of the new NO_STRIP flag, so that it's easier to see what the changes are.

[sunfish]

Abandoning in favor of https://reviews.llvm.org/D66968.

docs/ReleaseNotes.rst

 MachO Improvements
 ------------------
 
 * Item 1.
 
 WebAssembly Improvements
 ------------------------
 
-* ...
+* `__data_end` and `__heap_base` are no longer exported by default,
+  as it's best to keep them internal when possible. They can be
+  explicitly exported with `--export=__data_end` and
+  `--export=__heap_base`, respectively.

docs/WebAssembly.rst

 
 .. option:: --max-memory=<value>
 
   Maximum size of the linear memory. Default: unlimited.
 
 By default the function table is neither imported nor exported, but defined
 for internal use only.
 
+.. option:: --emscripten
+
+  Enable Emscripten mode.
+
+This option enables Emscripten mode, which exports symbols needed by
+Emscripten and enables options related to dynamic linking.
+
 Behaviour
 ---------
 
 In general, where possible, the WebAssembly linker attempts to emulate the
 behaviour of a traditional ELF linker, and in particular the ELF port of lld.
 For more specific details on how this is achieved see the tool conventions on
 linking_.
 

 unit but with too many arguments.
 
 In order not to generate such invalid modules, lld has two modes of handling such
 mismatches: it can simply error-out or it can create stub functions that will
 trap at runtime (functions that contain only an ``unreachable`` instruction)
 and use these stub functions at the otherwise invalid call sites.
 
 The default behaviour is to generate these stub function and to produce
-a warning.  The ``--falal-warnings`` flag can be used to disable this behaviour
+a warning.  The ``--fatal-warnings`` flag can be used to disable this behaviour
 and error out if mismatched are found.
 
 Imports and Exports
 ~~~~~~~~~~~~~~~~~~~
 
-When building a shared library any symbols marked as ``visibility=default`` will
-be exported.  When building an executable, only the entry point and symbols
-flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default.  In LLVM the
-``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list
-which corresponds to ``__attribute__((used))`` in C/C++ sources.
+By default, the only symbols exported from the WebAssembly module are the
+entry-point symbol and the primary linear memory, named "memory". These ABI
+details are not yet stable.
 
 In addition, symbols can be exported via the linker command line using
-``--export``.
+``--export``. ``--export-dynamic`` exports all symbols with "default"
+visibility. ``--export-all`` exports all symbols with global binding.
 
-Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
-used to export symbol in the executable which are marked as
-``visibility=default``.
+With ``--emscripten``, the ``--shared`` option implies ``--export-dynamic``,
+and symbols marked with ``__attribute__((used))`` are also exported from
+the WebAssembly module.
 
 Garbage Collection
 ~~~~~~~~~~~~~~~~~~
 
 Since WebAssembly is designed with size in mind the linker defaults to
 ``--gc-sections`` which means that all unused functions and data segments will
 be stripped from the binary.
 

test/wasm/export.ll

+; Test in default mode
 ; RUN: llc -filetype=obj %s -o %t.o
 ; RUN: not wasm-ld --export=missing -o %t.wasm %t.o 2>&1 | FileCheck -check-prefix=CHECK-ERROR %s
 ; RUN: wasm-ld --export=hidden_function -o %t.wasm %t.o
 ; RUN: obj2yaml %t.wasm | FileCheck %s
 
+; Now test in Emscripten mode
+; RUN: llc -filetype=obj %s -o %t.o -mtriple=wasm32-unknown-emscripten
+; RUN: not wasm-ld --export=missing -o %t.wasm %t.o 2>&1 | FileCheck -check-prefix=CHECK-ERROR %s
+; RUN: wasm-ld --emscripten --export=hidden_function -o %t.wasm %t.o
+; RUN: obj2yaml %t.wasm | FileCheck %s --check-prefixes=CHECK,EMSCRIPTEN
+
 @llvm.used = appending global [1 x i8*] [i8* bitcast (i32 ()* @used_function to i8*)], section "llvm.metadata"
 
 target triple = "wasm32-unknown-unknown"
 
 ; Not exported by default, but forced via commandline
 define hidden i32 @hidden_function() local_unnamed_addr {
 entry:
   ret i32 0

 ; CHECK:        - Type:            EXPORT
 ; CHECK-NEXT:     Exports:
 ; CHECK-NEXT:       - Name:            memory
 ; CHECK-NEXT:         Kind:            MEMORY
 ; CHECK-NEXT:         Index:           0
 ; CHECK-NEXT:       - Name:            hidden_function
 ; CHECK-NEXT:         Kind:            FUNCTION
 ; CHECK-NEXT:         Index:           0
-; CHECK-NEXT:       - Name:            used_function
-; CHECK-NEXT:         Kind:            FUNCTION
-; CHECK-NEXT:         Index:           1
+; EMSCRIPTEN-NEXT:  - Name:            used_function
+; EMSCRIPTEN-NEXT:    Kind:            FUNCTION
+; EMSCRIPTEN-NEXT:    Index:           1
 ; CHECK-NEXT:       - Name:            _start
 ; CHECK-NEXT:         Kind:            FUNCTION
 ; CHECK-NEXT:         Index:           2
 ; CHECK-NEXT:   - Type:            CODE

test/wasm/pie.ll

 ; RUN: llc -relocation-model=pic -filetype=obj %s -o %t.o
-; RUN: wasm-ld --no-gc-sections --allow-undefined -pie -o %t.wasm %t.o
+; RUN: wasm-ld --emscripten --no-gc-sections --allow-undefined -pie -o %t.wasm %t.o
 ; RUN: obj2yaml %t.wasm | FileCheck %s
 
-target triple = "wasm32-unknown-unknown"
+target triple = "wasm32-unknown-emscripten"
 
 @data = global i32 2, align 4
 @data_external = external global i32
 @indirect_func = local_unnamed_addr global i32 ()* @foo, align 4
 
 @data_addr = local_unnamed_addr global i32* @data, align 4
 @data_addr_external = local_unnamed_addr global i32* @data_external, align 4
 

test/wasm/shared-needed.ll

 ; RUN: llc -filetype=obj %s -o %t.o
 ; RUN: llc -filetype=obj %p/Inputs/ret32.ll -o %t.ret32.o
 
-; RUN: wasm-ld -shared -o %t1.so %t.o
+; RUN: wasm-ld --emscripten -shared -o %t1.so %t.o
 ; RUN: obj2yaml %t1.so | FileCheck %s -check-prefix=SO1
 
-; RUN: wasm-ld -shared -o %t2.so %t1.so %t.ret32.o
+; RUN: wasm-ld --emscripten -shared -o %t2.so %t1.so %t.ret32.o
 ; RUN: obj2yaml %t2.so | FileCheck %s -check-prefix=SO2
 
-target triple = "wasm32-unknown-unknown"
+target triple = "wasm32-unknown-emscripten"
 
 @data = global i32 2, align 4
 
 define default void @foo() {
 entry:
   ret void
 }
 

test/wasm/shared.ll

 ; RUN: llc -relocation-model=pic -filetype=obj %s -o %t.o
-; RUN: wasm-ld -shared -o %t.wasm %t.o
+; RUN: wasm-ld --emscripten -shared -o %t.wasm %t.o
 ; RUN: obj2yaml %t.wasm | FileCheck %s
 
-target triple = "wasm32-unknown-unknown"
+target triple = "wasm32-unknown-emscripten"
 
 @data = hidden global i32 2, align 4
 @data_external = external global i32
 @indirect_func = local_unnamed_addr global i32 ()* @foo, align 4
 @indirect_func_external = local_unnamed_addr global void ()* @func_external, align 4
 
 ; Test data relocations
 @data_addr = local_unnamed_addr global i32* @data, align 4

test/wasm/undefined-data.ll

 ; RUN: llc -filetype=obj %s -o %t.o
 ; RUN: not wasm-ld -o %t.wasm %t.o 2>&1 | FileCheck %s -check-prefix=UNDEF
 ; RUN: not wasm-ld --allow-undefined -o %t.wasm %t.o 2>&1 | FileCheck %s -check-prefix=ALLOW
-; RUN: not wasm-ld --shared -o %t.wasm %t.o 2>&1 | FileCheck %s -check-prefix=SHARED
+; RUN: not wasm-ld --emscripten --shared -o %t.wasm %t.o 2>&1 | FileCheck %s -check-prefix=SHARED
 
 target triple = "wasm32-unknown-unknown"
 
 @data_external = external global i32
 
 define i32 @_start() {
 entry:
     %0 = load i32, i32* @data_external, align 4
     ret i32 %0
 }
 
 ; UNDEF: undefined symbol: data_external
 ; ALLOW: undefined-data.ll.tmp.o: cannot resolve relocation of type R_WASM_MEMORY_ADDR_LEB against undefined (non-weak) data symbol: data_external
 ; SHARED: undefined-data.ll.tmp.o: relocation R_WASM_MEMORY_ADDR_LEB cannot be used againt symbol data_external; recompile with -fPIC

wasm/Config.h

 // and such fields have the same name as the corresponding options.
 // Most fields are initialized by the driver.
 struct Configuration {
   bool AllowUndefined;
   bool CheckFeatures;
   bool CompressRelocations;
   bool Demangle;
   bool DisableVerify;
+  bool Emscripten;
   bool EmitRelocs;
   bool ExportAll;
   bool ExportDynamic;
   bool ExportTable;
   bool GcSections;
   bool ImportMemory;
   bool SharedMemory;
   bool ImportTable;

wasm/Driver.cpp

static void readConfigs(opt::InputArgList &Args) {
   Config->StripDebug = Args.hasArg(OPT_strip_debug);
   Config->StackFirst = Args.hasArg(OPT_stack_first);
   Config->Trace = Args.hasArg(OPT_trace);
   Config->ThinLTOCacheDir = Args.getLastArgValue(OPT_thinlto_cache_dir);
   Config->ThinLTOCachePolicy = CHECK(
       parseCachePruningPolicy(Args.getLastArgValue(OPT_thinlto_cache_policy)),
       "--thinlto-cache-policy: invalid cache policy");
   Config->ThinLTOJobs = args::getInteger(Args, OPT_thinlto_jobs, -1u);
+  Config->Emscripten = Args.hasArg(OPT_emscripten);
   errorHandler().Verbose = Args.hasArg(OPT_verbose);
   LLVM_DEBUG(errorHandler().Verbose = true);
   ThreadsEnabled = Args.hasFlag(OPT_threads, OPT_no_threads, true);
 
   Config->InitialMemory = args::getInteger(Args, OPT_initial_memory, 0);
   Config->GlobalBase = args::getInteger(Args, OPT_global_base, 1024);
   Config->MaxMemory = args::getInteger(Args, OPT_max_memory, 0);
   Config->ZStackSize =
static void setConfigs() {
 
   if (Config->Pic) {
     if (Config->ExportTable)
       error("-shared/-pie is incompatible with --export-table");
     Config->ImportTable = true;
   }
 
   if (Config->Shared) {
+    // -shared is only supported in Emscripten mode, where it means the
+    // following options:
     Config->ImportMemory = true;
     Config->ExportDynamic = true;
     Config->AllowUndefined = true;
   }
 }
 
 // Some command line options or some combinations of them are not allowed.
 // This function checks for such errors.
if (Config->GcSections)
       error("-r and --gc-sections may not be used together");
     if (Config->CompressRelocations)
       error("-r -and --compress-relocations may not be used together");
     if (Args.hasArg(OPT_undefined))
       error("-r -and --undefined may not be used together");
     if (Config->Pie)
       error("-r and -pie may not be used together");
   }
+
+  if (!Config->Emscripten) {
+    if (Config->Shared)
+      error("-shared is currently only supported under Emscripten");
+    if (Config->Pie)
+      error("-pie is currently only supported under Emscripten");
+  }
 }
 
 // Force Sym to be entered in the output. Used for -u or equivalent.
 static Symbol *handleUndefined(StringRef Name) {
   Symbol *Sym = Symtab->find(Name);
   if (!Sym)
     return nullptr;
 

wasm/LTO.cpp

for (const lto::InputFile::Symbol &ObjSym : Obj.symbols()) {
 
     // Ideally we shouldn't check for SF_Undefined but currently IRObjectFile
     // reports two symbols for module ASM defined. Without this check, lld
     // flags an undefined in IR with a definition in ASM as prevailing.
     // Once IRObjectFile is fixed to report only one symbol this hack can
     // be removed.
     R.Prevailing = !ObjSym.isUndefined() && Sym->getFile() == &F;
     R.VisibleToRegularObj = Config->Relocatable || Sym->IsUsedInRegularObj ||
+                            Sym->isNoStrip() ||
                             (R.Prevailing && Sym->isExported());
     if (R.Prevailing)
       undefine(Sym);
 
     // We tell LTO to not apply interprocedural optimization for wrapped
     // (with --wrap) symbols because otherwise LTO would inline them while
     // their values are still not final.
     R.LinkerRedefined = !Sym->CanInline;

wasm/MarkLive.cpp

void lld::wasm::markLive() {
   };
 
   // Add GC root symbols.
   if (!Config->Entry.empty())
     Enqueue(Symtab->find(Config->Entry));
 
   // We need to preserve any exported symbol
   for (Symbol *Sym : Symtab->getSymbols())
-    if (Sym->isExported())
+    if (Sym->isNoStrip() || Sym->isExported())
       Enqueue(Sym);
 
   // For relocatable output, we need to preserve all the ctor functions
   if (Config->Relocatable) {
     for (const ObjFile *Obj : Symtab->ObjectFiles) {
       const WasmLinkingData &L = Obj->getWasmObj()->linkingData();
       for (const WasmInitFunc &F : L.InitFunctions)
         Enqueue(Obj->getFunctionSymbol(F.Symbol));

wasm/Options.td

 
 defm demangle: B<"demangle",
     "Demangle symbol names",
     "Do not demangle symbol names">;
 
 def emit_relocs: F<"emit-relocs">, HelpText<"Generate relocations in output">;
 
 defm export_dynamic: B<"export-dynamic",
-    "Put symbols in the dynamic symbol table",
-    "Do not put symbols in the dynamic symbol table (default)">;
+    "Export all global symbols with visibility \"default\"",
+    "Do not automatically export global symbols with visibility \"default\" (default)">;
 
 def entry: S<"entry">, MetaVarName<"<entry>">,
   HelpText<"Name of entry point symbol">;
 
 def error_limit: J<"error-limit=">,
   HelpText<"Maximum number of errors to emit before stopping (0 = no limit)">;
 
 def fatal_warnings: F<"fatal-warnings">,
def max_memory: J<"max-memory=">,
   HelpText<"Maximum size of the linear memory">;
 
 def no_entry: F<"no-entry">,
   HelpText<"Do not output any entry point">;
 
 def stack_first: F<"stack-first">,
   HelpText<"Place stack at start of linear memory rather than after data">;
 
+def emscripten: F<"emscripten">,
+  HelpText<"Enable Emscripten support">;
+
 defm whole_archive: B<"whole-archive",
     "Force load of all members in a static library",
     "Do not force load of all members in a static library (default)">;
 
 defm check_features: B<"check-features",
     "Check feature compatibility of linked objects (default)",
     "Ignore feature compatibility of linked objects">;
 

wasm/Symbols.h

public:
   // Get/set the index in the output symbol table.  This is only used for
   // relocatable output.
   uint32_t getOutputSymbolIndex() const;
   void setOutputSymbolIndex(uint32_t Index);
 
   WasmSymbolType getWasmType() const;
   bool isExported() const;
 
+  // Indicates that the symbol is used in an __attribute__((used)) directive
+  // or similar.
+  bool isNoStrip() const;
+
   // True if the symbol was used for linking and thus need to be added to the
   // output file's symbol table. This is true for all symbols except for
   // unreferenced DSO symbols, lazy (archive) symbols, and bitcode symbols that
   // are unreferenced except by other bitcode objects.
   unsigned IsUsedInRegularObj : 1;
 
   // True if ths symbol is explicity marked for export (i.e. via the -e/--export
   // command line flag)

wasm/Symbols.cpp

if (ForceExport || Config->ExportAll)
     return true;
 
   if (Config->ExportDynamic && !isHidden())
     return true;
 
   return Flags & WASM_SYMBOL_EXPORTED;
 }
 
+bool Symbol::isNoStrip() const {
+  return Flags & WASM_SYMBOL_NO_STRIP;
+}
+
 uint32_t FunctionSymbol::getFunctionIndex() const {
   if (auto *F = dyn_cast<DefinedFunction>(this))
     return F->Function->getFunctionIndex();
   assert(FunctionIndex != INVALID_INDEX);
   return FunctionIndex;
 }
 
 void FunctionSymbol::setFunctionIndex(uint32_t Index) {