// Copyright 2019 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.bluetooth;

using zx;

type ScoCodingFormat = flexible enum : uint8 {
    CVSD = 1;
    MSBC = 2;
};

type ScoEncoding = flexible enum : uint8 {
    BITS_8 = 1;
    BITS_16 = 2;
};

type ScoSampleRate = flexible enum : uint8 {
    KHZ_8 = 1;
    KHZ_16 = 2;
};

open protocol Hci {
    /// Open the two-way HCI command channel for sending HCI commands and
    /// receiving event packets.  Returns ZX_ERR_ALREADY_BOUND if the channel
    /// is already open.
    flexible OpenCommandChannel(resource struct {
        channel zx.Handle:CHANNEL;
    }) -> () error zx.Status;

    /// Open the two-way HCI ACL data channel.
    /// Returns ZX_ERR_ALREADY_BOUND if the channel is already open.
    flexible OpenAclDataChannel(resource struct {
        channel zx.Handle:CHANNEL;
    }) -> () error zx.Status;

    // TODO(b/315877895): Define a new protocol to hold SCO API calls.
    /// Opens a SCO channel on the provided handle. The zircon channel is
    /// closed in the event of an error opening the hci channel or if the hci
    /// channel is already associated with a handle to another zircon channel.
    /// Returns ZX_ERR_NOT_SUPPORTED if SCO is not supported by the current vendor or transport
    /// driver.
    /// Returns ZX_ERR_ALREADY_BOUND if the channel is already open.
    flexible OpenScoDataChannel(resource struct {
        channel zx.Handle:CHANNEL;
    }) -> () error zx.Status;

    /// Configure the HCI for a SCO connection with the indicated parameters.
    /// This must be called before sending/receiving data on the SCO channel.
    /// Returns ZX_ERR_NOT_SUPPORTED if SCO is not supported by the current vendor or transport
    /// driver.
    flexible ConfigureSco(struct {
        coding_format ScoCodingFormat;
        encoding ScoEncoding;
        sample_rate ScoSampleRate;
    }) -> () error zx.Status;

    /// Releases resources held by an active SCO connection. Must be called
    /// when a SCO connection is closed.
    /// Returns ZX_ERR_NOT_SUPPORTED if SCO is not supported by the current vendor or transport
    /// driver.
    flexible ResetSco() -> () error zx.Status;

    /// Opens a channel on the provided handle for sending and receiving isochronous data packets.
    /// The zircon channel is closed in the event of an error opening the hci channel or if the hci
    /// channel is already associated with a handle to another zircon channel.
    /// Returns ZX_ERR_NOT_SUPPORTED if ISO is not supported by the current vendor or transport
    /// driver.
    /// Returns ZX_ERR_ALREADY_BOUND if the channel is already open.
    flexible OpenIsoDataChannel(resource struct {
        channel zx.Handle:CHANNEL;
    }) -> () error zx.Status;

    /// Open an output-only channel for monitoring HCI traffic.
    /// The format of each message is: [1-octet flags] [n-octet payload]
    /// The flags octet is a bitfield with the following values defined:
    ///  - 0x00: The payload represents a command packet sent from the host to the
    ///          controller.
    ///  - 0x01: The payload represents an event packet sent by the controller.
    /// Returns ZX_ERR_ALREADY_BOUND if the channel is already open.
    flexible OpenSnoopChannel(resource struct {
        channel zx.Handle:CHANNEL;
    }) -> () error zx.Status;
};

/// Wrap the protocol in a service that will be exposed to the child driver.
service HciService {
    hci client_end:Hci;
};