netstack3_core/
lib.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
5//! A networking stack.
6
7#![no_std]
8// TODO(https://fxbug.dev/339502691): Return to the default limit once lock
9// ordering no longer causes overflows.
10#![recursion_limit = "256"]
11// In case we roll the toolchain and something we're using as a feature has been
12// stabilized.
13#![allow(stable_features)]
14#![warn(
15    missing_docs,
16    unreachable_patterns,
17    clippy::useless_conversion,
18    clippy::redundant_clone,
19    clippy::precedence
20)]
21extern crate alloc;
22
23mod api;
24mod context;
25mod counters;
26mod lock_ordering;
27mod marker;
28mod state;
29mod time;
30mod transport;
31
32#[cfg(any(test, feature = "testutils"))]
33pub mod testutil;
34
35/// The device layer.
36pub mod device {
37    #[path = "."]
38    pub(crate) mod integration {
39        mod base;
40        mod blackhole;
41        mod ethernet;
42        mod loopback;
43        mod pure_ip;
44        mod socket;
45
46        pub(crate) use base::{
47            device_state, device_state_and_core_ctx, get_mtu, ip_device_state,
48            ip_device_state_and_core_ctx,
49        };
50    }
51
52    // Re-exported types.
53    pub use netstack3_base::{
54        BoundInterfaceMatcher, InterfaceMatcher, InterfaceProperties, StrongDeviceIdentifier,
55    };
56    pub use netstack3_device::blackhole::{BlackholeDevice, BlackholeDeviceId};
57    pub use netstack3_device::ethernet::{
58        EthernetCreationProperties, EthernetDeviceEvent, EthernetDeviceId, EthernetLinkDevice,
59        EthernetWeakDeviceId, MaxEthernetFrameSize, RecvEthernetFrameMeta,
60    };
61    pub use netstack3_device::loopback::{
62        LoopbackCreationProperties, LoopbackDevice, LoopbackDeviceId, LoopbackWeakDeviceId,
63    };
64    pub use netstack3_device::pure_ip::{
65        PureIpDevice, PureIpDeviceCreationProperties, PureIpDeviceId,
66        PureIpDeviceReceiveFrameMetadata, PureIpHeaderParams, PureIpWeakDeviceId,
67    };
68    pub use netstack3_device::queue::{
69        BatchSize, ReceiveQueueBindingsContext, TransmitQueueBindingsContext,
70        TransmitQueueConfiguration, TxBufferAllocator,
71    };
72    pub use netstack3_device::{
73        ArpConfiguration, ArpConfigurationUpdate, BufferSlice, DeviceBufferBindingsTypes,
74        DeviceClassMatcher, DeviceConfiguration, DeviceConfigurationUpdate,
75        DeviceConfigurationUpdateError, DeviceCounters, DeviceId, DeviceIdAndNameMatcher,
76        DeviceLayerEventDispatcher, DeviceLayerStateTypes, DeviceProvider, DeviceSendFrameError,
77        GroBufferDestination, GroBufferStorage, GroFrameType, GroInputItem, GroIter,
78        GroOutputBuffers, GroOutputItem, MaybeContiguousBuffer, NdpConfiguration,
79        NdpConfigurationUpdate, WeakDeviceId,
80    };
81}
82
83/// Device socket API.
84pub mod device_socket {
85    pub use netstack3_base::{FrameDestination, SendFrameErrorReason};
86    pub use netstack3_device::socket::{
87        DeviceSocketBindingsContext, DeviceSocketMetadata, DeviceSocketTypes, EthernetFrame,
88        EthernetHeaderParams, Frame, IpFrame, Protocol, ReceiveFrameError, ReceivedFrame,
89        SentFrame, SocketId, SocketInfo, TargetDevice, WeakDeviceSocketId,
90    };
91}
92
93/// Generic netstack errors.
94pub mod error {
95    pub use netstack3_base::{
96        AddressResolutionFailed, ExistsError, LocalAddressError, NotFoundError, NotSupportedError,
97        RemoteAddressError, SocketError, ZonedAddressError,
98    };
99}
100
101/// Framework for packet filtering.
102pub mod filter {
103    mod integration;
104
105    pub use netstack3_filter::{
106        Action, BindingsPacketMatcher, EitherIpProto, FilterApi, FilterBindingsContext,
107        FilterBindingsTypes, FilterIpExt, FilterIpPacket, FilterPacketMetadata, Hook, Interfaces,
108        IpPacket, IpRoutines, MarkAction, NatRoutines, PacketMatcher, ProofOfEgressCheck,
109        RejectType, Routine, Routines, Rule, SocketEgressFilterResult, SocketInfo,
110        SocketIngressFilterResult, SocketOpsFilter, SocketOpsFilterBindingContext,
111        TransparentProxy, TransportProtocolMatcher, Tuple, UninstalledRoutine, ValidationError,
112    };
113}
114
115/// Facilities for inspecting stack state for debugging.
116pub mod inspect {
117    pub use netstack3_base::{
118        Inspectable, InspectableValue, Inspector, InspectorDeviceExt, InspectorExt,
119    };
120}
121
122/// Methods for dealing with ICMP sockets.
123pub mod icmp {
124    pub use netstack3_icmp_echo::{
125        IcmpEchoBindingsContext, IcmpEchoBindingsTypes, IcmpSocketId, ReceiveIcmpEchoError,
126    };
127}
128
129/// The Internet Protocol, versions 4 and 6.
130pub mod ip {
131    #[path = "."]
132    pub(crate) mod integration {
133        mod base;
134        mod device;
135        mod multicast_forwarding;
136        mod raw;
137
138        pub(crate) use device::CoreCtxWithIpDeviceConfiguration;
139    }
140
141    // Re-exported types.
142    pub use netstack3_base::{
143        AddressMatcher, AddressMatcherEither, AddressMatcherType, BoundAddressMatcherEither,
144        BoundPortMatcher, Mark, MarkDomain, MarkInDomainMatcher, MarkMatcher, MarkMatchers, Marks,
145        PortMatcher, SubnetMatcher, WrapBroadcastMarker,
146    };
147    pub use netstack3_ip::device::{
148        AddIpAddrSubnetError, AddrSubnetAndManualConfigEither, AddressRemovedReason,
149        CommonAddressConfig, CommonAddressProperties, IidGenerationConfiguration, IidSecret,
150        IpAddressState, IpDeviceConfiguration, IpDeviceConfigurationAndFlags,
151        IpDeviceConfigurationUpdate, IpDeviceEvent, IpDeviceIpExt, Ipv4AddrConfig,
152        Ipv4DeviceConfiguration, Ipv4DeviceConfigurationUpdate, Ipv6AddrManualConfig,
153        Ipv6DeviceConfiguration, Ipv6DeviceConfigurationUpdate, Lifetime,
154        PendingIpDeviceConfigurationUpdate, PreferredLifetime, RouteDiscoveryConfiguration,
155        RouteDiscoveryConfigurationUpdate, SetIpAddressPropertiesError, SlaacConfiguration,
156        SlaacConfigurationUpdate, StableSlaacAddressConfiguration,
157        TemporarySlaacAddressConfiguration, UpdateIpConfigurationError,
158    };
159    pub use netstack3_ip::gmp::{IgmpConfigMode, MldConfigMode};
160    pub use netstack3_ip::multicast_forwarding::{
161        ForwardMulticastRouteError, MulticastForwardingDisabledError, MulticastForwardingEvent,
162        MulticastRoute, MulticastRouteKey, MulticastRouteStats, MulticastRouteTarget,
163    };
164    pub use netstack3_ip::raw::{
165        RawIpSocketIcmpFilter, RawIpSocketIcmpFilterError, RawIpSocketId, RawIpSocketProtocol,
166        RawIpSocketSendToError, RawIpSocketsBindingsContext, RawIpSocketsBindingsTypes,
167        ReceivePacketError, WeakRawIpSocketId,
168    };
169    pub use netstack3_ip::socket::{
170        IpSockCreateAndSendError, IpSockCreationError, IpSockSendError,
171    };
172    pub use netstack3_ip::{
173        IpLayerEvent, IpRoutingBindingsTypes, MarksBindingsContext, ResolveRouteError,
174        RouterAdvertisementEvent, SocketMetadata,
175    };
176}
177
178/// Types and utilities for dealing with neighbors.
179pub mod neighbor {
180    // Re-exported types.
181    pub use netstack3_ip::nud::{
182        Event, EventDynamicState, EventKind, EventState, LinkResolutionContext,
183        LinkResolutionNotifier, LinkResolutionResult, MAX_ENTRIES, NeighborRemovalError,
184        NudUserConfig, NudUserConfigUpdate, StaticNeighborInsertionError,
185        TriggerNeighborProbeError,
186    };
187}
188
189/// Types and utilities for dealing with routes.
190pub mod routes {
191    // Re-exported types.
192    pub use netstack3_base::{Marks, WrapBroadcastMarker};
193    pub use netstack3_ip::{
194        AddRouteError, AddableEntry, AddableEntryEither, AddableMetric, Entry, EntryEither,
195        Generation, Metric, NextHop, RawMetric, ResolvedRoute, RoutableIpAddr, RoutePreference,
196        RouteResolveOptions, RoutingTableCookie, RoutingTableId, Rule, RuleAction, RuleMatcher,
197        TrafficOriginMatcher,
198    };
199}
200
201/// Common types for dealing with sockets.
202pub mod socket {
203    pub use netstack3_datagram::{
204        ConnInfo, ConnectError, ExpectedConnError, ExpectedUnboundError, ListenerInfo,
205        MulticastInterfaceSelector, MulticastMembershipInterfaceSelector,
206        PendingDatagramSocketError, SendError, SendToError, SetMulticastMembershipError,
207        SocketInfo,
208    };
209
210    pub use netstack3_base::socket::{
211        AddrIsMappedError, NotDualStackCapableError, ReusePortOption, SendBufferFullError,
212        SendBufferSpace, SendBufferTracking, SetDualStackEnabledError, SharingDomain, ShutdownType,
213        SocketCookie, SocketWritableListener, StrictlyZonedAddr,
214    };
215
216    pub use netstack3_base::{
217        IpSocketMatcher, SocketCookieMatcher, SocketTransportProtocolMatcher, TcpSocketMatcher,
218        TcpStateMatcher, UdpSocketMatcher, UdpStateMatcher,
219    };
220}
221
222/// Useful synchronization primitives.
223pub mod sync {
224    // We take all of our dependencies directly from base for symmetry with the
225    // other crates. However, we want to explicitly have all the dependencies in
226    // GN so we can assert the dependencies on the crate variants. This defeats
227    // rustc's unused dependency check.
228    use netstack3_sync as _;
229
230    pub use netstack3_base::sync::{
231        DebugReferences, DynDebugReferences, LockGuard, MapRcNotifier, Mutex, PrimaryRc,
232        RcNotifier, ResourceToken, ResourceTokenValue, RwLock, RwLockReadGuard, RwLockWriteGuard,
233        StrongRc, WeakRc,
234    };
235    pub use netstack3_base::{RemoveResourceResult, RemoveResourceResultWithContext};
236}
237
238/// Methods for dealing with TCP sockets.
239pub mod tcp {
240    pub use netstack3_base::{FragmentedPayload, Payload, PayloadLen, TcpSocketState};
241    pub use netstack3_tcp::{
242        AcceptError, BindError, BoundInfo, Buffer, BufferLimits, BufferSizes,
243        CongestionControlState, ConnectError, ConnectionError, ConnectionInfo,
244        DEFAULT_FIN_WAIT2_TIMEOUT, IntoBuffers, ListenError, ListenerNotifier, NoConnection,
245        OriginalDestinationError, ReceiveBuffer, SendBuffer, SetDeviceError, SetReuseAddrError,
246        SocketAddr, SocketInfo, SocketOptions, TcpBindingsTypes, TcpSettings,
247        TcpSocketDestructionContext, TcpSocketDiagnosticTuple, TcpSocketDiagnostics, TcpSocketId,
248        TcpSocketInfo, UnboundInfo,
249    };
250}
251
252/// Tracing utilities.
253pub mod trace {
254    // Re-export all of the trace crate to match how the rest of core works.
255    pub use netstack3_trace::*;
256}
257
258/// Miscellaneous and common types.
259pub mod types {
260    pub use netstack3_base::{BufferSizeSettings, Counter, PositiveIsize, WorkQueueReport};
261}
262
263/// Methods for dealing with UDP sockets.
264pub mod udp {
265    pub use netstack3_udp::{
266        ReceiveUdpError, SendError, SendToError, UdpBindingsTypes, UdpPacketMeta,
267        UdpReceiveBindingsContext, UdpRemotePort, UdpSocketDiagnosticTuple, UdpSocketDiagnostics,
268        UdpSocketId,
269    };
270}
271
272pub use api::CoreApi;
273pub use context::{CoreCtx, UnlockedCoreCtx};
274pub use inspect::Inspector;
275pub use marker::{BindingsContext, BindingsTypes, CoreContext, IpBindingsContext, IpExt};
276pub use netstack3_base::{
277    ChecksumOffloadResult, ChecksumOffloadSpec, ChecksumRxOffloading, CtxPair,
278    DeferredResourceRemovalContext, EventContext, GsoInfo, InstantBindingsTypes, InstantContext,
279    Ipv4IdMode, MapDerefExt, MatcherBindingsTypes, NetworkParsingContext,
280    NetworkSerializationContext, ProtocolSpecificOffloadSpec, ReferenceNotifiers, RngContext,
281    SettingsContext, SocketDiagnosticsSeed, TimerBindingsTypes, TimerContext, TxMetadata,
282    TxMetadataBindingsTypes,
283};
284pub use netstack3_datagram::PendingDatagramSocketError;
285pub use state::{StackState, StackStateBuilder};
286pub use time::{AtomicInstant, Instant, TimerId};
287pub use transport::CoreTxMetadata;
288
289// Re-export useful macros.
290pub use netstack3_device::for_any_device_id;
291pub use netstack3_macros::context_ip_bounds;
292
293// Rust compiler spinning workaround (https://fxbug.dev/395694598):
294//
295// If you find yourself with a spinning rustc because you're changing traits
296// that need to be implemented by bindings, uncomment the lines below and give
297// it a go. See attached bug for details.
298//
299// unsafe impl<BT: BindingsTypes> Send for TimerId<BT> {}
300// unsafe impl<BT: BindingsTypes> Sync for TimerId<BT> {}
301// unsafe impl<BT: BindingsTypes> Send for TxMetadata<BT> {}
302// unsafe impl<BT: BindingsTypes> Sync for TxMetadata<BT> {}
netstack3_core/lib.rs

netstack3_core/
lib.rs
