| // 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.fidlcodec.sys; | |
| using zx; | |
| // 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. | |
| type Buffer = resource struct { | |
| /// The vmo. | |
| vmo zx.Handle:VMO; | |
| /// The size of the data in the vmo in bytes. This size must be smaller | |
| /// than the physical size of the vmo. | |
| size uint64; | |
| }; | |
| type TerminationReason = strict enum { | |
| // 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; | |
| }; | |
| // A protocol for controlling components. | |
| // | |
| // Closing this protocol implicitly kills the controlled component unless | |
| // the `Detach` method has been called. | |
| // | |
| // If the component exits, this protocol will be closed. | |
| // | |
| // Typically obtained via `Launcher.CreateComponent`. | |
| closed protocol ComponentController { | |
| // Terminates the component. | |
| // | |
| // This ComponentController connection is closed when the component has | |
| // terminated. | |
| strict Kill(); | |
| // Decouples the lifetime of the component from this controller. | |
| // | |
| // After calling `Detach`, the component will not be implicitly killed when | |
| // this protocol is closed. | |
| strict 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. | |
| strict -> OnTerminated(struct { | |
| return_code int64; | |
| termination_reason TerminationReason; | |
| }); | |
| // 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. | |
| strict -> OnDirectoryReady(); | |
| }; | |
| // A protocol for controlling an environment. | |
| // | |
| // Closing this protocol implicitly kills the controlled environment unless | |
| // the `Detach` method has been called. | |
| // | |
| // If the environment is destroyed, this protocol will be closed. | |
| // | |
| // Typically obtained via `Environment.CreateNestedEnvironment`. | |
| closed 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. | |
| strict Kill() -> (); | |
| // Decouples the lifetime of the environment from this controller. | |
| // | |
| // After calling `Detach`, the environment will not be implicitly killed when | |
| // this protocol is closed. | |
| strict Detach(); | |
| // Event that is triggered when the environment is created. | |
| strict -> OnCreated(); | |
| }; | |
| // Maximum length for an environment label. | |
| const LABEL_MAX_LENGTH uint32 = 32; | |
| type EnvironmentOptions = struct { | |
| // True if this environment should inherit services provided by the | |
| // parent environment. | |
| inherit_parent_services bool; | |
| // 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. | |
| allow_parent_runners bool; | |
| // 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. | |
| kill_on_oom bool; | |
| // True if "persistent" storage requested by components in this environment should not actually | |
| // be persistent, and instead be deleted when this environment is killed. | |
| delete_storage_on_death bool; | |
| }; | |
| // A protocol for managing a set of applications. | |
| // | |
| // Applications run inside environments, which provide ambient services and | |
| // support for their lifecycle. | |
| @discoverable | |
| closed 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` client endpoint 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 `LABEL_MAX_LENGTH`. | |
| // | |
| // `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. | |
| strict CreateNestedEnvironment(resource struct { | |
| environment server_end:Environment; | |
| controller server_end:EnvironmentController; | |
| label string; | |
| additional_services box<ServiceList>; | |
| options EnvironmentOptions; | |
| }); | |
| // 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`. | |
| strict GetLauncher(resource struct { | |
| launcher server_end:Launcher; | |
| }); | |
| // Gets a superset of services provided by this environment's | |
| // `host_directory`. | |
| strict GetServices(resource struct { | |
| services server_end:Provider; | |
| }); | |
| // Gets a superset of services provided by this environment's | |
| // `host_directory`. | |
| strict GetDirectory(resource struct { | |
| directory_request zx.Handle:CHANNEL; | |
| }); | |
| }; | |
| type FlatNamespace = resource struct { | |
| // The mount point for each of the directories below. | |
| // | |
| // For example, ["/pkg", "/svc"]. | |
| paths vector<string>; | |
| // The directories mounted at each path in the namespace. | |
| directories vector<zx.Handle:CHANNEL>; | |
| }; | |
| // A protocol for providing a job handle. Instances of this protocol are | |
| // created in the context of an already-identified realm, so there is no need | |
| // to explicitly identify the realm below. | |
| @discoverable | |
| closed protocol JobProvider { | |
| // Gets the root job associated with the realm. | |
| strict GetJob() -> (resource struct { | |
| job zx.Handle:JOB; | |
| }); | |
| }; | |
| // An FDIO file descriptor. | |
| // TODO(abarth): Use the real FDIO declaration once FDIO converts to FIDL2. | |
| type FileDescriptor = resource struct { | |
| // The FDIO types of the handle (e.g., FA_FDIO_REMOTE). | |
| type0 int32; | |
| type1 int32; | |
| type2 int32; | |
| // The handles for the file descriptor (e.g., a channel). | |
| handle0 zx.Handle:optional; | |
| handle1 zx.Handle:optional; | |
| handle2 zx.Handle:optional; | |
| }; | |
| // Information used to create an instance of a component and obtain | |
| // services from it. | |
| type LaunchInfo = resource struct { | |
| // 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 protocols. | |
| url string; | |
| // The arguments to be provided to the component. | |
| arguments vector<string>:optional; | |
| // The file descriptor to use for stdout. | |
| // | |
| // If null, the component will use the default stdout for the environment. | |
| out box<FileDescriptor>; | |
| // The file descriptor to use for stderr. | |
| // | |
| // If null, the component will use the default stderr for the environment. | |
| err box<FileDescriptor>; | |
| // The protocol request for a Directory that is passed through to the | |
| // component and arrives in the component as its `directory_request` | |
| // protocol request. | |
| directory_request zx.Handle:<CHANNEL, optional>; | |
| // A custom namespace that can be appended to the namespace of the 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. | |
| flat_namespace box<FlatNamespace>; | |
| // A list of services to be added to this component's svc namespace. These | |
| // services are in addition to those coming from Environment. | |
| additional_services box<ServiceList>; | |
| }; | |
| type ServiceList = resource struct { | |
| // A list of services that can be requested from `provider`. | |
| names vector<string>; | |
| // A service provider to get the services listed in `names` from. | |
| provider client_end:<Provider, optional>; | |
| // A channel to the directory hosting the services in `names`. | |
| // TODO(https://fxbug.dev/42106217): Support `host_directory` for CreateComponent and deprecate | |
| // `provider`. | |
| host_directory zx.Handle:<CHANNEL, optional>; | |
| }; | |
| // A protocol for creating component instances. | |
| // | |
| // Typically obtained via `Environment.GetLauncher`. | |
| @discoverable | |
| closed 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 provided, the component instance is killed when | |
| // the `ComponentController` client endpoint is closed. | |
| strict CreateComponent(resource struct { | |
| launch_info LaunchInfo; | |
| controller server_end:<ComponentController, optional>; | |
| }); | |
| }; | |
| // A protocol for loading from packages. | |
| @discoverable | |
| closed protocol Loader { | |
| // LoadUrl a package by url. | |
| strict LoadUrl(struct { | |
| url string; | |
| }) -> (resource struct { | |
| package box<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. | |
| type StartupInfo = resource struct { | |
| // The launch info for the to start. | |
| launch_info LaunchInfo; | |
| // The namespace in which to run the component. | |
| flat_namespace FlatNamespace; | |
| // Key string value string map of the component's program metadata, obtained | |
| // from its component manifest. | |
| program_metadata vector<ProgramMetadata>:optional; | |
| // TODO(abarth): Add more fields to this struct relating to component and | |
| // environment identity. | |
| }; | |
| // Program information about a component. | |
| type ProgramMetadata = struct { | |
| // Key for program metadata pair. E.g. "binary" for an ELF binary component, | |
| // or "data" for a flutter/dart component. | |
| key string; | |
| // Value for program metadata pair. E.g. "bin/app" for a "binary" key, or | |
| // "data/foo" for a flutter/dart component. | |
| value string; | |
| }; | |
| // A binary representation of a component. | |
| // | |
| // Typically provided to `Runner.StartComponent` when starting a | |
| // component. | |
| type Package = resource struct { | |
| // 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. | |
| data box<Buffer>; | |
| // 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. | |
| directory zx.Handle:<CHANNEL, optional>; | |
| // Resolved URL of the component. This is the url specified in startup_info | |
| // after following redirects and resolving relative paths. | |
| resolved_url string; | |
| }; | |
| // A protocol for running components. | |
| // | |
| // Typically exposed by components that provide execution environments for | |
| // particular classes of programs. For example, the Dart virtual machine exposes | |
| // this protocol to run Dart programs. | |
| @discoverable | |
| closed 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` protocol request typically originates from the | |
| // `Launcher.CreateComponent` message that caused this | |
| // component to be started. | |
| strict StartComponent(resource struct { | |
| package Package; | |
| startup_info StartupInfo; | |
| controller server_end:<ComponentController, optional>; | |
| }); | |
| }; | |
| // A protocol through which a client may request services from a host. | |
| // Instances of this protocol 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 protocol is deprecated. Services should be published as directory | |
| // entries instead, just like files. | |
| // TODO(https://fxbug.dev/42106217): Point to the FIDL protocol for file I/O once RIO is migrated. | |
| closed protocol Provider { | |
| // 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`. | |
| strict ConnectToService(resource struct { | |
| service_name string; | |
| channel zx.Handle:CHANNEL; | |
| }); | |
| }; |