// Copyright 2022 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.hardware.fastboot;

using zx;

/// USB Fastboot implementation protocol. Fastboot is a single-channel and fully synchronous
/// protocol for communication between host and device.
closed protocol FastbootImpl {
    /// Sends fastboot data via USB fastboot device.
    ///
    /// This FIDL protocol blocks until all USB requests needed to send the data are completed. It
    /// can only serve one request at a time.
    ///
    /// Returns ZX_ERR_UNAVAILABLE if another call is made while a previous one is being processed,
    /// or the FIDL is called too early during boot when the driver has not become ready.
    strict Send(resource struct {
        data zx.Handle:VMO;
    }) -> () error zx.Status;

    /// Receives at least `requested` bytes of data from the USB fastboot device.
    ///
    /// Upon success, a vmo is allocated and returned by the driver which contains the data and the
    /// actual received data size (via vmo::get_prop_content_size()). Because USB transmission is
    /// in the unit of packet (512bytes), the actual received size can be at most 512 bytes more
    /// than the requested size.
    ///
    /// If `requested` is 0, the driver returns as soon as a USB packet with data is received. This
    /// should be the value used when expecting fastboot command which is guaranteed to be within a
    /// single USB packet (a fastboot command is no more than 64 bytes as per protocol). When
    /// expecting larger amount of data during image download, it should be set to a larger value
    /// to avoid the overhead of calling this FIDL too many times, as it can be very expensive
    /// comparing to actual data transfer.
    ///
    /// This FIDL protocol is blocking and can only serve one request at a time (Send() is not
    /// affected. Receive() and Send() are individually synchronous).
    ///
    /// Returns ZX_ERR_UNAVAILABLE if another call is made while a previous one is being processed,
    /// or the FIDL is called too early during boot when the driver has not become ready.
    strict Receive(struct {
        requested uint64;
    }) -> (resource struct {
        data zx.Handle:VMO;
    }) error zx.Status;
};