1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5library fuchsia.ldsvc;
6
7using zx;
8
9// See //zircon/docs/program_loading.md for a more complete
10// description of this and related process bootsrapping protocols, and
11// for specifics about the default global loader service's
12// interpretation of names, paths, and configurations.
13
14// WARNING: This interface is manually implemented in libldmsg.a. Please
15// update that implmentation if you change this protocol.
16
17[Layout = "Simple"]
18interface Loader {
19    // Cleanly shutdown the connection to the Loader service.
20    1: Done();
21
22    // The dynamic linker sends |object_name| and gets back a VMO
23    // handle containing the file.
24    2: LoadObject(string:1024 object_name) -> (zx.status rv, handle<vmo>? object);
25
26    // The program loader sends the script |interperter_name| from
27    // hashbang and gets back a VMO to execute in place of the script.
28    3: LoadScriptInterpreter(string:1024 interpreter_name) -> (zx.status rv, handle<vmo>? object);
29
30    // The dynamic linker sends a |config| identifying its load
31    // configuration.  This is intended to affect how later
32    // |LoadObject| requests decide what particular implementation
33    // file to supply for a given name.
34    4: Config(string:1024 config) -> (zx.status rv);
35
36    // Obtain a new loader service connection.
37    5: Clone(request<Loader> loader) -> (zx.status rv);
38
39    // The program runtime sends a string naming a |data_sink| and
40    // transfers the sole handle to a VMO containing the |data| it
41    // wants published there.  The |data_sink| string identifies a
42    // type of data, and the VMO's object name can specifically
43    // identify the data set in this VMO.  The client must transfer
44    // the only handle to the VMO (which prevents the VMO being
45    // resized without the receiver's knowledge), but it might still
46    // have the VMO mapped in and continue to write data to it.  Code
47    // instrumentation runtimes use this to deliver large binary trace
48    // results.
49    //
50    // This is intended to be a developer-oriented feature and might
51    // not ordinarily be available in production runs.
52    7: DebugPublishDataSink(string:1024 data_sink, handle<vmo> data) -> (zx.status rv);
53
54    // The program runtime names a |config_name| referring to a debug
55    // configuration of some kind and gets back a VMO to read
56    // configuration data from.  The sanitizer runtimes use this to
57    // allow large options text to be stored in a file rather than
58    // passed directly in environment strings.
59    //
60    // This is intended to be a developer-oriented feature and might
61    // not ordinarily be available in production runs.
62    8: DebugLoadConfig(string:1024 config_name) -> (zx.status rv, handle<vmo>? config);
63};
64