src/developer/ffx/fidl/usb/protocol.fidl

// Copyright 2025 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.
@available(added=HEAD)
library fuchsia.ffx.usb;

/// Maximum string length for error responses that contain strings.
const MAX_ERROR_STRING uint16 = 1024;
/// Maximum string length for the log path.
const MAX_LOG_PATH_STRING uint16 = 1024;

/// Identifies a VSOCK connection. We omit the local CID since it is always
/// assumed to be 2 (the USB driver is always the host).
type ConnectionId = struct {
    remote_cid uint32;
    remote_port uint32;
    local_port uint32;
};

/// Information that is returned about a device when it is discovered.
type DeviceInfo = struct {
    cid uint32;
    meta DeviceMeta;
};

/// Optional information that is returned about a newly-discovered device.
type DeviceMeta = table {
    1: serial string:MAX_ERROR_STRING;
};

/// Error indicating an operation failed because a needed port was already in
/// use.
type PortInUse = struct {
    port uint32;
};

/// Errors occurring during the `Listen` operation.
type ListenError = flexible union {
    1: port_in_use PortInUse;
};
/// Errors occurring during the `StopListen` operation.
type StopListenError = flexible union {
    1: not_listening struct {
        port uint32;
    };
};
/// Errors occurring during the `Reject` operation.
type RejectError = flexible union {
    1: no_such_connection ConnectionId;
};
/// Errors occurring during the `InitializeAccept` operation.
type AcceptError = flexible union {
    1: no_such_connection ConnectionId;
};
/// Errors occurring during the `InitializeConnectTo` operation.
type ConnectionError = flexible union {
    1: cid_not_found struct {
        cid uint32;
    };
    2: failed struct {
        message string:MAX_ERROR_STRING;
    };
    3: port_out_of_range struct {
        port uint32;
    };
    4: cid_invalid struct {
        cid uint32;
    };
    5: port_in_use PortInUse;
};

/// The initial protocol which is being spoken when we first connect to the
/// driver. All methods on this protocol indicate a protocol switch, and the
/// stream is then used to service a different protocol or provide data from a
/// connection.
@no_resource
open protocol FfxUsb {
    /// Start using this stream as a control channel for the driver. After the
    /// response to this method, the stream is now serving the `Control`
    /// protocol below.
    flexible InitializeControl() -> (struct {
        current uint32;
        minimum uint32;
        session_id uint64;
        log_path string:MAX_LOG_PATH_STRING;
    });

    /// Connect to the given CID and port. After a successful response from this
    /// method, the stream is no longer used for FIDL communication and is now
    /// transferring data for the connection.
    flexible InitializeConnectTo(struct {
        cid uint32;
        port uint32;
    }) -> () error ConnectionError;

    /// Accept the given incoming connection.  After a successful response from
    /// this method, the stream is no longer used for FIDL communication and is
    /// now transferring data for the connection.
    flexible InitializeAccept(struct {
        conn ConnectionId;
        session_id uint64;
    }) -> () error AcceptError;

    /// Start using this stream as a channel for device discovery. After the
    /// response to this method, the stream is now serving the `ListDevices`
    /// protocol below.
    flexible InitializeListDevices() -> ();
};

/// Control protocol. This contains methods for initiating listening and
/// handling incoming connection requests.
@no_resource
open protocol Control {
    flexible Listen(struct {
        port uint32;
    }) -> () error ListenError;

    flexible StopListen(struct {
        port uint32;
    }) -> () error StopListenError;

    flexible Reject(ConnectionId) -> () error RejectError;

    strict -> OnIncoming(ConnectionId);
};

/// This protocol provides events for device discovery.
@no_resource
open protocol ListDevices {
    strict -> OnDeviceAppeared(DeviceInfo);
    strict -> OnDeviceDisappeared(struct {
        cid uint32;
    });
};