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