// 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.net.ppp;

using zx;
using fuchsia.net;

/// Information about PPP device configuration.
// TODO(CONN-166): Change this to a table when LLCPP supports it.
struct Info {
    uint16 mtu; // bytes
};

/// Options for a PPP connection.
// TODO(CONN-166): Change this to a table when LLCPP supports it.
struct ConnectionOptions {
    /// Enable Link Control Protocol Magic Numbers for loopback detection.
    bool magic_number;
    /// Enable IPv4 with the given IP address.
    fuchsia.net.Ipv4Address? ipv4;
    /// Enable IPv6 with the given IPv6 address (used as an interface identifier).
    fuchsia.net.Ipv6Address? ipv6;
};

/// The type of protocol being transmitted or received.
enum ProtocolType {
    CONTROL = 1;
    IPV4 = 2;
    IPV6 = 3;
};

/// PPP device driver interface.
protocol Device {
    /// Receive data.
    Rx(ProtocolType protocol) -> (bytes data) error zx.status;

    /// Transmit data. When this call returns, it is guaranteed that the data has either been
    /// written or that the write failed and the caller may attempt to retransmit.
    Tx(ProtocolType protocol, bytes data) -> () error zx.status;

    /// Obtain information about device configuration.
    GetInfo() -> (Info info);

    /// Obtain status of a given protocol. If a protocol is `up`, `Rx` and `Tx` may be called with
    /// the same protocol to send and receive PPP frames.
    GetStatus(ProtocolType protocol) -> (bool up);

    /// Set status of a given protocol. If a protocol is `up`, `Rx` and `Tx` may be called with the
    /// same protocol to send and receive PPP frames.
    SetStatus(ProtocolType protocol, bool up);

    /// On up, obtain exclusive access to the serial port, and begin continuously reading all
    /// protocol types. On down, stop reading and release access to the serial port. Errors only
    /// occur when the device fails to obtain exclusive access to the serial port, in which case
    /// the device remains in a down state. The device begins down when initialized, so `Enable`
    /// must be called before the driver can send or receive data.
    Enable(bool up) -> () error zx.status;
};

protocol DeviceBootstrap {
    /// Obtain a unique channel to be used with the driver. This is desirable to avoid blocking
    /// other consumers of the device protocol, and should be removed when the DDK has a better
    /// channel ownership model for drivers which implement protocols. All instances point to the
    /// same underlying device; separate instances are only used to allow the driver to
    /// concurrently reply to calls.
    GetInstance() -> (Device instance);
};

/// PPP service interface.
[Discoverable]
protocol Ppp {
    /// Given an instance of the driver and options, attempt to open a PPP connection.
    /// Uses the provided options to determine how to configure the link, and whether or not to
    /// configure IPv4 or IPv6. If no error is returned, the connection is open and the driver
    /// supports the requested protocols. Only one connection can be open at a time.
    Open(Device instance, ConnectionOptions options) -> () error zx.status;

    /// If a connection is currently open, close it. Otherwise return an error.
    Close() -> () error zx.status;
};