// 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;

/// `HOST_CID` is the reserved context ID (CID) of the host.
const HOST_CID uint32 = 2;
/// VM to VM communication is not supported, so all guests will be assigned this default guest CID.
const DEFAULT_GUEST_CID uint32 = 3;

/// Exposed by a host capable of listening via vsocks. A variant of a
/// `GuestVsockAcceptor` that is responsible for creating the `socket` with which
/// to communicate.
protocol HostVsockAcceptor {
    Accept(struct {
        src_cid uint32;
        src_port uint32;
        port uint32;
    }) -> (resource struct {
        socket zx.handle:SOCKET;
    }) error zx.status;
};

// A host port and acceptor pair. When a guest attempts to initiate a connection on the given port,
// the matching acceptor is used.
type Listener = resource struct {
    port uint32;
    acceptor client_end:HostVsockAcceptor;
};

/// Exposed by a host to provide the ability for listeners to be multiplexed by
/// port and to manage dynamic port allocation for outbound connections.
@discoverable
protocol HostVsockEndpoint {
    /// Instructs the device to listen for guest initiated connections to a given port by
    /// using `acceptor` when the guest creates a connection.
    ///
    /// Possible errors:
    ///     - ZX_ERR_ALREADY_BOUND: A client is already listening on this port.
    Listen(Listener) -> () error zx.status;

    /// Attempts to create a vsock connection to a guest on 'guest_port'. Uses a dynamically chosen
    /// ephemeral host port.
    ///
    /// Possible errors:
    ///     - ZX_ERR_NO_RESOURCES: The device couldn't allocate an unused host port.
    ///     - ZX_ERR_CONNECTION_REFUSED: The guest refused this connection.
    ///
    /// Other errors are related to socket creation, see
    /// [zx_socket_create](https://fuchsia.dev/fuchsia-src/reference/syscalls/socket_create.md)
    Connect(struct {
        guest_port uint32;
    }) -> (resource struct {
        socket zx.handle:SOCKET;
    }) error zx.status;
};