| // Copyright 2019 The Chromium 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 test.fidlcat.sys; |
| |
| // The goal of this file is to get a pretty big library. It's a copy |
| // of fuchsia.sys and fuchsia.mem as of 26 April 2019. |
| |
| /// A Buffer for data whose size is not necessarily a multiple of the page |
| /// size. |
| /// |
| /// VMO objects have a physical size that is always a multiple of the page |
| /// size. As such, VMO alone cannot serve as a buffer for arbitrarly sized |
| /// data. |fuchsia.mem.Buffer| is a standard struct that aggregate the VMO |
| /// and its size. |
| struct Buffer { |
| /// The vmo. |
| handle<vmo> vmo; |
| |
| /// The size of the data in the vmo in bytes. This size must be smaller |
| /// than the physical size of the vmo. |
| uint64 size; |
| }; |
| |
| enum TerminationReason { |
| // The channel closed without giving a termination reason. |
| UNKNOWN = 0; |
| // Component ran and exited with a given return_code. |
| EXITED = 1; |
| // The given URL given to launch was invalid. |
| URL_INVALID = 2; |
| // The requested package could not be found. |
| PACKAGE_NOT_FOUND = 3; |
| // An internal error happened during the launch process. |
| INTERNAL_ERROR = 4; |
| // Process creation failed. |
| PROCESS_CREATION_ERROR = 5; |
| // A Runner failed to start. |
| RUNNER_FAILED = 6; |
| // A Runner terminated while attempting to run a component. |
| RUNNER_TERMINATED = 7; |
| // Attempted to use an unsupported feature. |
| UNSUPPORTED = 8; |
| }; |
| |
| // An interface for controlling components. |
| // |
| // Closing this interface implicitly kills the controlled component unless |
| // the |Detach| method has been called. |
| // |
| // If the component exits, this interface will be closed. |
| // |
| // Typically obtained via |Launcher.CreateComponent|. |
| protocol ComponentController { |
| // Terminates the component. |
| // |
| // This ComponentController connection is closed when the component has |
| // terminated. |
| Kill(); |
| |
| // Decouples the lifetime of the component from this controller. |
| // |
| // After calling |Detach|, the component will not be implicitly killed when |
| // this interface is closed. |
| Detach(); |
| |
| // DEPRECATED: Use OnTerminated instead of Wait(). |
| // 3: Wait() |
| |
| // Event that is triggered when the component is terminated. |
| // |
| // This event provides the return code of the process and reason for |
| // its termination. The return_code is only valid if the termination |
| // reason is EXITED. If the termination reason is not EXITED, the |
| // return code is guaranteed not to be 0. |
| -> OnTerminated(int64 return_code, TerminationReason termination_reason); |
| |
| // Event that is triggered when the component's output directory is mounted. |
| // |
| // This event will not be triggered for every component, only those that |
| // serve a directory over their PA_DIRECTORY_REQUEST handle. |
| -> OnDirectoryReady(); |
| }; |
| |
| // An interface for controlling an environment. |
| // |
| // Closing this interface implicitly kills the controlled environment unless |
| // the |Detach| method has been called. |
| // |
| // If the environment is destroyed, this interface will be closed. |
| // |
| // Typically obtained via |Environment.CreateNestedEnvironment|. |
| protocol EnvironmentController { |
| // Terminates the environment. |
| // |
| // When an |Environment| is terminated, all applications launched |
| // in the environment (and in all transitively nested environments) are also |
| // killed. |
| Kill() -> (); |
| |
| // Decouples the lifetime of the environment from this controller. |
| // |
| // After calling |Detach|, the environment will not be implicitly killed when |
| // this interface is closed. |
| Detach(); |
| |
| // Event that is triggered when the environment is created. |
| -> OnCreated(); |
| }; |
| |
| // Maximum length for an environment label. |
| const uint32 kLabelMaxLength = 32; |
| |
| struct EnvironmentOptions { |
| // True if this environment should inherit services provided by the |
| // parent environment. |
| bool inherit_parent_services; |
| // True if components in this environment can share a runner provided |
| // by the parent environment. If false, a new runner will be started |
| // in this environment for components. |
| bool allow_parent_runners; |
| // True if this environment should be killed first in out of memory |
| // situations by setting the ZX_PROP_JOB_KILL_ON_OOM property on this |
| // environment's job. |
| bool kill_on_oom; |
| // True if "persistent" storage requested by components in this environment should not actually |
| // be persistent, and instead be deleted when this environment is killed. |
| bool delete_storage_on_death; |
| }; |
| |
| // An interface for managing a set of applications. |
| // |
| // Applications run inside environments, which provide ambient services and |
| // support for their lifecycle. |
| [Discoverable] |
| protocol Environment { |
| // Creates a new environment nested inside this environment. |
| // |
| // When applications are created inside the nested environment using the |
| // environment's |Launcher|, the environment requests the |
| // environment services from |host_directory| before passing those services to |
| // the newly created application in its |StartupInfo|. |
| // |
| // The |controller| can be used to control the lifecycle of the created |
| // environment. Note that by default the environment will be killed |
| // automatically when the |EnvironmentController|'s interface is closed. You |
| // can use |EnvironmentController.Detach| to disable this behavior. |
| // |
| // |label| defines the new environment's label/name. It must be unique within |
| // the parent environment (though not globally) and is used for isolating |
| // separate environments. It can also be used for diagnostic purposes. The |
| // label will be truncated if it is longer than |kLabelMaxLength|. |
| // |
| // |additional_services|, which may be empty, contains a list of services |
| // that the environment provides, which are hosted by |
| // |additional_services.host_directory|. If |options.inherit_parent_services| |
| // is false, |host_directory| must provide a |Loader| service if it wishes to |
| // allow new components to be loaded in the new environment. |
| // |
| // |options| provides additional options, see |EnvironmentOptions| for |
| // details. |
| CreateNestedEnvironment(request<Environment> environment, |
| request<EnvironmentController> controller, |
| string label, |
| ServiceList? additional_services, |
| EnvironmentOptions options); |
| |
| // Gets the Launcher associated with this environment. |
| // |
| // Applications created using this application launcher will be given the |
| // environment services provided by this environment's |host_directory|. |
| GetLauncher(request<Launcher> launcher); |
| |
| // Gets a superset of services provided by this environment's |
| // |host_directory|. |
| GetServices(request<ServiceProvider> services); |
| |
| // Gets a superset of services provided by this environment's |
| // |host_directory|. |
| GetDirectory(handle<channel> directory_request); |
| }; |
| |
| struct FlatNamespace { |
| // The mount point for each of the directories below. |
| // |
| // For example, ["/pkg", "/svc"]. |
| vector<string> paths; |
| |
| // The directories mounted at each path in the namespace. |
| vector<handle<channel>> directories; |
| }; |
| |
| // An interface for providing a job handle. Instances of this interface are |
| // created in the context of an already-identified realm, so there is no need |
| // to explicitly identify the realm below. |
| [Discoverable] |
| protocol JobProvider { |
| // Gets the root job associated with the realm. |
| GetJob() -> (handle<job> job); |
| }; |
| |
| // An FDIO file descriptor. |
| // TODO(abarth): Use the real FDIO declaration once FDIO converts to FIDL2. |
| struct FileDescriptor { |
| // The FDIO types of the handle (e.g., FA_FDIO_REMOTE). |
| int32 type0; |
| int32 type1; |
| int32 type2; |
| |
| // The handles for the file descriptor (e.g., a channel). |
| handle? handle0; |
| handle? handle1; |
| handle? handle2; |
| }; |
| |
| // Information used to create an instance of a component and obtain |
| // services from it. |
| struct LaunchInfo { |
| // The location from which to retrieve this component. |
| // |
| // This field will probably be replaced with a stronger notion of identity, |
| // such as an unforgeable token. This field is included in this iteration to |
| // ease the transition from the previous component interfaces. |
| string url; |
| |
| // The arguments to be provided to the component. |
| vector<string>? arguments; |
| |
| // The file descriptor to use for stdout. |
| // |
| // If null, the component will use the default stdout for the environment. |
| FileDescriptor? out; |
| |
| // The file descriptor to use for stderr. |
| // |
| // If null, the component will use the default stderr for the environment. |
| FileDescriptor? err; |
| |
| // The interface request for a Directory that is passed through to the |
| // component and arrives in the component as its |directory_request| |
| // interface request. |
| handle<channel>? directory_request; |
| |
| // A custom namespace that can be appended to the namespace generated by |
| // appmgr and provided to this component. |
| // Adding a mount point at standard paths like 'pkg' or 'svc' will be ignored. |
| // HACK(alhaad): Adding mount points for deprecated default directories like |
| // '/data' will override the default. |
| FlatNamespace? flat_namespace; |
| |
| // A list of services to be added to this component's svc namespace. These |
| // services are in addition to those coming from Environment. |
| ServiceList? additional_services; |
| }; |
| |
| struct ServiceList { |
| // A list of services that can be requested from |provider|. |
| vector<string> names; |
| |
| // A service provider to get the services listed in |names| from. |
| ServiceProvider? provider; |
| |
| // A channel to the directory hosting the services in |names|. |
| // TODO(CP-124): Support |host_directory| for CreateComponent and deprecate |
| // |provider|. |
| handle<channel>? host_directory; |
| }; |
| |
| // An interface for creating component instances. |
| // |
| // Typically obtained via |Environment.GetLauncher|. |
| [Discoverable] |
| protocol Launcher { |
| // Creates a new instance of the component described by |launch_info|. |
| // |
| // The component instance is created in the |Environment| |
| // associated with this |Launcher|. When creating the component, |
| // the environment requests the environment services for this component from |
| // its |EnvironmentHost|. |
| // |
| // The |controller| can be used to control the lifecycle of the created |
| // component instance. If an |ComponentController|'s interface is |
| // requested, the component instance is killed when the interface is closed. |
| CreateComponent(LaunchInfo launch_info, |
| request<ComponentController>? controller); |
| }; |
| |
| // An interface for loading from packages. |
| [Discoverable] |
| protocol Loader { |
| // LoadUrl a package by url. |
| LoadUrl(string url) -> (Package? package); |
| }; |
| |
| // Information given to components at startup. |
| // |
| // For ELF binaries, this information is provided in the initialization message |
| // given to libc by fuchsia.process.Launcher. |
| struct StartupInfo { |
| // The launch info for the to start. |
| LaunchInfo launch_info; |
| |
| // The namespace in which to run the component. |
| FlatNamespace flat_namespace; |
| |
| // Key string value string map of the component's program metadata, obtained |
| // from its component manifest. |
| vector<ProgramMetadata>? program_metadata; |
| |
| // TODO(abarth): Add more fields to this struct relating to component and |
| // environment identity. |
| }; |
| |
| // Program information about a component. |
| struct ProgramMetadata { |
| // Key for program metadata pair. E.g. "binary" for an ELF binary component, |
| // or "data" for a flutter/dart component. |
| string key; |
| |
| // Value for program metadata pair. E.g. "bin/app" for a "binary" key, or |
| // "data/foo" for a flutter/dart component. |
| string value; |
| }; |
| |
| // A binary representation of a component. |
| // |
| // Typically provided to |Runner.StartComponent| when starting a |
| // component. |
| struct Package { |
| // A read-only binary representation of the component. For example, if the |
| // component is intended to run in the Dart virtual machine, this data might |
| // contain a dartx package. |
| Buffer? data; |
| |
| // A directory containing the contents of the package. For example, if the |
| // component is stored in pkgfs, this directory will be the pkgfs directory |
| // containing the package. |
| handle<channel>? directory; |
| |
| // Resolved URL of the component. This is the url specified in startup_info |
| // after following redirects and resolving relative paths. |
| string resolved_url; |
| }; |
| |
| // An interface for running components. |
| // |
| // Typically exposed by components that provide execution environments for |
| // particular classes of programs. For example, the Dart virtual machine exposes |
| // this interface to run Dart programs. |
| [Discoverable] |
| protocol Runner { |
| // Execute the given component. |
| // |
| // Upon startup, the component is to be given the information in |
| // |startup_info|, but the mechanism by which the component receives that |
| // information is up to the component runner. |
| // |
| // The |controller| interface request typically originates from the |
| // |Launcher.CreateComponent| message that caused this |
| // component to be started. |
| StartComponent(Package package, |
| StartupInfo startup_info, |
| request<ComponentController>? controller); |
| }; |
| |
| // An interface through which a client may request services from a host. |
| // Instances of this interface are created within the context of an |
| // already-identified client and host pair, so there is no need to explicitly |
| // identify the client or host in the methods below. |
| // |
| // This interface is deprecated. Services should be published as directory |
| // entries instead, just like files. |
| // TODO(ZX-1358): Point to the FIDL interface for file I/O once RIO is migrated. |
| protocol ServiceProvider { |
| // Asks the host to provide the service identified by |service_name| through |
| // the |channel| endpoint supplied by the caller. If the host is not willing |
| // or able to provide the requested service, it should close the |channel|. |
| ConnectToService(string service_name, handle<channel> channel); |
| }; |