// Copyright 2021 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.device;

using fuchsia.lowpan;

/// Protocol for connecting to [`Counters`] on a LoWPAN
/// interface.
@discoverable
protocol CountersConnector {
    /// Connects to the [`DeviceCounters`] 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.
    Connect(resource struct {
        name fuchsia.lowpan.InterfaceName;
        server_end server_end:Counters;
    });
};

protocol Counters {
    /// Returns a snapshot of the counters without resetting the counters.
    Get() -> (struct {
        counters AllCounters;
    });

    /// Resets all of the counters to zero returning the counter values
    /// immediately prior.
    Reset() -> (struct {
        counters AllCounters;
    });
};

/// Describes all counters.
///
/// May be empty if no counters are supported.
type AllCounters = table {
    /// MAC Counters for TX
    1: mac_tx MacCounters;

    /// MAC Counters for RX
    2: mac_rx MacCounters;

    /// Coex Counters for TX
    3: coex_tx CoexCounters;

    /// Coex Counters for RX
    4: coex_rx CoexCounters;

    /// Coex stats may be incorrect due to internal counter overflow.
    ///
    /// Reset the counters to clear this flag.
    5: coex_saturated bool;

    /// IP Counters for TX.
    @available(added=8)
    6: ip_tx IpCounters;

    /// IP Counters for RX.
    @available(added=8)
    7: ip_rx IpCounters;
};

/// Counters associated with the MAC layer.
///
/// Some counters are only valid for RX or TX.
type MacCounters = table {
    /// The total number of frames
    1: total uint32;

    /// The total number of unicast frames
    2: unicast uint32;

    /// The total number of broadcast frames
    3: broadcast uint32;

    /// The number of frames with ack request
    4: ack_requested uint32;

    /// The number of frames that were acked
    5: acked uint32;

    /// The number of frames without ack request
    6: no_ack_requested uint32;

    /// The number of data frames
    7: data uint32;

    /// The number of data poll frames
    8: data_poll uint32;

    /// The number of beacon frames
    9: beacon uint32;

    /// The number of beacon request frames
   10: beacon_request uint32;

    /// The number of other types of frames
   11: other uint32;

    /// The number of frames filtered by address filter (allowlist
    /// or denylist).
   12: address_filtered uint32;

    /// The number of retransmission attempts.
    /// TX only.
   13: retries uint32;

    /// The number of expired retransmission retries for direct message.
    /// TX only.
   14: direct_max_retry_expiry uint32;

    /// The number of expired retransmission retries for indirect message
    /// TX only.
   15: indirect_max_retry_expiry uint32;

    /// The number of received frames filtered by destination check.
    /// RX only.
   16: dest_addr_filtered uint32;

    /// The number of received duplicated frames.
    /// RX only.
   17: duplicated uint32;

    /// The number of received frames with no or malformed content.
    /// RX only.
   18: err_no_frame uint32;

    /// The number of received frames from unknown neighbor.
    /// RX only.
   19: err_unknown_neighbor uint32;

    /// The number of received frames whose source address is invalid.
    /// RX only.
   20: err_invalid_src_addr uint32;

    /// The number of received frames with security error.
    /// RX only.
   21: err_sec uint32;

    /// The number of received frames with FCS error.
    /// RX only.
   22: err_fcs uint32;

    /// The number of CCA failures.
    /// TX only.
   23: err_cca uint32;

    /// The number of frame transmission failures due to abort error.
    /// TX only.
   24: err_abort uint32;

    /// The number of frames that were dropped due to a busy channel.
    /// TX only.
   25: err_busy_channel uint32;

    /// The number of frames that encountered some other error.
   26: err_other uint32;
};

/// Counters associated with RF Coexistance.
///
/// Some counters are only valid for RX or TX. See [this][1] for more info.
///
/// [1]: https://github.com/openthread/wpantund/blob/4ae4619/third_party/openthread/src/ncp/spinel.h#L1738-L1775
type CoexCounters = table {
    /// The number of requests
    1: requests uint64;

    /// The number of requests while grant was active
    2: grant_immediate uint64;

    /// The number of requests while grant was inactive
    3: grant_wait uint64;

    /// The number of requests while grant was inactive that were
    /// ultimately granted
    4: grant_wait_activated uint64;

    /// The number of requests while grant was inactive that timed out
    5: grant_wait_timeout uint64;

    /// The number of requests that were in progress when grant was
    /// deactivated
    6: grant_deactivated_during_request uint64;

    /// The number of requests that were not granted within 50µs
    7: delayed_grant uint64;

    /// The average time in µsec from request to grant
    8: avg_delay_request_to_grant_usec uint32;

    /// The number of requests that completed without receiving grant.
    ///
    /// Receive only.
    9: grant_none uint64;
};

/// Counters associated with the IP layer.
@available(added=8)
type IpCounters = table {
    /// The number of IPv6 packets successfully transmitted/received.
    1: success uint32;

    /// The number of IPv6 packets failed to transmit/receive.
    2: failure uint32;
};