A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
net-device.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2005,2006 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 * Modified by Emmanuelle Laprise to remove dependence on LLC headers
8 */
9#ifndef NET_DEVICE_H
10#define NET_DEVICE_H
11
12#include "address.h"
13#include "packet.h"
14
15#include "ns3/callback.h"
16#include "ns3/ipv4-address.h"
17#include "ns3/ipv6-address.h"
18#include "ns3/object.h"
19#include "ns3/ptr.h"
20
21#include <stdint.h>
22
23namespace ns3
24{
25
26class Node;
27class Channel;
28
29/**
30 * @ingroup network
31 * @defgroup netdevice Network Device
32 */
33
34/**
35 * @ingroup netdevice
36 *
37 * @brief Network layer to device interface
38 *
39 * This interface defines the API which the IP and ARP
40 * layers need to access to manage an instance of a network device
41 * layer. It currently does not support MAC-level
42 * multicast but this should not be too hard to add by adding
43 * extra methods to register MAC multicast addresses to
44 * filter out unwanted packets before handing them to the
45 * higher layers.
46 *
47 * In Linux, this interface is analogous to the interface
48 * just above dev_queue_xmit() (i.e., IP packet is fully
49 * constructed with destination MAC address already selected).
50 *
51 * If you want to write a new MAC layer, you need to subclass
52 * this base class and implement your own version of the
53 * pure virtual methods in this class.
54 *
55 * This class was designed to hide as many MAC-level details as
56 * possible from the perspective of layer 3 to allow a single layer 3
57 * to work with any kind of MAC layer. Specifically, this class
58 * encapsulates the specific format of MAC addresses used by a
59 * device such that the layer 3 does not need any modification
60 * to handle new address formats. This means obviously that the
61 * NetDevice class must know about the address format of all potential
62 * layer 3 protocols through its GetMulticast methods: the current
63 * API has been optimized to make it easy to add new MAC protocols,
64 * not to add new layer 3 protocols.
65 *
66 * Devices aiming to support flow control and dynamic queue limits must perform
67 * the following operations:
68 * - in the NotifyNewAggregate method
69 * + cache the pointer to the netdevice queue interface aggregated to the
70 * device
71 * + set the select queue callback through the netdevice queue interface,
72 * if the device is multi-queue
73 * - anytime before initialization
74 * + set the number of device transmission queues (and optionally create them)
75 * through the netdevice queue interface, if the device is multi-queue
76 * - when the device queues have been created, invoke
77 * NetDeviceQueueInterface::ConnectQueueTraces, which
78 * + connects the Enqueue traced callback of the device queues to the
79 * PacketEnqueued static method of the NetDeviceQueue class
80 * + connects the Dequeue and DropAfterDequeue traced callback of the device
81 * queues to the PacketDequeued static method of the NetDeviceQueue
82 * class
83 * + connects the DropBeforeEnqueue traced callback of the device queues to
84 * the PacketDiscarded static method of the NetDeviceQueue class
85 */
86class NetDevice : public Object
87{
88 public:
89 /**
90 * @brief Get the type ID.
91 * @return the object TypeId
92 */
93 static TypeId GetTypeId();
94 ~NetDevice() override;
95
96 /**
97 * @param index ifIndex of the device
98 */
99 virtual void SetIfIndex(const uint32_t index) = 0;
100 /**
101 * @return index ifIndex of the device
102 */
103 virtual uint32_t GetIfIndex() const = 0;
104
105 /**
106 * @return the channel this NetDevice is connected to. The value
107 * returned can be zero if the NetDevice is not yet connected
108 * to any channel or if the underlying NetDevice has no
109 * concept of a channel. i.e., callers _must_ check for zero
110 * and be ready to handle it.
111 */
112 virtual Ptr<Channel> GetChannel() const = 0;
113
114 /**
115 * Set the address of this interface
116 * @param address address to set
117 */
118 virtual void SetAddress(Address address) = 0;
119
120 /**
121 * @return the current Address of this interface.
122 */
123 virtual Address GetAddress() const = 0;
124
125 /**
126 * @param mtu MTU value, in bytes, to set for the device
127 * @return whether the MTU value was within legal bounds
128 *
129 * Override for default MTU defined on a per-type basis.
130 */
131 virtual bool SetMtu(const uint16_t mtu) = 0;
132 /**
133 * @return the link-level MTU in bytes for this interface.
134 *
135 * This value is typically used by the IP layer to perform
136 * IP fragmentation when needed.
137 */
138 virtual uint16_t GetMtu() const = 0;
139 /**
140 * @return true if link is up; false otherwise
141 */
142 virtual bool IsLinkUp() const = 0;
143 /**
144 * TracedCallback signature for link changed event.
145 */
146 typedef void (*LinkChangeTracedCallback)();
147 /**
148 * @param callback the callback to invoke
149 *
150 * Add a callback invoked whenever the link
151 * status changes to UP. This callback is typically used
152 * by the IP/ARP layer to flush the ARP cache and by IPv6 stack
153 * to flush NDISC cache whenever the link goes up.
154 */
155 virtual void AddLinkChangeCallback(Callback<void> callback) = 0;
156 /**
157 * @return true if this interface supports a broadcast address,
158 * false otherwise.
159 */
160 virtual bool IsBroadcast() const = 0;
161 /**
162 * @return the broadcast address supported by
163 * this netdevice.
164 *
165 * Calling this method is invalid if IsBroadcast returns
166 * not true.
167 */
168 virtual Address GetBroadcast() const = 0;
169
170 /**
171 * @return value of m_isMulticast flag
172 */
173 virtual bool IsMulticast() const = 0;
174
175 /**
176 * @brief Make and return a MAC multicast address using the provided
177 * multicast group
178 *
179 * \RFC{1112} says that an Ipv4 host group address is mapped to an Ethernet
180 * multicast address by placing the low-order 23-bits of the IP address into
181 * the low-order 23 bits of the Ethernet multicast address
182 * 01-00-5E-00-00-00 (hex). Similar RFCs exist for Ipv6 and Eui64 mappings.
183 * This method performs the multicast address creation function appropriate
184 * to the underlying MAC address of the device. This MAC address is
185 * encapsulated in an abstract Address to avoid dependencies on the exact
186 * MAC address format.
187 *
188 * In the case of net devices that do not support
189 * multicast, clients are expected to test NetDevice::IsMulticast and avoid
190 * attempting to map multicast packets. Subclasses of NetDevice that do
191 * support multicasting are expected to override this method and provide an
192 * implementation appropriate to the particular device.
193 *
194 * @param multicastGroup The IP address for the multicast group destination
195 * of the packet.
196 * @return The MAC multicast Address used to send packets to the provided
197 * multicast group.
198 *
199 * @warning Calling this method is invalid if IsMulticast returns not true.
200 * @see IsMulticast()
201 */
202 virtual Address GetMulticast(Ipv4Address multicastGroup) const = 0;
203
204 /**
205 * @brief Get the MAC multicast address corresponding
206 * to the IPv6 address provided.
207 * @param addr IPv6 address
208 * @return the MAC multicast address
209 * @warning Calling this method is invalid if IsMulticast returns not true.
210 */
211 virtual Address GetMulticast(Ipv6Address addr) const = 0;
212
213 /**
214 * @brief Return true if the net device is acting as a bridge.
215 *
216 * @return value of m_isBridge flag
217 */
218 virtual bool IsBridge() const = 0;
219
220 /**
221 * @brief Return true if the net device is on a point-to-point link.
222 *
223 * @return value of m_isPointToPoint flag
224 */
225 virtual bool IsPointToPoint() const = 0;
226 /**
227 * @param packet packet sent from above down to Network Device
228 * @param dest mac address of the destination (already resolved)
229 * @param protocolNumber identifies the type of payload contained in
230 * this packet. Used to call the right L3Protocol when the packet
231 * is received.
232 *
233 * Called from higher layer to send packet into Network Device
234 * to the specified destination Address
235 *
236 * @return whether the Send operation succeeded
237 */
238 virtual bool Send(Ptr<Packet> packet, const Address& dest, uint16_t protocolNumber) = 0;
239 /**
240 * @param packet packet sent from above down to Network Device
241 * @param source source mac address (so called "MAC spoofing")
242 * @param dest mac address of the destination (already resolved)
243 * @param protocolNumber identifies the type of payload contained in
244 * this packet. Used to call the right L3Protocol when the packet
245 * is received.
246 *
247 * Called from higher layer to send packet into Network Device
248 * with the specified source and destination Addresses.
249 *
250 * @return whether the Send operation succeeded
251 */
252 virtual bool SendFrom(Ptr<Packet> packet,
253 const Address& source,
254 const Address& dest,
255 uint16_t protocolNumber) = 0;
256 /**
257 * @returns the node base class which contains this network
258 * interface.
259 *
260 * When a subclass needs to get access to the underlying node
261 * base class to print the nodeid for example, it can invoke
262 * this method.
263 */
264 virtual Ptr<Node> GetNode() const = 0;
265
266 /**
267 * @param node the node associated to this netdevice.
268 *
269 * This method is called from ns3::Node::AddDevice.
270 */
271 virtual void SetNode(Ptr<Node> node) = 0;
272
273 /**
274 * @returns true if ARP is needed, false otherwise.
275 *
276 * Called by higher-layers to check if this NetDevice requires
277 * ARP to be used.
278 */
279 virtual bool NeedsArp() const = 0;
280
281 /**
282 * Packet types are used as they are in Linux. GCC name resolution on
283 * typedef enum {} PacketType is broken for the foreseeable future, so
284 * if you need to use ns-3 PacketType in a driver that also uses the
285 * Linux packet types you're hosed unless we define a shadow type,
286 * which we do here.
287 */
289 {
290 PACKET_HOST = 1, //!< Packet addressed to us
292 PACKET_BROADCAST, //!< Packet addressed to all
294 PACKET_MULTICAST, //!< Packet addressed to multicast group
296 PACKET_OTHERHOST, //!< Packet addressed to someone else
298 };
299
300 /**
301 * @param device a pointer to the net device which is calling this callback
302 * @param packet the packet received
303 * @param protocol the 16 bit protocol number associated with this packet.
304 * This protocol number is expected to be the same protocol number
305 * given to the Send method by the user on the sender side.
306 * @param sender the address of the sender
307 * @returns true if the callback could handle the packet successfully, false
308 * otherwise.
309 */
312
313 /**
314 * @param cb callback to invoke whenever a packet has been received and must
315 * be forwarded to the higher layers.
316 *
317 * Set the callback to be used to notify higher layers when a packet has been
318 * received.
319 */
321
322 /**
323 * @param device a pointer to the net device which is calling this callback
324 * @param packet the packet received
325 * @param protocol the 16 bit protocol number associated with this packet.
326 * This protocol number is expected to be the same protocol number
327 * given to the Send method by the user on the sender side.
328 * @param sender the address of the sender
329 * @param receiver the address of the receiver
330 * @param packetType type of packet received (broadcast/multicast/unicast/otherhost)
331 * @returns true if the callback could handle the packet successfully, false
332 * otherwise.
333 */
334 typedef Callback<bool,
337 uint16_t,
338 const Address&,
339 const Address&,
342
343 /**
344 * @param cb callback to invoke whenever a packet has been received in promiscuous mode and must
345 * be forwarded to the higher layers.
346 *
347 * Enables netdevice promiscuous mode and sets the callback that
348 * will handle promiscuous mode packets. Note, promiscuous mode
349 * packets means _all_ packets, including those packets that can be
350 * sensed by the netdevice but which are intended to be received by
351 * other hosts.
352 */
354
355 /**
356 * @return true if this interface supports a bridging mode, false otherwise.
357 */
358 virtual bool SupportsSendFrom() const = 0;
359};
360
361} // namespace ns3
362
363#endif /* NET_DEVICE_H */
a polymophic address class
Definition address.h:90
Callback template class.
Definition callback.h:422
Ipv4 addresses are stored in host order in this class.
Describes an IPv6 address.
Network layer to device interface.
Definition net-device.h:87
virtual bool SupportsSendFrom() const =0
Callback< bool, Ptr< NetDevice >, Ptr< const Packet >, uint16_t, const Address &, const Address &, PacketType > PromiscReceiveCallback
Definition net-device.h:341
virtual uint32_t GetIfIndex() const =0
virtual bool SendFrom(Ptr< Packet > packet, const Address &source, const Address &dest, uint16_t protocolNumber)=0
static TypeId GetTypeId()
Get the type ID.
Definition net-device.cc:21
virtual bool SetMtu(const uint16_t mtu)=0
virtual void SetIfIndex(const uint32_t index)=0
virtual uint16_t GetMtu() const =0
virtual void SetPromiscReceiveCallback(PromiscReceiveCallback cb)=0
virtual void SetNode(Ptr< Node > node)=0
virtual Address GetMulticast(Ipv6Address addr) const =0
Get the MAC multicast address corresponding to the IPv6 address provided.
void(* LinkChangeTracedCallback)()
TracedCallback signature for link changed event.
Definition net-device.h:146
virtual bool IsMulticast() const =0
virtual Address GetBroadcast() const =0
virtual bool Send(Ptr< Packet > packet, const Address &dest, uint16_t protocolNumber)=0
virtual bool NeedsArp() const =0
virtual Address GetAddress() const =0
virtual bool IsLinkUp() const =0
~NetDevice() override
Definition net-device.cc:27
virtual bool IsBridge() const =0
Return true if the net device is acting as a bridge.
virtual Address GetMulticast(Ipv4Address multicastGroup) const =0
Make and return a MAC multicast address using the provided multicast group.
virtual bool IsBroadcast() const =0
virtual void AddLinkChangeCallback(Callback< void > callback)=0
virtual void SetAddress(Address address)=0
Set the address of this interface.
virtual Ptr< Channel > GetChannel() const =0
virtual void SetReceiveCallback(ReceiveCallback cb)=0
PacketType
Packet types are used as they are in Linux.
Definition net-device.h:289
@ PACKET_HOST
Packet addressed to us.
Definition net-device.h:290
@ PACKET_OTHERHOST
Packet addressed to someone else.
Definition net-device.h:296
@ PACKET_BROADCAST
Packet addressed to all.
Definition net-device.h:292
@ PACKET_MULTICAST
Packet addressed to multicast group.
Definition net-device.h:294
Callback< bool, Ptr< NetDevice >, Ptr< const Packet >, uint16_t, const Address & > ReceiveCallback
Definition net-device.h:311
virtual Ptr< Node > GetNode() const =0
virtual bool IsPointToPoint() const =0
Return true if the net device is on a point-to-point link.
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
a unique identifier for an interface.
Definition type-id.h:48
Every class exported by the ns3 library is enclosed in the ns3 namespace.