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
5library fuchsia.net.stack;
6
7using fuchsia.net;
8using fuchsia.hardware.ethernet;
9
10enum PresenceStatus {
11    /// The interface is added.
12    ADDED = 1;
13    /// The interface is removed.
14    REMOVED = 2;
15};
16
17enum PhysicalStatus {
18    /// The link is not attached to the medium.
19    DOWN = 1;
20    /// The link is attached to the medium.
21    UP = 2;
22};
23
24enum EnablementStatus {
25    /// The interface is administratively disabled.
26    DISABLED = 1;
27    /// The interface is administratively enabled.
28    ENABLED = 2;
29};
30
31union InterfaceStatus {
32    PresenceStatus presence;
33    PhysicalStatus physical;
34    EnablementStatus enablement;
35};
36
37struct InterfaceAddress {
38    /// The IP address of the interface.
39    fuchsia.net.IpAddress ipAddress;
40
41    /// The length of the network portion of the interface IP address.
42    uint8 prefixLen;
43};
44
45struct InterfaceInfo {
46    /// An opaque identifier for the interface, assigned by the stack.
47    /// This identifier will never be 0, and will not be reused even if the device is removed and
48    /// subsequently re-added. It is not stable across netstack instances.
49    uint64 id;
50
51    /// All info of an interface except the interface name.
52    InterfaceProperties properties;
53};
54
55struct InterfaceProperties {
56    /// The topological path to the device, representing a stable identifier for the interface
57    /// hardware.
58    string path;
59
60    /// The MAC address of the interface, if available.
61    fuchsia.hardware.ethernet.MacAddress? mac;
62
63    /// The maximum transmission unit for the interface in bytes.
64    uint32 mtu;
65
66    /// The features present on the interface, as a bitfield. Valid flags are
67    /// fuchsia.hardware.ethernet.INFO_FEATURE_*.
68    uint32 features;
69
70    /// The enablement status of the interface.
71    EnablementStatus enablementStatus;
72
73    /// The physcial link status of the interface.
74    PhysicalStatus physicalStatus;
75
76    /// The list of addresses currently assigned to the interface.
77    vector<InterfaceAddress> addresses;
78};
79
80/// A ForwardingDestination represents either the device that should transmit a packet or the address
81/// of the next hop in the route.
82union ForwardingDestination {
83    /// The opaque identifier of the device to which packets should be forwarded.
84    uint64 deviceId;
85
86    /// The IP address of the next hop, used to look up the next forwarding entry.
87    fuchsia.net.IpAddress nextHop;
88};
89
90/// An entry in the forwarding table for the network stack.
91struct ForwardingEntry {
92    /// The subnet is the key for the entry in the table.
93    fuchsia.net.Subnet subnet;
94
95    /// The destination that will receive the forwarded packet.
96    ForwardingDestination destination;
97};
98
99struct InterfaceStatusChange {
100    /// The opaque identifier of the device that had its status change.
101    uint64 id;
102
103    /// The new status.
104    InterfaceStatus status;
105};
106
107union InterfaceAddressDiff {
108    InterfaceAddress added;
109    InterfaceAddress removed;
110};
111
112struct InterfaceAddressChange {
113    /// The opaque identifier of the device that had its address change.
114    uint64 id;
115
116    /// The diff representing the address change.
117    InterfaceAddressDiff diff;
118};
119
120enum ErrorType {
121    INTERNAL = 1;
122    NOT_SUPPORTED = 2;
123    INVALID_ARGS = 3;
124    BAD_STATE = 4;
125    TIME_OUT = 5;
126    NOT_FOUND = 6;
127    ALREADY_EXISTS = 7;
128    IO = 8;
129};
130
131struct Error {
132    ErrorType type;
133};
134
135[Discoverable]
136interface Stack {
137    /// Add an Ethernet interface to the network stack. On success, returns the identifier assigned
138    /// by the stack for use in subsequent calls.
139    AddEthernetInterface(string topological_path, fuchsia.hardware.ethernet.Device device) -> (Error? err, uint64 id);
140
141    /// Remove an Ethernet interface from the network stack.
142    DelEthernetInterface(uint64 id) -> (Error? err);
143
144    /// List all the interfaces available in the network stack.
145    ListInterfaces() -> (vector<InterfaceInfo> ifs);
146
147    /// Retrieve info about a specific interface.
148    GetInterfaceInfo(uint64 id) -> (InterfaceInfo? info, Error? err);
149
150    /// Enable the interface. Packets may be processed by the stack after this call is processed.
151    EnableInterface(uint64 id) -> (Error? err);
152
153    /// Disable the interface. The stack will no longer process packets after this call.
154    DisableInterface(uint64 id) -> (Error? err);
155
156    /// Add an address to the interface. If the interface already has an address of a given type that
157    /// does not allow duplicates, this method will return an error.
158    AddInterfaceAddress(uint64 id, InterfaceAddress addr) -> (Error? err);
159
160    /// Remove the address from the interface. If the address is not assigned to the interface, an
161    /// error is returned.
162    DelInterfaceAddress(uint64 id, fuchsia.net.IpAddress addr) -> (Error? err);
163
164    /// List all the entries in the forwarding table for the network stack.
165    GetForwardingTable() -> (vector<ForwardingEntry> table);
166
167    /// Add a new entry to the forwarding table. If the table already contains an entry with the same
168    /// subnet, an error is returned. The entry may be deleted using DelForwardingEntry first.
169    AddForwardingEntry(ForwardingEntry entry) -> (Error? err);
170
171    /// Removes the forwarding entry with the given subnet. This will not affect any overlapping
172    /// subnets (superset or subset) so the subnet must exactly match an entry in the forwarding
173    /// table. If no entry for the subnet exists, an error is returned.
174    DelForwardingEntry(fuchsia.net.Subnet subnet) -> (Error? err);
175
176    /// Events
177
178    /// A status change event is triggered whenever an interface's status changes.
179    -> OnInterfaceStatusChange(InterfaceStatusChange info);
180
181    /// An address change event is triggered whenever an interface's addresses change.
182    -> OnInterfaceAddressChange(InterfaceAddressChange info);
183};
184