netstack3_device/
base.rs

1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use core::fmt::{Debug, Display};
6use core::num::NonZeroU64;
7
8use derivative::Derivative;
9use lock_order::lock::{OrderedLockAccess, OrderedLockRef};
10use net_types::ethernet::Mac;
11use net_types::ip::{Ip, IpVersion, Ipv4, Ipv6};
12use netstack3_base::sync::RwLock;
13use netstack3_base::{
14    Counter, CounterRepr, Device, DeviceIdContext, HandleableTimer, Inspectable, Inspector,
15    InspectorExt as _, InstantContext, ReferenceNotifiers, TimerBindingsTypes, TimerHandler,
16    TxMetadataBindingsTypes,
17};
18use netstack3_filter::FilterBindingsTypes;
19use netstack3_hashmap::HashMap;
20use netstack3_ip::device::Ipv6LinkLayerAddr;
21use netstack3_ip::nud::{LinkResolutionContext, NudCounters};
22
23use crate::blackhole::{BlackholeDeviceId, BlackholePrimaryDeviceId};
24use crate::internal::arp::ArpCounters;
25use crate::internal::ethernet::{EthernetLinkDevice, EthernetTimerId};
26use crate::internal::id::{
27    BaseDeviceId, BasePrimaryDeviceId, DeviceId, EthernetDeviceId, EthernetPrimaryDeviceId,
28    EthernetWeakDeviceId,
29};
30use crate::internal::loopback::{LoopbackDeviceId, LoopbackPrimaryDeviceId};
31use crate::internal::pure_ip::{PureIpDeviceId, PureIpPrimaryDeviceId};
32use crate::internal::queue::rx::ReceiveQueueBindingsContext;
33use crate::internal::queue::tx::{TransmitQueueBindingsContext, TxBufferAllocator};
34use crate::internal::socket::{self, DeviceSocketCounters, HeldSockets};
35use crate::internal::state::DeviceStateSpec;
36
37/// Iterator over devices.
38///
39/// Implements `Iterator<Item=DeviceId<C>>` by pulling from provided loopback
40/// and ethernet device ID iterators. This struct only exists as a named type
41/// so it can be an associated type on impls of the [`IpDeviceContext`] trait.
42pub struct DevicesIter<'s, BT: DeviceLayerTypes> {
43    pub(super) ethernet:
44        netstack3_hashmap::hash_map::Values<'s, EthernetDeviceId<BT>, EthernetPrimaryDeviceId<BT>>,
45    pub(super) pure_ip:
46        netstack3_hashmap::hash_map::Values<'s, PureIpDeviceId<BT>, PureIpPrimaryDeviceId<BT>>,
47    pub(super) blackhole: netstack3_hashmap::hash_map::Values<
48        's,
49        BlackholeDeviceId<BT>,
50        BlackholePrimaryDeviceId<BT>,
51    >,
52    pub(super) loopback: core::option::Iter<'s, LoopbackPrimaryDeviceId<BT>>,
53}
54
55impl<'s, BT: DeviceLayerTypes> Iterator for DevicesIter<'s, BT> {
56    type Item = DeviceId<BT>;
57
58    fn next(&mut self) -> Option<Self::Item> {
59        let Self { ethernet, pure_ip, blackhole, loopback } = self;
60        ethernet
61            .map(|primary| primary.clone_strong().into())
62            .chain(pure_ip.map(|primary| primary.clone_strong().into()))
63            .chain(blackhole.map(|primary| primary.clone_strong().into()))
64            .chain(loopback.map(|primary| primary.clone_strong().into()))
65            .next()
66    }
67}
68
69/// Supported link layer address types for IPv6.
70#[allow(missing_docs)]
71pub enum Ipv6DeviceLinkLayerAddr {
72    Mac(Mac),
73    // Add other link-layer address types as needed.
74}
75
76impl Ipv6LinkLayerAddr for Ipv6DeviceLinkLayerAddr {
77    fn as_bytes(&self) -> &[u8] {
78        match self {
79            Ipv6DeviceLinkLayerAddr::Mac(a) => a.as_ref(),
80        }
81    }
82
83    fn eui64_iid(&self) -> [u8; 8] {
84        match self {
85            Ipv6DeviceLinkLayerAddr::Mac(a) => a.to_eui64(),
86        }
87    }
88}
89
90/// The identifier for timer events in the device layer.
91#[derive(Derivative)]
92#[derivative(
93    Clone(bound = ""),
94    Eq(bound = ""),
95    PartialEq(bound = ""),
96    Hash(bound = ""),
97    Debug(bound = "")
98)]
99pub struct DeviceLayerTimerId<BT: DeviceLayerTypes>(DeviceLayerTimerIdInner<BT>);
100
101#[derive(Derivative)]
102#[derivative(
103    Clone(bound = ""),
104    Eq(bound = ""),
105    PartialEq(bound = ""),
106    Hash(bound = ""),
107    Debug(bound = "")
108)]
109#[allow(missing_docs)]
110enum DeviceLayerTimerIdInner<BT: DeviceLayerTypes> {
111    Ethernet(EthernetTimerId<EthernetWeakDeviceId<BT>>),
112}
113
114impl<BT: DeviceLayerTypes> From<EthernetTimerId<EthernetWeakDeviceId<BT>>>
115    for DeviceLayerTimerId<BT>
116{
117    fn from(id: EthernetTimerId<EthernetWeakDeviceId<BT>>) -> DeviceLayerTimerId<BT> {
118        DeviceLayerTimerId(DeviceLayerTimerIdInner::Ethernet(id))
119    }
120}
121
122impl<CC, BT> HandleableTimer<CC, BT> for DeviceLayerTimerId<BT>
123where
124    BT: DeviceLayerTypes,
125    CC: TimerHandler<BT, EthernetTimerId<EthernetWeakDeviceId<BT>>>,
126{
127    fn handle(self, core_ctx: &mut CC, bindings_ctx: &mut BT, timer: BT::UniqueTimerId) {
128        let Self(id) = self;
129        match id {
130            DeviceLayerTimerIdInner::Ethernet(id) => core_ctx.handle_timer(bindings_ctx, id, timer),
131        }
132    }
133}
134
135/// The collection of devices within [`DeviceLayerState`].
136#[derive(Derivative)]
137#[derivative(Default(bound = ""))]
138pub struct Devices<BT: DeviceLayerTypes> {
139    /// Collection of Ethernet devices.
140    pub ethernet: HashMap<EthernetDeviceId<BT>, EthernetPrimaryDeviceId<BT>>,
141    /// Collection of PureIP devices.
142    pub pure_ip: HashMap<PureIpDeviceId<BT>, PureIpPrimaryDeviceId<BT>>,
143    /// Collection of blackhole devices.
144    pub blackhole: HashMap<BlackholeDeviceId<BT>, BlackholePrimaryDeviceId<BT>>,
145    /// The loopback device, if installed.
146    pub loopback: Option<LoopbackPrimaryDeviceId<BT>>,
147}
148
149impl<BT: DeviceLayerTypes> Devices<BT> {
150    /// Gets an iterator over available devices.
151    pub fn iter(&self) -> DevicesIter<'_, BT> {
152        let Self { ethernet, pure_ip, blackhole, loopback } = self;
153        DevicesIter {
154            ethernet: ethernet.values(),
155            pure_ip: pure_ip.values(),
156            blackhole: blackhole.values(),
157            loopback: loopback.iter(),
158        }
159    }
160}
161
162/// The state associated with the device layer.
163#[derive(Derivative)]
164#[derivative(Default(bound = ""))]
165pub struct DeviceLayerState<BT: DeviceLayerTypes> {
166    devices: RwLock<Devices<BT>>,
167    /// Device layer origin tracker.
168    pub origin: OriginTracker,
169    /// Collection of all device sockets.
170    pub shared_sockets: HeldSockets<BT>,
171    /// Device socket counters.
172    pub device_socket_counters: DeviceSocketCounters,
173    /// Common device counters.
174    pub counters: DeviceCounters,
175    /// Ethernet counters.
176    pub ethernet_counters: EthernetDeviceCounters,
177    /// PureIp counters.
178    pub pure_ip_counters: PureIpDeviceCounters,
179    /// IPv4 NUD counters.
180    pub nud_v4_counters: NudCounters<Ipv4>,
181    /// IPv6 NUD counters.
182    pub nud_v6_counters: NudCounters<Ipv6>,
183    /// ARP counters.
184    pub arp_counters: ArpCounters,
185}
186
187impl<BT: DeviceLayerTypes> DeviceLayerState<BT> {
188    /// Helper to access NUD counters for an IP version.
189    pub fn nud_counters<I: Ip>(&self) -> &NudCounters<I> {
190        I::map_ip((), |()| &self.nud_v4_counters, |()| &self.nud_v6_counters)
191    }
192}
193
194impl<BT: DeviceLayerTypes> OrderedLockAccess<Devices<BT>> for DeviceLayerState<BT> {
195    type Lock = RwLock<Devices<BT>>;
196    fn ordered_lock_access(&self) -> OrderedLockRef<'_, Self::Lock> {
197        OrderedLockRef::new(&self.devices)
198    }
199}
200
201/// Counters for ethernet devices.
202#[derive(Default)]
203pub struct EthernetDeviceCounters {
204    /// Count of incoming frames dropped due to an unsupported ethertype.
205    pub recv_unsupported_ethertype: Counter,
206    /// Count of incoming frames dropped due to an empty ethertype.
207    pub recv_no_ethertype: Counter,
208}
209
210impl Inspectable for EthernetDeviceCounters {
211    fn record<I: Inspector>(&self, inspector: &mut I) {
212        inspector.record_child("Ethernet", |inspector| {
213            let Self { recv_no_ethertype, recv_unsupported_ethertype } = self;
214            inspector.record_child("Rx", |inspector| {
215                inspector.record_counter("NoEthertype", recv_no_ethertype);
216                inspector.record_counter("UnsupportedEthertype", recv_unsupported_ethertype);
217            });
218        })
219    }
220}
221
222/// Counters for pure IP devices.
223#[derive(Default)]
224pub struct PureIpDeviceCounters {}
225
226impl Inspectable for PureIpDeviceCounters {
227    fn record<I: Inspector>(&self, _inspector: &mut I) {}
228}
229
230/// Counters for blackhole devices.
231pub struct BlackholeDeviceCounters;
232
233impl Inspectable for BlackholeDeviceCounters {
234    fn record<I: Inspector>(&self, _inspector: &mut I) {}
235}
236
237/// Device layer counters.
238#[derive(Default, Debug)]
239#[cfg_attr(
240    any(test, feature = "testutils"),
241    derive(PartialEq, netstack3_macros::CounterCollection)
242)]
243pub struct DeviceCounters<C: CounterRepr = Counter> {
244    /// Count of outgoing frames which enter the device layer (but may or may
245    /// not have been dropped prior to reaching the wire).
246    pub send_total_frames: C,
247    /// Count of frames sent.
248    pub send_frame: C,
249    /// Count of bytes sent.
250    pub send_bytes: C,
251    /// Count of frames that failed to send because of a full Tx queue.
252    pub send_queue_full: C,
253    /// Count of frames that failed to send because of a serialization error.
254    pub send_serialize_error: C,
255    /// Count of frames received.
256    pub recv_frame: C,
257    /// Count of bytes received.
258    pub recv_bytes: C,
259    /// Count of incoming frames dropped due to a parsing error.
260    pub recv_parse_error: C,
261    /// Count of incoming frames containing an IPv4 packet delivered.
262    pub recv_ipv4_delivered: C,
263    /// Count of incoming frames containing an IPv6 packet delivered.
264    pub recv_ipv6_delivered: C,
265    /// Count of sent frames containing an IPv4 packet.
266    pub send_ipv4_frame: C,
267    /// Count of sent frames containing an IPv6 packet.
268    pub send_ipv6_frame: C,
269    /// Count of frames that failed to send because there was no Tx queue.
270    pub send_dropped_no_queue: C,
271    /// Count of frames that were dropped during Tx queue dequeuing.
272    pub send_dropped_dequeue: C,
273}
274
275impl DeviceCounters {
276    /// Either `send_ipv4_frame` or `send_ipv6_frame` depending on `I`.
277    pub fn send_frame<I: Ip>(&self) -> &Counter {
278        match I::VERSION {
279            IpVersion::V4 => &self.send_ipv4_frame,
280            IpVersion::V6 => &self.send_ipv6_frame,
281        }
282    }
283}
284
285impl Inspectable for DeviceCounters {
286    fn record<I: Inspector>(&self, inspector: &mut I) {
287        let Self {
288            recv_frame,
289            recv_bytes,
290            recv_ipv4_delivered,
291            recv_ipv6_delivered,
292            recv_parse_error,
293            send_dropped_no_queue,
294            send_frame,
295            send_bytes,
296            send_ipv4_frame,
297            send_ipv6_frame,
298            send_queue_full,
299            send_serialize_error,
300            send_total_frames,
301            send_dropped_dequeue,
302        } = self;
303        inspector.record_child("Rx", |inspector| {
304            inspector.record_counter("TotalFrames", recv_frame);
305            inspector.record_counter("TotalBytes", recv_bytes);
306            inspector.record_counter("Malformed", recv_parse_error);
307            inspector.record_counter("Ipv4Delivered", recv_ipv4_delivered);
308            inspector.record_counter("Ipv6Delivered", recv_ipv6_delivered);
309        });
310        inspector.record_child("Tx", |inspector| {
311            inspector.record_counter("TotalFrames", send_total_frames);
312            inspector.record_counter("Sent", send_frame);
313            inspector.record_counter("SentBytes", send_bytes);
314            inspector.record_counter("SendIpv4Frame", send_ipv4_frame);
315            inspector.record_counter("SendIpv6Frame", send_ipv6_frame);
316            inspector.record_counter("NoQueue", send_dropped_no_queue);
317            inspector.record_counter("QueueFull", send_queue_full);
318            inspector.record_counter("SerializeError", send_serialize_error);
319            inspector.record_counter("DequeueDrop", send_dropped_dequeue);
320        });
321    }
322}
323/// Light-weight tracker for recording the source of some instance.
324///
325/// This should be held as a field in a parent type that is cloned into each
326/// child instance. Then, the origin of a child instance can be verified by
327/// asserting equality against the parent's field.
328///
329/// This is only enabled in debug builds; in non-debug builds, all
330/// `OriginTracker` instances are identical so all operations are no-ops.
331// TODO(https://fxbug.dev/320078167): Move this and OriginTrackerContext out of
332// the device module and apply to more places.
333#[derive(Clone, Debug, PartialEq)]
334pub struct OriginTracker(#[cfg(debug_assertions)] u64);
335
336impl Default for OriginTracker {
337    fn default() -> Self {
338        Self::new()
339    }
340}
341
342impl OriginTracker {
343    /// Creates a new `OriginTracker` that isn't derived from any other
344    /// instance.
345    ///
346    /// In debug builds, this creates a unique `OriginTracker` that won't be
347    /// equal to any instances except those cloned from it. In non-debug builds
348    /// all `OriginTracker` instances are identical.
349    #[cfg_attr(not(debug_assertions), inline)]
350    fn new() -> Self {
351        Self(
352            #[cfg(debug_assertions)]
353            {
354                static COUNTER: core::sync::atomic::AtomicU64 =
355                    core::sync::atomic::AtomicU64::new(0);
356                COUNTER.fetch_add(1, core::sync::atomic::Ordering::Relaxed)
357            },
358        )
359    }
360}
361
362/// A trait abstracting a context containing an [`OriginTracker`].
363///
364/// This allows API structs to extract origin from contexts when creating
365/// resources.
366pub trait OriginTrackerContext {
367    /// Gets the origin tracker for this context.
368    fn origin_tracker(&mut self) -> OriginTracker;
369}
370
371/// A context providing facilities to store and remove primary device IDs.
372///
373/// This allows the device layer APIs to be written generically on `D`.
374pub trait DeviceCollectionContext<D: Device + DeviceStateSpec, BT: DeviceLayerTypes>:
375    DeviceIdContext<D>
376{
377    /// Adds `device` to the device collection.
378    fn insert(&mut self, device: BasePrimaryDeviceId<D, BT>);
379
380    /// Removes `device` from the collection, if it exists.
381    fn remove(&mut self, device: &BaseDeviceId<D, BT>) -> Option<BasePrimaryDeviceId<D, BT>>;
382}
383
384/// Provides abstractions over the frame metadata received from bindings for
385/// implementers of [`Device`].
386///
387/// This trait allows [`api::DeviceApi`] to provide a single entrypoint for
388/// frames from bindings.
389pub trait DeviceReceiveFrameSpec {
390    /// The frame metadata for ingress frames, where `D` is a device identifier.
391    type FrameMetadata<D>;
392}
393
394/// Provides associated types used in the device layer.
395pub trait DeviceLayerStateTypes: InstantContext + FilterBindingsTypes {
396    /// The state associated with loopback devices.
397    type LoopbackDeviceState: Send + Sync + DeviceClassMatcher<Self::DeviceClass>;
398
399    /// The state associated with ethernet devices.
400    type EthernetDeviceState: Send + Sync + DeviceClassMatcher<Self::DeviceClass>;
401
402    /// The state associated with pure IP devices.
403    type PureIpDeviceState: Send + Sync + DeviceClassMatcher<Self::DeviceClass>;
404
405    /// The state associated with blackhole devices.
406    type BlackholeDeviceState: Send + Sync + DeviceClassMatcher<Self::DeviceClass>;
407
408    /// An opaque identifier that is available from both strong and weak device
409    /// references.
410    type DeviceIdentifier: Send + Sync + Debug + Display + DeviceIdAndNameMatcher;
411}
412
413/// Provides matching functionality for the device class of a device installed
414/// in the netstack.
415pub trait DeviceClassMatcher<DeviceClass> {
416    /// Returns whether the provided device class matches the class of the
417    /// device.
418    fn device_class_matches(&self, device_class: &DeviceClass) -> bool;
419}
420
421/// Provides matching functionality for the ID and name of a device installed in
422/// the netstack.
423pub trait DeviceIdAndNameMatcher {
424    /// Returns whether the provided ID matches the ID of the device.
425    fn id_matches(&self, id: &NonZeroU64) -> bool;
426
427    /// Returns whether the provided name matches the name of the device.
428    fn name_matches(&self, name: &str) -> bool;
429}
430
431/// Trait for associated types used in the device layer.
432pub trait DeviceBufferBindingsTypes: 'static {
433    /// The buffer type stored in transmit queues.
434    type TxBuffer: packet::FragmentedBuffer + AsMut<[u8]> + Send + 'static;
435    /// The allocator for transmit queue buffers.
436    type TxAllocator: TxBufferAllocator<Self::TxBuffer> + Send + 'static;
437}
438
439/// Provides associated types used in the device layer.
440///
441/// This trait groups together state types used throughout the device layer. It
442/// is blanket-implemented for all types that implement
443/// [`socket::DeviceSocketTypes`] and [`DeviceLayerStateTypes`].
444pub trait DeviceLayerTypes:
445    DeviceBufferBindingsTypes
446    + DeviceLayerStateTypes
447    + socket::DeviceSocketTypes
448    + LinkResolutionContext<EthernetLinkDevice>
449    + TimerBindingsTypes
450    + ReferenceNotifiers
451    + TxMetadataBindingsTypes
452    + 'static
453{
454}
455impl<
456    BC: DeviceLayerStateTypes
457        + socket::DeviceSocketTypes
458        + LinkResolutionContext<EthernetLinkDevice>
459        + TimerBindingsTypes
460        + ReferenceNotifiers
461        + TxMetadataBindingsTypes
462        + 'static
463        + DeviceBufferBindingsTypes,
464> DeviceLayerTypes for BC
465{
466}
467
468/// An event dispatcher for the device layer.
469pub trait DeviceLayerEventDispatcher:
470    DeviceLayerTypes
471    + ReceiveQueueBindingsContext<LoopbackDeviceId<Self>>
472    + TransmitQueueBindingsContext<EthernetDeviceId<Self>>
473    + TransmitQueueBindingsContext<LoopbackDeviceId<Self>>
474    + TransmitQueueBindingsContext<PureIpDeviceId<Self>>
475    + Sized
476{
477    /// The transmit queue dequeueing context used by bindings.
478    ///
479    /// `DequeueContext` is a passthrough type from bindings (i.e. entirely
480    /// opaque to core) when using `TransmitQueueApi` to trigger the transmit
481    /// queue to send frames to the underlying devices.
482    type DequeueContext;
483
484    /// Send a frame to an Ethernet device driver.
485    ///
486    /// See [`DeviceSendFrameError`] for the ways this call may fail; all other
487    /// errors are silently ignored and reported as success. Implementations are
488    /// expected to gracefully handle non-conformant but correctable input, e.g.
489    /// by padding too-small frames.
490    ///
491    /// `dequeue_context` is `Some` iff this is called from the context of
492    /// operating the transmit queue via `TransmitQueueApi`.
493    fn send_ethernet_frame(
494        &mut self,
495        device: &EthernetDeviceId<Self>,
496        frame: Self::TxBuffer,
497        dequeue_context: Option<&mut Self::DequeueContext>,
498    ) -> Result<(), DeviceSendFrameError>;
499
500    /// Send an IP packet to an IP device driver.
501    ///
502    /// See [`DeviceSendFrameError`] for the ways this call may fail; all other
503    /// errors are silently ignored and reported as success. Implementations are
504    /// expected to gracefully handle non-conformant but correctable input, e.g.
505    /// by padding too-small frames.
506    ///
507    /// `dequeue_context` is `Some` iff this is called from the context of
508    /// operating the transmit queue via `TransmitQueueApi`.
509    fn send_ip_packet(
510        &mut self,
511        device: &PureIpDeviceId<Self>,
512        packet: Self::TxBuffer,
513        ip_version: IpVersion,
514        dequeue_context: Option<&mut Self::DequeueContext>,
515    ) -> Result<(), DeviceSendFrameError>;
516}
517
518/// An error encountered when sending a frame.
519#[derive(Debug, PartialEq, Eq)]
520pub enum DeviceSendFrameError {
521    /// The device doesn't have available buffers to send frames.
522    NoBuffers,
523}
524
525#[cfg(any(test, feature = "testutils"))]
526pub mod testutil {
527    use alloc::vec::Vec;
528    use netstack3_base::testutil::FakeBindingsCtx;
529    use netstack3_base::{CounterCollection, ResourceCounterContext};
530
531    use super::*;
532    use crate::internal::queue::tx::BufVecU8Allocator;
533
534    /// Expected values of [`DeviceCounters`].
535    pub type DeviceCounterExpectations = DeviceCounters<u64>;
536
537    impl DeviceCounterExpectations {
538        /// Assert that the counters tracked by `core_ctx` match expectations.
539        #[track_caller]
540        pub fn assert_counters<D, CC: ResourceCounterContext<D, DeviceCounters>>(
541            &self,
542            core_ctx: &CC,
543            device: &D,
544        ) {
545            assert_eq!(&core_ctx.counters().cast::<u64>(), self, "stack-wide counters");
546            assert_eq!(
547                &core_ctx.per_resource_counters(device).cast::<u64>(),
548                self,
549                "per-device counters"
550            );
551        }
552    }
553
554    impl<TimerId: 'static, Event: Debug + 'static, State: 'static, FrameMeta: 'static>
555        DeviceBufferBindingsTypes for FakeBindingsCtx<TimerId, Event, State, FrameMeta>
556    {
557        type TxBuffer = packet::Buf<Vec<u8>>;
558        type TxAllocator = BufVecU8Allocator;
559    }
560}
561
562#[cfg(test)]
563mod tests {
564    use super::*;
565
566    #[test]
567    fn origin_tracker() {
568        let tracker = OriginTracker::new();
569        if cfg!(debug_assertions) {
570            assert_ne!(tracker, OriginTracker::new());
571        } else {
572            assert_eq!(tracker, OriginTracker::new());
573        }
574        assert_eq!(tracker.clone(), tracker);
575    }
576}
netstack3_device/base.rs

netstack3_device/
base.rs
