| // Copyright 2018 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.virtualization; |
| |
| using zx; |
| |
| type GuestError = strict enum { |
| /// Catch all VMM error. |
| INTERNAL_ERROR = 1; |
| |
| /// A device endpoint was requested via the guest client API, but the device isn't enabled. |
| DEVICE_NOT_PRESENT = 2; |
| |
| /// The config failed VMM validation for reasons such as a missing required field. |
| BAD_CONFIG = 3; |
| |
| /// The VMM failed to initialize the guest object, usually due to capability routing issues |
| /// or memory layout problems. |
| GUEST_INITIALIZATION_FAILURE = 4; |
| |
| /// The VMM failed to initialize a device. |
| DEVICE_INITIALIZATION_FAILURE = 5; |
| |
| /// The VMM failed to start a device, usually because the device component returned a failure. |
| DEVICE_START_FAILURE = 6; |
| |
| /// Two or more devices have attempted to register overlapping memory ranges. |
| DEVICE_MEMORY_OVERLAP = 7; |
| |
| /// Failed to connect to a required service. Check the routing in the manifest. |
| FAILED_SERVICE_CONNECT = 8; |
| |
| /// Failed to add a public service. |
| DUPLICATE_PUBLIC_SERVICES = 9; |
| |
| /// General error when loading the guest kernel. |
| KERNEL_LOAD_FAILURE = 10; |
| |
| /// Error when starting a VCPU. |
| VCPU_START_FAILURE = 11; |
| |
| /// A VCPU encountered a fatal error while running. |
| VCPU_RUNTIME_FAILURE = 12; |
| |
| /// The VMM was asked to run before it was created. |
| NOT_CREATED = 13; |
| |
| /// A VMM is already running. The VMM must be stopped and a new VMM must be created before it |
| /// can be run again. |
| ALREADY_RUNNING = 14; |
| |
| /// A running VMM was forced to stop by the VMM controller. |
| CONTROLLER_FORCED_HALT = 15; |
| }; |
| |
| /// The guest control plane allowing for creating, starting, and stopping the guest. |
| @discoverable |
| closed protocol GuestLifecycle { |
| /// Create a VMM configured with the provided config. This instantiates all devices and loads |
| /// the kernel without starting the VCPU or device dispatch loops. |
| /// |
| /// Possible errors: |
| /// - ALREADY_RUNNING: A VMM instance is already running, and must be stopped before being |
| /// recreated. |
| /// |
| /// All other errors are related to VMM initialization. |
| strict Create(resource struct { |
| guest_config GuestConfig; |
| }) -> () error GuestError; |
| |
| /// Binds to the Guest protocol for an initialized guest. |
| /// |
| /// This operation must be called between `Create` and `Stop`, otherwise the provided channel |
| /// will be immediately closed. |
| strict Bind(resource struct { |
| guest server_end:Guest; |
| }); |
| |
| /// Start the primary VCPU and any dispatch loop. This will not return until the VMM stops |
| /// running. On a clean shutdown (either guest or client initiated) this will return success. |
| /// |
| /// Possible errors: |
| /// - ALREADY_RUNING: The VMM has already been started. |
| /// - NOT_CREATED: Run was called before the VMM was created. |
| /// - CONTROLLER_FORCED_HALT: Stop was called on a running VMM. |
| /// - VCPU_START_FAILURE: Failed to start the primary VCPU. |
| /// - VCPU_RUNTIME_FAILURE: A VCPU encountered a fatal error while running the guest. |
| strict Run() -> () error GuestError; |
| |
| /// Stop a running VMM. Returns once the dispatch loops have stopped. After Stop returns, |
| /// Create and then Run can be called again. |
| strict Stop() -> (); |
| }; |
| |
| /// The guest client API providing high level access to guest features. When the guest terminates, |
| /// this channel will contain a ZX_OK epitaph on a clean shutdown, a ZX_ERR_INTERNAL epitaph on |
| /// an unexpected shutdown, and no epitaph if the component crashed. |
| @discoverable |
| closed protocol Guest { |
| /// Get a guest console. |
| /// |
| /// The details regarding what output is produced and what input is accepted |
| /// are determined by each guest, but will typically be a read/write socket |
| /// with a shell. |
| /// |
| /// Returns error DEVICE_NOT_PRESENT if the guest was started without a console device. |
| strict GetConsole() -> (resource struct { |
| socket zx.Handle:SOCKET; |
| }) error GuestError; |
| |
| /// Get the socket for low-level guest debug logs. |
| /// |
| /// The details regarding what output is produced and what input is accepted |
| /// are determined by each guest, but will typically be a read-only socket |
| /// with the guest kernel's serial logs. |
| strict GetSerial() -> (resource struct { |
| socket zx.Handle:SOCKET; |
| }); |
| |
| /// Get the vsock endpoint for the guest. |
| /// |
| /// This endpoint can be used to register listeners for guest initiated connections, and |
| /// to initiate connections from a client. If listeners need to be registered before the guest |
| /// starts so that they are immediately available, set them via the guest config instead of |
| /// using this endpoint. |
| /// |
| /// Returns error DEVICE_NOT_PRESENT if the guest was started without a vsock device. |
| strict GetHostVsockEndpoint(resource struct { |
| endpoint server_end:HostVsockEndpoint; |
| }) -> () error GuestError; |
| |
| /// Get the balloon controller endpoint for the guest. |
| /// |
| /// Returns error DEVICE_NOT_PRESENT if the guest was started without a balloon device. |
| strict GetBalloonController(resource struct { |
| controller server_end:BalloonController; |
| }) -> () error GuestError; |
| |
| /// Get the mem controller endpoint for the guest. |
| /// |
| /// Returns error DEVICE_NOT_PRESENT if the guest was started without a mem device. |
| strict GetMemController(resource struct { |
| controller server_end:MemController; |
| }) -> () error GuestError; |
| }; |