sdk/fidl/fuchsia.lowpan.experimental/telemetry.fidl

// Copyright 2022 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.experimental;

using fuchsia.lowpan;
using zx;

/// Protocol for connecting to [`TelemetryProvider`] on a LoWPAN interface.
@discoverable
closed protocol TelemetryProviderConnector {
    /// Connects to the [`TelemetryProvider`] 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:TelemetryProvider;
    });
};

/// Provides telemetry data for an individual interface to the LoWPAN service.
closed protocol TelemetryProvider {
    /// Returns a snapshot the telemetry information table.
    strict GetTelemetry() -> (struct {
        telemetry Telemetry;
    });
};

/// Counters associated with border routing.
type BorderRoutingCounters = table {
    /// The number of packets associated with inbound unicast messages.
    ///
    /// Required.
    1: inbound_unicast_packets uint64;

    /// The number of bytes associated with inbound unicast messages.
    ///
    /// Required.
    2: inbound_unicast_bytes uint64;

    /// The number of packets associated with inbound multicast messages.
    ///
    /// Required.
    3: inbound_multicast_packets uint64;

    /// The number of bytes associated with inbound multicast messages.
    ///
    /// Required.
    4: inbound_multicast_bytes uint64;

    /// The number of packets associated with outbound unicast messages.
    ///
    /// Required.
    5: outbound_unicast_packets uint64;

    /// The number of bytes associated with outbound unicast messages.
    ///
    /// Required.
    6: outbound_unicast_bytes uint64;

    /// The number of packets associated with outbound multicast messages.
    ///
    /// Required.
    7: outbound_multicast_packets uint64;

    /// The number of bytes associated with outbound multicast messages.
    ///
    /// Required.
    8: outbound_multicast_bytes uint64;

    /// The number of received RA packets.
    ///
    /// Required.
    9: ra_rx uint32;

    /// The number of RA packets successfully transmitted.
    ///
    /// Required.
    10: ra_tx_success uint32;

    /// The number of RA packets failed to transmit.
    ///
    /// Required.
    11: ra_tx_failure uint32;

    /// The number of received RS packets.
    ///
    /// Required.
    12: rs_rx uint32;

    /// The number of RS packets successfully transmitted.
    ///
    /// Required.
    13: rs_tx_success uint32;

    /// The number of RS packets failed to transmit.
    ///
    /// Required.
    14: rs_tx_failure uint32;

    /// Inbound Internet packets when DHCPv6 PD enabled.
    ///
    /// Optional.
    15: inbound_internet_packets uint64;

    /// Inbound Internet bytes when DHCPv6 PD enabled.
    ///
    /// Optional.
    16: inbound_internet_bytes uint64;

    /// Outbound Internet packets when DHCPv6 PD enabled.
    ///
    /// Optional.
    17: outbound_internet_packets uint64;

    /// Outbound Internet bytes when DHCPv6 PD enabled.
    ///
    /// Optional.
    18: outbound_internet_bytes uint64;
};

/// Represents the count of queries, responses, failures handled by upstream DNS server
///
/// Derived from `otUpstreamDnsCounters`(https://openthread.io/reference/group/api-dnssd-server)
type UpstreamDnsCounters = table {
    /// The number of queries forwarded
    ///
    /// Required.
    1: queries uint32;

    /// The number of responses forwarded
    ///
    /// Required.
    2: responses uint32;

    /// The number of upstream DNS failures
    ///
    /// Required.
    3: failures uint32;
};

/// Counters associated with the DNS-SD server.
type DnssdCounters = table {
    /// The number of successful responses.
    ///
    /// Required.
    1: success_response uint32;

    /// The number of 'server failure' responses.
    ///
    /// Required.
    2: server_failure_response uint32;

    /// The number of 'format error' responses.
    ///
    /// Required.
    3: format_error_response uint32;

    /// The number of 'name error' responses.
    ///
    /// Required.
    4: name_error_response uint32;

    /// The number of 'not implemented' responses.
    ///
    /// Required.
    5: not_implemented_response uint32;

    /// The number of 'other' responses.
    ///
    /// Required.
    6: other_response uint32;

    /// The number of queries completely resolved by the local SRP server.
    ///
    /// Required.
    7: resolved_by_srp uint32;

    /// The counters of upstream DNS feature.
    ///
    /// Optional.
    8: upstream_dns_counters UpstreamDnsCounters;
};

/// Registration information about the SRP server.
type SrpServerRegistration = table {
    /// Number of hosts/services that have not been deleted.
    ///
    /// Required.
    1: fresh_count uint32;

    /// Number of hosts/services that have been deleted.
    ///
    /// Required.
    2: deleted_count uint32;

    /// Total lease time.
    ///
    /// Required.
    3: lease_time_total zx.Duration;

    /// Total key lease time.
    ///
    /// Required.
    4: key_lease_time_total zx.Duration;

    /// Total remaining lease time.
    ///
    /// Required.
    5: remaining_lease_time_total zx.Duration;

    /// Total remaining key lease time.
    ///
    /// Required.
    6: remaining_key_lease_time_total zx.Duration;
};

/// State information about the SRP server.
type SrpServerInfo = table {
    /// The operational state of the SRP server.
    ///
    /// Required.
    1: state @generated_name("SrpServerState") strict enum {
        /// The server is disabled.
        DISABLED = 1;
        /// The server is enabled and running.
        RUNNING = 2;
        /// The server is enabled, but stopped.
        STOPPED = 3;
    };

    /// The port the SRP server is listening to.
    ///
    /// Optional. The port may be omitted when `state` is `DISABLED`.
    2: port uint16;

    /// The address mode of the SRP server.
    ///
    /// Required.
    3: address_mode @generated_name("SrpServerAddressMode") strict enum {
        /// Thread network data is published as unicast addresses.
        UNICAST = 1;
        /// Thread network data is published as anycast addresses.
        ANYCAST = 2;
    };

    /// The response counters of the SRP server.
    ///
    /// Required.
    4: response_counters @generated_name("SrpServerResponseCounters") table {
        /// The number of successful responses.
        ///
        /// Required.
        1: success_response uint32;

        /// The number of 'server failure' responses.
        ///
        /// Required.
        2: server_failure_response uint32;

        /// The number of 'format error' responses.
        ///
        /// Required.
        3: format_error_response uint32;

        /// The number of 'name exists' responses.
        ///
        /// Required.
        4: name_exists_response uint32;

        /// The number of 'refused' responses.
        ///
        /// Required.
        5: refused_response uint32;

        /// The number of 'other' responses.
        ///
        /// Required.
        6: other_response uint32;
    };

    /// The registration information of SRP hosts.
    ///
    /// Required.
    5: hosts_registration SrpServerRegistration;

    /// The registration information of SRP services.
    ///
    /// Required.
    6: services_registration SrpServerRegistration;
};


/// Node information for Thread network leaders.
type LeaderData = table {
    /// The network partition ID of the leader.
    ///
    /// Required.
    1: partition_id uint32;

    /// The weight of this leader on the network.
    ///
    /// Required.
    2: weight uint8;

    /// The full network data version.
    ///
    /// Required.
    3: network_data_version uint8;

    /// The stable network data version.
    ///
    /// Required.
    4: stable_network_data_version uint8;

    /// The router ID of the leader.
    ///
    /// Required.
    5: router_id uint8;
};

type Nat64State = flexible enum {
    NAT64_STATE_UNSPECIFIED = 0;
    NAT64_STATE_DISABLED = 1;
    NAT64_STATE_NOT_RUNNING = 2;
    NAT64_STATE_IDLE = 3;
    NAT64_STATE_ACTIVE = 4;
};

/// Information about the state of components of NAT64
type BorderRoutingNat64State = table {
    /// prefix manager state
    1: prefix_manager_state Nat64State;
    /// translator state
    2: translator_state Nat64State;
};

type Nat64TrafficCounters = table {
    /// Number of packets translated from IPv4 to IPv6
    1: ipv4_to_ipv6_packets uint64;
    /// Sum of size of packets translated from IPv4 to IPv6
    2: ipv4_to_ipv6_bytes uint64;
    /// Number of packets translated from IPv6 to IPv4
    3: ipv6_to_ipv4_packets uint64;
    /// Sum of size of packets translated from IPv6 to IPv4
    4: ipv6_to_ipv4_bytes uint64;
};

type Nat64ProtocolCounters = table {
    /// TCP counters
    1: tcp Nat64TrafficCounters;
    /// UDP counters
    2: udp Nat64TrafficCounters;
    /// ICMP counters
    3: icmp Nat64TrafficCounters;
    /// Total counters
    4: total Nat64TrafficCounters;
};

/// Information about the mappings of NAT64 translator
type Nat64Mapping = table {
    /// The unique id for a mapping session
    1: mapping_id uint64;
    /// The IPv4 address of the mapping
    2: ip4_addr vector<uint8>:MAX;
    /// The IPv6 address of the mapping
    3: ip6_addr vector<uint8>:MAX;
    /// Remaining time before expiry in milliseconds
    4: remaining_time_ms uint32;
    /// Nat64 Counters
    5: counters Nat64ProtocolCounters;
};

type Nat64PacketCounters = table {
    /// Number of packets translated from IPv4 to IPv6
    1: ipv4_to_ipv6_packets uint64;
    /// Number of packets translated from IPv6 to IPv4
    2: ipv6_to_ipv4_packets uint64;
};

type Nat64ErrorCounters = table {
    /// Packet drop for unknown reasons
    1: unknown Nat64PacketCounters;
    /// Packet drop due to failed to parse the datagram
    2: illegal_packet Nat64PacketCounters;
    /// Packet drop due to unsupported IP protocol
    3: unsupported_protocol Nat64PacketCounters;
    /// Packet drop due to no mappings found or mapping pool exhausted
    4: no_mapping Nat64PacketCounters;
};

type Nat64Info = table {
    /// NAT64 border routing state
    1: nat64_state BorderRoutingNat64State;
    /// NAT64 mapping
    2: nat64_mappings vector<Nat64Mapping>:MAX;
    /// NAT64 error counters
    3: nat64_error_counters Nat64ErrorCounters;
    /// NAT64 protocol counters
    4: nat64_protocol_counters Nat64ProtocolCounters;
};

/// Represents a group of TREL related counters in the platform layer.
///
/// Derived from [`otPlatTrelCounters`](https://openthread.io/reference/struct/ot-plat-trel-counters).
type TrelCounters = table {
    /// Sum of size of packets received through TREL.
    1: rx_bytes uint64;

    /// Number of packets received through TREL.
    2: rx_packets uint64;

    /// Sum of size of packets successfully transmitted through TREL.
    3: tx_bytes uint64;

    /// Number of packet transmission failures through TREL.
    4: tx_failure uint64;

    /// Number of packets successfully transmitted through TREL.
    5: tx_packets uint64;
};

/// Represents the TREL peer related info.
///
/// The info is available in OpenThread via https://openthread.io/reference/group/api-trel
/// More fields may be added per request.
type TrelPeersInfo = table {
    /// Number of TREL peers for this Thread Border Router.
    ///
    /// Required.
    1: num_trel_peers uint16;
};

/// Represents the Upstream DNS state
type UpstreamDnsQueryState = flexible enum {
    UPSTREAMDNS_QUERY_STATE_UNSPECIFIED = 0;
    UPSTREAMDNS_QUERY_STATE_ENABLED = 1;
    UPSTREAMDNS_QUERY_STATE_DISABLED = 2;
};

/// Represents the Upstream DNS related info.
///
/// The info is available in OpenThread via https://openthread.io/reference/group/api-dnssd-server
/// More fields may be added per request.
type UpstreamDnsInfo = table {
    /// State of upstream DNS query.
    ///
    /// Required.
    1: upstream_dns_query_state UpstreamDnsQueryState;
};

/// Platform counters related to processed RA info when DHCPv6 PD is enabled.
type PdProcessedRaInfo = table {
    /// The number of platform generated RA handled by ApplyPlatformGeneratedRa.
    ///
    /// Required.
    1: num_platform_ra_received uint32;

    /// The number of PIO processed for adding OMR prefixes.
    ///
    /// Required.
    2: num_platform_pio_processed uint32;

    /// The duration since the last processed RA message.
    ///
    /// Required.
    3: last_platform_ra_msec uint32;
};

/// Represents the DHCPv6 PD state.
type Dhcp6PdState = flexible enum {
    DHCP6_PD_STATE_UNSPECIFIED = 0;

    /// DHCPv6 PD is disabled on the border router.
    DHCP6_PD_STATE_DISABLED = 1;

    /// DHCPv6 PD is enabled but won't try to request and publish a prefix.
    DHCP6_PD_STATE_STOPPED = 2;

    /// DHCPv6 PD is enabled and will try to request and publish a prefix.
    DHCP6_PD_STATE_RUNNING = 3;
};

/// DHCPv6 PD related info.
type Dhcp6PdInfo = table {
    /// DHCPv6 PD state.
    ///
    /// Required.
    1: dhcp6pd_state Dhcp6PdState;

    /// DHCPv6 PD processed RA Info.
    ///
    /// Optional.
    2: pd_processed_ra_info PdProcessedRaInfo;

    /// DHCPv6 PD prefix.
    ///
    /// Optional.
    // Choose the 32 bytes as SHA256 is used.
    // Reference: https://github.com/openthread/ot-br-posix/pull/2110
    3: hashed_pd_prefix vector<uint8>:32;
};

/// LoWPAN Interface Telemetry Information.
///
/// The fields in this table are used for providing low-level telemetry and information about the
/// LoWPAN interface for debugging and statistics purposes.
///
/// All fields are optional.
type Telemetry = table {
    /// The current RSSI of the radio.
    1: rssi fuchsia.lowpan.PowerDbm;

    /// The configured transmit power of the radio.
    2: tx_power fuchsia.lowpan.PowerDbm;

    /// The current channel index of the radio.
    3: channel_index fuchsia.lowpan.ChannelIndex;

    /// The partition ID of the currently associated network partition.
    4: partition_id uint32;

    /// The version string describing the underlying mesh stack.
    5: stack_version string:256;

    /// The version string describing the underlying radio control firmware.
    6: rcp_version string:256;

    /// Thread link mode byte.
    ///
    /// Only present on Thread networks.
    ///
    /// Defined by section 4.5.2 of the Thread 1.1.1 specification ("Mode TLV").
    7: thread_link_mode uint8;

    /// The router ID of this device in the currently associated network.
    ///
    /// Only present on Thread networks.
    8: thread_router_id uint8;

    /// The current RLOC16 address of this node.
    ///
    /// Only present on Thread networks.
    9: thread_rloc uint16;

    /// The full network data version.
    ///
    /// Only present on Thread networks.
    10: thread_network_data_version uint8;

    /// The stable network data version.
    ///
    /// Only present on Thread networks.
    11: thread_stable_network_data_version uint8;

    /// The current Thread network data, in raw binary form, as defined in section 5.13 of
    /// the Thread 1.1.1 specification.
    ///
    /// Only present on Thread networks.
    12: thread_network_data vector<uint8>:255;

    /// The current Thread stable network data, in raw binary form, as defined in section 5.13 of
    /// the Thread 1.1.1 specification.
    ///
    /// Only present on Thread networks.
    13: thread_stable_network_data vector<uint8>:255;

    /// The counters associated with border routing messages.
    ///
    /// Only present on Thread networks.
    14: thread_border_routing_counters BorderRoutingCounters;

    /// The SRP server information.
    ///
    /// Only present on Thread networks.
    15: srp_server_info SrpServerInfo;

    /// The DNS-SD server counters.
    ///
    /// Only present on Thread networks.
    16: dnssd_counters DnssdCounters;

    /// The data associated with the leader of the currently associated Thread network.
    ///
    /// Only present on Thread networks.
    17: leader_data LeaderData;

    /// The uptime of the current instance.
    ///
    /// Required.
    18: uptime zx.Duration;

    /// Information about the NAT64
    ///
    /// Only present on Thread networks.
    19: nat64_info Nat64Info;

    /// Information about the TREL interface, if available.
    ///
    /// Only present on Thread networks.
    20: trel_counters TrelCounters;

    /// Information about the TREL peers, if available.
    ///
    /// Only present on Thread networks.
    21: trel_peers_info TrelPeersInfo;

    /// Information about the Upstream DNS feature, if available.
    ///
    /// Only present on Thread networks.
    22: upstream_dns_info UpstreamDnsInfo;

    /// Information about the DHCPv6 PD feature, if available.
    ///
    /// Only present on Thread networks.
    23: dhcp6pd_info Dhcp6PdInfo;
};