// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.process.init;

using fuchsia.ldsvc;
using fuchsia.mem;
using fuchsia.process;
using zx;

/// The protocol used to initialize processes.
closed protocol Bootstrap {
    /// Provide the interpreter (in the sense of PT_INTERP) with the capabilities and information it
    /// needs to load code.
    ///
    /// This method must be called at most once, and must come before all other method calls if it
    /// is sent at all.
    strict InitializeInterpreter(resource struct {
        info InterpreterInfo;
    });

    /// Provide the program with the capabilities and information it needs for runtime support.
    ///
    /// This method must be called exactly once. It must proceed all other messages except the
    /// optional call to `InitializeInterpreter`.
    strict InitializeRuntime(resource struct {
        info RuntimeInfo;
    });

    /// Add the given handles to set of startup handles for the process.
    ///
    /// Must be called after `InitializeInterpreter` and `InitializeRuntime`, and before
    /// `Start`. Can be called multiple times.
    strict AddHandles(resource struct {
        handles vector<fuchsia.process.HandleInfo>:64;
    });

    /// Add the given names to the namespace of the new process.
    ///
    /// Must be called after `InitializeInterpreter` and `InitializeRuntime`, and before
    /// `Start`. Can be called multiple times.
    strict AddNames(resource struct {
        names vector<fuchsia.process.NameInfo>:64;
    });

    /// Start the process.
    ///
    /// This must be called last, and exactly once, after initialization and after all handles and
    /// names have been added.
    ///
    ///  * argc: The number of arguments in `argv`.
    ///  * environc: The number of variables in the `environ`.
    ///
    /// The command line arguments and environment variables for the process.
    ///
    /// Each byte sequence in `data` is terminated by a single 0x00 byte. The
    /// first `argc` byte sequences in the payload are the command line
    /// arguments. The next `environc` byte sequences are the environment
    /// variables.
    strict Start(resource struct {
        argc uint32;
        environc uint32;
        data fuchsia.mem.Data;
    });
};

type RuntimeInfo = resource struct {
    /// The process being bootstrapped.
    process zx.Handle:PROCESS;

    /// The initial thread of the process being bootstrapped.
    initial_thread zx.Handle:THREAD;

    /// REVIEW: What VMAR(s) does the program runtime receive?
    vmars zx.Handle:VMAR;
};

/// Flags to modulate the behavior of the interpreter for a process.
type InterpreterFlags = strict bits : uint64 {
    DEBUG = 0x1;
    TRACE = 0x2;
};

/// Information need by the interpreter to initialize a process.
type InterpreterInfo = resource struct {
    /// Flags to modulate the behavior of the interpreter.
    /// REVIEW: Can this be removed?
    flags InterpreterFlags;

    /// The VMAR into which the interpreter should load code.
    target_vmar zx.Handle:VMAR;

    /// The VMAR into which the interpreter was loaded.
    interpreter_vmar zx.Handle:VMAR;

    /// The executable to load.
    executable zx.Handle:VMO;

    /// The shared library loader to use for the process.
    loader client_end:fuchsia.ldsvc.Loader;
};