sdk/fidl/fuchsia.hardware.network.driver/network-mac.fidl

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

using fuchsia.hardware.network;
using fuchsia.net;

/// The length of an IEEE 802 MAC Address, in bytes.
const MAC_SIZE uint64 = 6;
/// The maximum number of multicast MAC addresses set to filter.
// NOTE(brunodalbo) this number derived from common defaults for maximum
// multicast membership allowances in established OSes (20-40) rounded up for
// some leeway. It should be noted that typical hardware implementations don't
// keep perfect filtering lists, but rather use a special hash function to
// perform the filtering, where collisions are tolerated since the filtering is
// just a performance feature.
const MAX_MAC_FILTER uint64 = 64;

/// Device MAC filtering modes supported.
///
/// The variants of this type should match
/// fuchsia.hardware.network.MacFilterMode.
// LINT.IfChange
type SupportedMacFilterMode = strict bits {
    /// Device accepts only unicast frames addressed to its own unicast address,
    /// or multicast frames that are part of the multicast address filter list.
    MULTICAST_FILTER = 1;
    /// Device accepts unicast frames addressed to its own unicast address, or
    /// any multicast frames.
    MULTICAST_PROMISCUOUS = 2;
    /// Device accepts all frames.
    PROMISCUOUS = 4;
};
// LINT.ThenChange(/sdk/fidl/fuchsia.hardware.network/mac.fidl)

/// Device features reported by [`MacAddr.GetFeatures`].
type Features = table {
    /// The maximum number of multicast filtering entries available on this
    /// device.
    ///
    /// Implementations must set 0 if multicast filtering is not supported.
    /// Values will always be saturated to [`MAX_MAC_FILTER`].
    /// Optional, interpreted as zero if absent.
    1: multicast_filter_count uint32;
    /// The filtering operating modes supported by this device.
    ///
    /// Bitfield of possible [`SupportedMacFilterMode`] values that can be passed to
    /// [`MacAddr.SetMode`].
    // Optional, interpreted as an empty set if absent.
    2: supported_modes SupportedMacFilterMode;
};

@transport("Driver")
@banjo_layout("ddk-interface")
closed protocol MacAddr {
    /// Gets this device's MAC address.
    // TODO(https://fxbug.dev/42120438) we need an address changed event (in
    // lockstep with FIDL definition).
    // TODO(brunodalbo) use fuchsia.net.MacAddress here and in SetMode when we
    // can use FIDL types in Banjo.
    strict GetAddress() -> (struct {
        mac fuchsia.net.MacAddress;
    });
    /// Gets this device's features.
    strict GetFeatures() -> (struct {
        features Features;
    });
    /// Sets this device's operating mode.
    ///
    /// `mode` is one of the variants in [`Mode`], it's guaranteed to be one of
    /// the reported modes in this device's reported features. `multicast_macs`
    /// is only provided (though it can still be empty) when `mode` is
    /// `MULTICAST_FILTER`. `multicast_macs` is always guaranteed to be at most
    /// `multicast_filter_count` entries.
    strict SetMode(struct {
        mode fuchsia.hardware.network.MacFilterMode;
        multicast_macs vector<fuchsia.net.MacAddress>:MAX_MAC_FILTER;
    }) -> ();
};