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.process;
6
7using fuchsia.io;
8using zx;
9
10struct HandleInfo {
11    // The handle to use for this argument.
12    handle @handle;
13
14    // Process argument identifier, from <zircon/processargs.h>.
15    uint32 id;
16};
17
18struct NameInfo {
19    // Path at which to install the associated directory.
20    //
21    // Must be an absolute path (i.e., start with '/').
22    string path;
23
24    // The associated directory.
25    fuchsia.io.Directory directory;
26};
27
28struct LaunchInfo {
29    // The executable to run in the process.
30    handle<vmo> executable;
31
32    // The job in which to create the process.
33    handle<job> job;
34
35    // The name to assign to the created process.
36    string name;
37};
38
39struct LaunchResult {
40    // A status code describing the result of the launch.
41    zx.status status;
42
43    // A string describing the failure.
44    //
45    // Non-null when |status| is an error.
46    string? error_message;
47
48    // The process that was launched.
49    //
50    // Present when |status| is ZX_OK.
51    handle<process>? process;
52};
53
54struct ProcessStartData {
55    // The process that was created.
56    handle<process> process;
57
58    // The vmar object that was created when the process was created.
59    //
60    // See <https://fuchsia.googlesource.com/zircon/+/master/docs/syscalls/process_create.md>.
61    handle<vmar> root_vmar;
62
63    // The initial thread for the process.
64    //
65    // Should be passed to |zx_process_start| when starting the process.
66    handle<thread> thread;
67
68    // The address of the initial entry point in the process.
69    //
70    // Should be passed to |zx_process_start| when starting the process.
71    uint64 entry;
72
73    // The stack pointer value for the initial thread of the process.
74    //
75    // Should be passed to |zx_process_start| when starting the process.
76    uint64 sp;
77
78    // The bootstrap channel to pass to the process on startup.
79    //
80    // Should be passed to |zx_process_start| when starting the process.
81    handle<channel> bootstrap;
82
83    // The base address of the vDSO to pass to the process on startup.
84    //
85    // Should be passed to |zx_process_start| when starting the process.
86    uint64 vdso_base;
87
88    // The base load address of the the ELF file loaded.
89    //
90    // Most often used by debuggers or other tools that inspect the process.
91    uint64 base;
92};
93
94struct CreateWithoutStartingResult {
95    // A status code describing the result of the launch.
96    zx.status status;
97
98    // A string describing the failure.
99    //
100    // Non-null when |status| is an error.
101    string? error_message;
102
103    // Data describing the process that was created.
104    //
105    // Non-null when |status| is ZX_OK.
106    ProcessStartData? data;
107};
108
109[Discoverable]
110interface Launcher {
111    // Creates and starts the process described by |info|.
112    //
113    // After processing this message, the |Launcher| is reset to its initial
114    // state and is ready to launch another process.
115    1: Launch(LaunchInfo info) -> (LaunchResult result);
116
117    // Creates the process described by |info| but does not start it.
118    //
119    // After processing this message, the |Launcher| is reset to its initial
120    // state and is ready to launch another process.
121    //
122    // The caller is responsible for calling |zx_process_start| using the data
123    // in |ProcessStartData| to actually start the process.
124    2: CreateWithoutStarting(LaunchInfo info) -> (CreateWithoutStartingResult result);
125
126    // Adds the given arguments to the command-line for the process.
127    //
128    // Calling this method multiple times concatentates the arguments.
129    10: AddArgs(vector<string> args);
130
131    // Adds the given variables to the enviornment variables for the process.
132    //
133    // Calling this method multiple times concatentates the variables.
134    11: AddEnvirons(vector<string> environ);
135
136    // Adds the given names to the namespace for the process.
137    //
138    // The paths in the namespace must be non-overlapping. See
139    // <https://fuchsia.googlesource.com/docs/+/master/the-book/namespaces.md> for details.
140    //
141    // Calling this method multiple times concatentates the names.
142    12: AddNames(vector<NameInfo> names);
143
144    // Adds the given handles to the startup handles for the process.
145    //
146    // Calling this method multiple times concatentates the handles.
147    13: AddHandles(vector<HandleInfo> handles);
148};
149