netstack3_base/
lib.rs

1// Copyright 2024 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
5//! Base type definitions for netstack3 core.
6//!
7//! This crate contains definitions common to the other netstack3 core crates
8//! and is the base dependency for most of them.
9
10#![no_std]
11#![warn(
12    missing_docs,
13    unreachable_patterns,
14    clippy::useless_conversion,
15    clippy::redundant_clone,
16    clippy::precedence
17)]
18
19extern crate fakealloc as alloc;
20
21mod context;
22mod convert;
23mod counters;
24mod data_structures;
25mod device;
26mod error;
27mod event;
28mod frame;
29mod inspect;
30mod ip;
31mod matchers;
32mod num;
33mod port_alloc;
34mod resource_references;
35mod rng;
36mod tcp;
37mod test_only;
38mod time;
39mod uninstantiable;
40mod work_queue;
41
42pub use context::{BuildableCoreContext, ContextPair, ContextProvider, CtxPair};
43pub use convert::{BidirectionalConverter, OwnedOrRefsBidirectionalConverter};
44pub use counters::{Counter, CounterContext, CounterRepr, ResourceCounterContext};
45pub use data_structures::token_bucket::TokenBucket;
46pub use device::address::{
47    AssignedAddrIpExt, IpAddressId, IpDeviceAddr, IpDeviceAddressIdContext, Ipv4DeviceAddr,
48    Ipv6DeviceAddr, WeakIpAddressId,
49};
50pub use device::link::{LinkAddress, LinkDevice, LinkUnicastAddress};
51pub use device::{
52    AnyDevice, Device, DeviceIdAnyCompatContext, DeviceIdContext, DeviceIdentifier, DeviceWithName,
53    EitherDeviceId, StrongDeviceIdentifier, WeakDeviceIdentifier,
54};
55pub use error::{
56    AddressResolutionFailed, ErrorAndSerializer, ExistsError, LocalAddressError, NotFoundError,
57    NotSupportedError, RemoteAddressError, SocketError, ZonedAddressError,
58};
59pub use event::EventContext;
60pub use frame::{
61    CoreTxMetadataContext, FrameDestination, ReceivableFrameMeta, RecvFrameContext,
62    RecvIpFrameMeta, SendFrameContext, SendFrameError, SendFrameErrorReason, SendableFrameMeta,
63    TxMetadataBindingsTypes,
64};
65pub use inspect::{Inspectable, InspectableValue, Inspector, InspectorDeviceExt, InspectorExt};
66pub use ip::{
67    BroadcastIpExt, IcmpErrorCode, IcmpIpExt, Icmpv4ErrorCode, Icmpv6ErrorCode, IpExt,
68    IpTypesIpExt, Mark, MarkDomain, MarkStorage, Marks, Mms, WrapBroadcastMarker,
69};
70pub use matchers::{DeviceNameMatcher, Matcher, SubnetMatcher};
71pub use num::PositiveIsize;
72pub use port_alloc::{simple_randomized_port_alloc, EphemeralPort, PortAllocImpl};
73pub use resource_references::{
74    DeferredResourceRemovalContext, ReferenceNotifiers, ReferenceNotifiersExt,
75    RemoveResourceResult, RemoveResourceResultWithContext,
76};
77pub use rng::RngContext;
78pub use tcp::base::{Control, FragmentedPayload, Mss};
79pub use tcp::segment::{
80    HandshakeOptions, Options, Payload, PayloadLen, SackBlock, SackBlocks, Segment, SegmentHeader,
81    SegmentOptions, VerifiedTcpSegment,
82};
83pub use tcp::seqnum::{SeqNum, UnscaledWindowSize, WindowScale, WindowSize};
84pub use test_only::{TestOnlyFrom, TestOnlyPartialEq};
85pub use time::local_timer_heap::LocalTimerHeap;
86pub use time::{
87    AtomicInstant, CoreTimerContext, HandleableTimer, Instant, InstantBindingsTypes,
88    InstantContext, IntoCoreTimerCtx, NestedIntoCoreTimerCtx, TimerBindingsTypes, TimerContext,
89    TimerHandler,
90};
91pub use uninstantiable::{Uninstantiable, UninstantiableWrapper};
92pub use work_queue::WorkQueueReport;
93
94/// Reference counted hash map data structure.
95pub mod ref_counted_hash_map {
96    pub use crate::data_structures::ref_counted_hash_map::{
97        InsertResult, RefCountedHashMap, RefCountedHashSet, RemoveResult,
98    };
99}
100
101/// Common types and utilities for sockets.
102pub mod socket {
103    mod address;
104    mod base;
105    mod cookie;
106    pub(crate) mod sndbuf;
107
108    pub use address::{
109        AddrIsMappedError, AddrVecIter, ConnAddr, ConnInfoAddr, ConnIpAddr, DualStackConnIpAddr,
110        DualStackListenerIpAddr, DualStackLocalIp, DualStackRemoteIp, ListenerAddr, ListenerIpAddr,
111        SocketIpAddr, StrictlyZonedAddr,
112    };
113    pub use base::{
114        AddrEntry, AddrVec, Bound, BoundSocketMap, DualStackIpExt, DualStackTuple, EitherStack,
115        FoundSockets, IncompatibleError, InsertError, Inserter, Listener, ListenerAddrInfo,
116        MaybeDualStack, NotDualStackCapableError, RemoveResult, SetDualStackEnabledError, Shutdown,
117        ShutdownType, SocketAddrType, SocketDeviceUpdate, SocketDeviceUpdateNotAllowedError,
118        SocketIpAddrExt, SocketIpExt, SocketMapAddrSpec, SocketMapAddrStateSpec,
119        SocketMapAddrStateUpdateSharingSpec, SocketMapConflictPolicy, SocketMapStateSpec,
120        SocketMapUpdateSharingPolicy, SocketStateEntry, SocketZonedAddrExt, UpdateSharingError,
121    };
122    pub use cookie::SocketCookie;
123    pub use sndbuf::{
124        SendBufferFullError, SendBufferSpace, SendBufferTracking, SocketWritableListener,
125    };
126}
127
128/// Defines generic data structures used to implement common application socket
129/// functionality for multiple protocols.
130pub mod socketmap {
131    pub use crate::data_structures::socketmap::{
132        Entry, IterShadows, OccupiedEntry, SocketMap, Tagged, VacantEntry,
133    };
134}
135
136/// Sync utilities common to netstack3.
137pub mod sync {
138    // TODO(https://fxbug.dev/42062225): Support single-threaded variants of
139    // types exported from this module.
140
141    // Exclusively re-exports from the sync crate.
142    pub use netstack3_sync::rc::{
143        DebugReferences, DynDebugReferences, MapNotifier as MapRcNotifier, Notifier as RcNotifier,
144        Primary as PrimaryRc, ResourceToken, ResourceTokenValue, Strong as StrongRc,
145        Weak as WeakRc,
146    };
147    pub use netstack3_sync::{LockGuard, Mutex, RwLock, RwLockReadGuard, RwLockWriteGuard};
148}
149
150/// Test utilities provided to all crates.
151#[cfg(any(test, feature = "testutils"))]
152pub mod testutil {
153    mod addr;
154    mod benchmarks;
155    mod fake_bindings;
156    mod fake_core;
157    mod fake_network;
158    mod misc;
159    mod monotonic_id;
160
161    pub use crate::device::address::testutil::FakeWeakAddressId;
162    pub use crate::device::link::testutil::{FakeLinkAddress, FakeLinkDevice, FakeLinkDeviceId};
163    pub use crate::device::testutil::{
164        FakeDeviceId, FakeReferencyDeviceId, FakeStrongDeviceId, FakeWeakDeviceId,
165        MultipleDevicesId, MultipleDevicesIdState,
166    };
167    pub use crate::event::testutil::FakeEventCtx;
168    pub use crate::frame::testutil::{FakeFrameCtx, FakeTxMetadata, WithFakeFrameContext};
169    pub use crate::rng::testutil::{new_rng, run_with_many_seeds, FakeCryptoRng};
170    pub use crate::socket::sndbuf::testutil::FakeSocketWritableListener;
171    pub use crate::time::testutil::{
172        FakeAtomicInstant, FakeInstant, FakeInstantCtx, FakeTimerCtx, FakeTimerCtxExt, FakeTimerId,
173        InstantAndData, WithFakeTimerContext,
174    };
175    pub use addr::{TestAddrs, TestDualStackIpExt, TestIpExt, TEST_ADDRS_V4, TEST_ADDRS_V6};
176    pub use benchmarks::{Bencher, RealBencher, TestBencher};
177    pub use fake_bindings::FakeBindingsCtx;
178    pub use fake_core::FakeCoreCtx;
179    pub use fake_network::{
180        FakeNetwork, FakeNetworkLinks, FakeNetworkSpec, PendingFrame, PendingFrameData, StepResult,
181    };
182    pub use misc::{assert_empty, set_logger_for_test};
183    pub use monotonic_id::MonotonicIdentifier;
184}
185
186/// Benchmarks defined in the base crate.
187#[cfg(benchmark)]
188pub mod benchmarks {
189    /// Adds benchmarks defined in the base crate to the provided benchmarker.
190    pub fn add_benches(b: criterion::Benchmark) -> criterion::Benchmark {
191        crate::data_structures::token_bucket::benchmarks::add_benches(b)
192    }
193}