// Copyright 2020 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.lowpan.test;

using fuchsia.lowpan;
using zx;

const MAX_NEIGHBORS uint32 = 1024;

/// Protocol for connecting to [`DeviceTest`] on a LoWPAN
/// interface.
@discoverable
closed protocol DeviceTestConnector {
    /// Connects to the [`DeviceTest`] protocol on the
    /// named LoWPAN interface.
    ///
    /// The name of the interface can be learned by calling
    /// [`fuchsia.lowpan/Lookup.GetDevices`].
    ///
    /// If there is an error in processing this request
    /// the given channel is closed and an epitaph code used
    /// to describe the reason for the failure:
    ///
    /// * `ZX_ERR_INVALID_ARGUMENT`: The given interface name
    ///   was not formatted correctly or otherwise invalid.
    /// * `ZX_ERR_NOT_FOUND`: No interface was found with the
    ///   given name.
    /// * `ZX_ERR_NOT_SUPPORTED`: The interface exists but
    ///   does not support this protocol.
    strict Connect(resource struct {
        name fuchsia.lowpan.InterfaceName;
        server_end server_end:DeviceTest;
    });
};

closed protocol DeviceTest {
    /// Resets this network interface, returning
    /// all volatile state to default values. Any
    /// information stored in non-volatile memory
    /// is preserved. If the interface was attached
    /// to a network, this method will cause the
    /// interface to detach. In that case, once the
    /// interface has finished initialization the
    /// interface will attempt to reattach to the
    /// previous network.
    strict Reset() -> ();

    /// Returns the version string describing the firmware/stack
    /// version that is in use.
    strict GetNcpVersion() -> (struct {
        version string:256;
    });

    /// Returns the current RSSI measured by the radio.
    strict GetCurrentRssi() -> (struct {
        rssi fuchsia.lowpan.PowerDbm;
    });

    /// Returns the factory-assigned static MAC address.
    strict GetFactoryMacAddress() -> (struct {
        address fuchsia.lowpan.MacAddress;
    });

    /// Returns the currently used MAC address, which can
    /// differ from the static factory-assigned MAC address.
    strict GetCurrentMacAddress() -> (struct {
        address fuchsia.lowpan.MacAddress;
    });

    /// Returns the current channel index for the radio.
    strict GetCurrentChannel() -> (struct {
        channel_index fuchsia.lowpan.ChannelIndex;
    });

    /// Returns the partition ID of the currently associated
    /// network partition.
    strict GetPartitionId() -> (struct {
        pid uint32;
    });

    strict GetThreadRloc16() -> (struct {
        rloc uint16;
    });

    strict GetThreadRouterId() -> (struct {
        router_id uint8;
    });

    /// Updates the address filter settings.
    ///
    /// Responds once the filter settings have taken effect.
    strict ReplaceMacAddressFilterSettings(struct {
        settings MacAddressFilterSettings;
    }) -> ();

    /// Returns the current address filter settings.
    strict GetMacAddressFilterSettings() -> (struct {
        settings MacAddressFilterSettings;
    });

    /// Returns a snapshot of the current neighbor table.
    strict GetNeighborTable() -> (struct {
        neighbor_table vector<NeighborInfo>:MAX_NEIGHBORS;
    });
};

/// An item in the MAC filter list.
type MacAddressFilterItem = table {
    /// The MAC address of the item. This field is required.
    1: mac_address fuchsia.lowpan.MacAddress;

    /// Replacement RSSI value for packets received from this address.
    ///
    /// This field is ignored unless the mode is set to `MacAddressFilterMode::ALLOW`.
    ///
    /// This value is substituted for all received packets. This can affect
    /// what the mesh topology ultimately looks like.
    2: rssi int8;
};

/// Maximum number of addresses that can be in the address filter list.
const MAX_FILTERED uint16 = 100;

type MacAddressFilterSettings = table {
    /// Address filter mode.
    ///
    /// This field is required. If this field is absent when passed to
    /// `ReplaceMacAddressFilterSettings`, the channel will be closed with
    /// the epitaph `ZX_ERR_INVALID_ARGUMENT`.
    1: mode MacAddressFilterMode;

    /// Addresses to be filtered.
    ///
    /// If this field is absent it is assumed to be empty.
    2: items vector<MacAddressFilterItem>:MAX_FILTERED;
};

/// Describes the address filtering mode of the interface.
type MacAddressFilterMode = strict enum : int32 {
    /// Address filtering is disabled. All packets that are
    /// received are processed normally.
    DISABLED = 0;

    /// Only packets that have addresses matching an address
    /// in the filter list will be allowed to be processed.
    /// All other packets are dropped as if they were never
    /// received.
    ///
    /// Additionally, if an RSSI value was associated
    /// with an item, that value will be substituted for internal
    /// routing considerations.
    ALLOW = 1;

    /// All packets from addresses in the filter list will be
    /// dropped.
    DENY = 2;
};

/// Neighbor Table Entry
///
/// All fields are optional except for `mac_address`.
///
/// See also:
///   * https://openthread.io/reference/struct/ot-neighbor-info
///   * https://openthread.io/reference/struct/ot-child-info
///   * https://github.com/openthread/wpantund/blob/8db2a71c9597e08949dfc38d8c10f830e3de565c/third_party/openthread/src/ncp/spinel.h#L2356-L2373
type NeighborInfo = table {
    /// The MAC address of the neighbor.
    ///
    /// Note that this is the only field guaranteed to be present.
    1: mac_address fuchsia.lowpan.MacAddress;

    /// 802.15.4 short address of neighbor.
    ///
    /// On Thread networks, this is also the RLOC16.
    2: short_address uint16;

    /// The age of this entry in the neighbor table.
    ///
    /// Describes when this neighbor was last seen.
    /// Resolution is roughly +/- 1sec.
    3: age zx.Duration;

    /// True if this neighbor is considered a child and is thus
    /// entirely dependent on this device for routing.
    ///
    /// If absent, assumed to be false.
    4: is_child bool;

    /// The number of link (non-management) frames received from this neighbor.
    5: link_frame_count uint32;

    /// The number of management (MLE, etc) frames received from this neighbor.
    6: mgmt_frame_count uint32;

    /// RSSI of the most recent packet received from the neighbor.
    7: last_rssi_in int32;

    /// Average/typical RSSI of packets received from the neighbor.
    8: avg_rssi_in int8;

    /// LQI of the most recent packet received from the neighbor.
    ///
    /// Value is between 1 and 255, with 1 being the worst possible
    /// link quality (any worse and it would not have been decoded)
    /// and 255 being perfect reception. All values in between
    /// are a roughly linear (but not well defined) extrapolation
    /// between these two extremes.
    ///
    /// Zero values must not be encoded, but if encountered should be
    /// interpreted as if the LQI field were absent.
    ///
    /// In 802.15.4 networks, LQI is typically determined by the number of
    /// "chip errors" when decoding the packets.
    9: lqi_in uint8;

    /// Thread Mode TLV. Only present on Thread networks.
    ///
    /// Defined by section 4.5.2 of the Thread 1.1.1 specification ("Mode TLV").
    10: thread_mode uint8;

    /// Frame error rate.
    ///
    /// `0xffff` indicates 100%, `0x0000` indicates 0%.
    11: frame_error_rate uint16;

    /// IPv6 message error rate.
    ///
    /// `0xffff` indicates 100%, `0x0000` indicates 0%.
    12: ipv6_error_rate uint16;

    /// True if the child is CSL synced.
    ///
    /// CSL is Coordinated Sampled Listening, a mechanism for sleepy devices
    /// to perform indirect TX.
    13: child_is_csl_synced bool;

    /// True if the child is restoring state.
    14: child_is_state_restoring bool;

    /// Version of NetData that the neighbor has.
    15: net_data_version uint8;

    /// Number of messages queued for the neighbor.
    16: queued_messages uint16;

    /// MLE version for the neighbor.
    17: thread_mle_version uint8;
};