// 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.hardware.serialimpl;

using zx;
using fuchsia.hardware.serial;

// Start of `flags` that can be passed to Config.

// Select the character width
const SERIAL_DATA_BITS_5 uint32 = 0x0;
const SERIAL_DATA_BITS_6 uint32 = 0x1;
const SERIAL_DATA_BITS_7 uint32 = 0x2;
const SERIAL_DATA_BITS_8 uint32 = 0x3;
const SERIAL_DATA_BITS_MASK uint32 = 0x3;

// Select the number of stop bits
const SERIAL_STOP_BITS_1 uint32 = 0x0;
const SERIAL_STOP_BITS_2 uint32 = 0x4;
const SERIAL_STOP_BITS_MASK uint32 = 0x4;

// Select the parity mechanism
const SERIAL_PARITY_NONE uint32 = 0x00;
const SERIAL_PARITY_EVEN uint32 = 0x08;
const SERIAL_PARITY_ODD uint32 = 0x10;
const SERIAL_PARITY_MASK uint32 = 0x18;

// Select the flow control mechanism
const SERIAL_FLOW_CTRL_NONE uint32 = 0x00;
const SERIAL_FLOW_CTRL_CTS_RTS uint32 = 0x20;
const SERIAL_FLOW_CTRL_MASK uint32 = 0x20;

// Set this flag to change baud rate but leave other properties unchanged
const SERIAL_SET_BAUD_RATE_ONLY uint32 = 0x80000000;

// End of `flags` that can be passed to Config.
@transport("Driver")
open protocol Device {
    flexible GetInfo() -> (struct {
        info fuchsia.hardware.serial.SerialPortInfo;
    }) error zx.Status;

    /// Configures the given serial port.
    /// Values of `flags` are defined in the constants above.
    flexible Config(struct {
        baud_rate uint32;
        flags uint32;
    }) -> () error zx.Status;

    /// Enable or disable the device.
    /// If already enabled and `enable` is true, this is a no-op and returns successfully.
    /// If already disabled and `enable` is false, this is a no-op and returns successfully.
    ///
    /// + request `enable` true to enable the device, or false to disable it.
    /// * error one of the following values:
    /// *     `ZX_ERR_BAD_STATE`: `enable` was false, and a `Read()` or `Write()` call was pending.
    flexible Enable(struct {
        enable bool;
    }) -> () error zx.Status;

    /// Perform a read operation. Returns immediately if data has been received since the last call;
    /// otherwise the request is completed the next time data is received (clients can use the
    /// hanging-get pattern to be notified of new data).
    ///
    /// - response `data` the bytes read from the device.
    /// * error one of the following values:
    /// *     `ZX_ERR_BAD_STATE`: The device was not enabled.
    /// *     `ZX_ERR_CANCELED`: The call was canceled by `CancelAll()`.
    /// *     `ZX_ERR_ALREADY_BOUND`: Another `Read()` call was already pending.
    /// *     Other values may be returned for driver- or device-specific errors.
    flexible Read() -> (struct {
        data vector<uint8>:MAX;
    }) error zx.Status;

    /// Perform a write operation. Returns when all bytes have been written, or when an error is
    /// encountered.
    ///
    /// + request `data` the bytes to write to the device.
    /// * error one of the following values:
    /// *     `ZX_ERR_BAD_STATE`: The device was not enabled.
    /// *     `ZX_ERR_CANCELED`: The call was canceled by `CancelAll()`.
    /// *     `ZX_ERR_ALREADY_BOUND`: Another `Write()` call was already pending.
    /// *     Other values may be returned for driver- or device-specific errors.
    flexible Write(struct {
        data vector<uint8>:MAX;
    }) -> () error zx.Status;

    /// Immediately cancels all outstanding asynchronous I/O
    flexible CancelAll() -> ();
};

service Service {
    device client_end:Device;
};