ns-3 is an evolving system and there will be API or behavioral changes from time to time. Users who try to use scripts or models across versions of ns-3 may encounter problems at compile time, run time, or may see the simulation output change.
We have adopted the development policy that we are going to try to ease the impact of these changes on users by documenting these changes in a single place (this file), and not by providing a temporary or permanent backward-compatibility software layer.
The goal is that users who encounter a problem when trying to use older code with newer code should be able to consult this file to find guidance as to how to fix the problem. For instance, if a method name or signature has changed, it should be stated what the new replacement name is.
Note that users who upgrade the simulator across versions, or who work directly out of the development tree, may find that simulation output changes even when the compilation doesn't break, such as when a simulator default value is changed. Therefore, it is good practice for _anyone_ using code across multiple ns-3 releases to consult this file, as well as the RELEASE_NOTES, to understand what has changed over time.
This file is a best-effort approach to solving this issue; we will do our best but can guarantee that there will be things that fall through the cracks, unfortunately. If you, as a user, can suggest improvements to this file based on your experience, please contribute a patch or drop us a note on ns-developers mailing list.
virtual void Socket::BindToNetDevice (Ptr<NetDevice> netdevice);
- virtual Ptr<Ipv4Route> RouteOutput (Ptr<Packet> p, const Ipv4Header &header, uint32_t oif, Socket::SocketErrno &sockerr) = 0; + virtual Ptr<Ipv4Route> RouteOutput (Ptr<Packet> p, const Ipv4Header &header, Ptr<NetDevice> oif, Socket::SocketErrno &sockerr) = 0;
- virtual Ptr<Ipv6Route> RouteOutput (Ptr<Packet> p, const Ipv6Header &header, uint32_t oif, Socket::SocketErrno &sockerr) = 0; + virtual Ptr<Ipv6Route> RouteOutput (Ptr<Packet> p, const Ipv6Header &header, Ptr<NetDevice> oif, Socket::SocketErrno &sockerr) = 0;
void
SimpleChannel::Send (Ptr<Packet> p, uint16_t protocol,
Mac48Address to, Mac48Address from,
Ptr<SimpleNetDevice> sender)
{
for (std::vector<Ptr<SimpleNetDevice> >::const_iterator i = m_devices.begin (); i != m_devices.end (); ++i)
{
Ptr<SimpleNetDevice> tmp = *i;
if (tmp == sender)
{
continue;
}
Simulator::ScheduleNow (&SimpleNetDevice::Receive, tmp, p->Copy (), protocol, to, from);
}
}
After:
void
SimpleChannel::Send (Ptr<Packet> p, uint16_t protocol,
Mac48Address to, Mac48Address from,
Ptr<SimpleNetDevice> sender)
{
for (std::vector<Ptr<SimpleNetDevice> >::const_iterator i = m_devices.begin (); i != m_devices.end (); ++i)
{
Ptr<SimpleNetDevice> tmp = *i;
if (tmp == sender)
{
continue;
}
Simulator::ScheduleWithContext (tmp->GetNode ()->GetId (), Seconds (0),
&SimpleNetDevice::Receive, tmp, p->Copy (), protocol, to, from);
}
}
Ptr<Scheduler> sched = CreateObject<ListScheduler> (); Simulator::SetScheduler (sched);After:
ObjectFactory sched;
sched.SetTypeId ("ns3::ListScheduler");
Simulator::SetScheduler (sched);
NodeContainer hubNode;
NodeContainer spokeNodes;
hubNode.Create (1);
Ptr<Node> hub = hubNode.Get (0);
spokeNodes.Create (nNodes - 1);
PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
NetDeviceContainer hubDevices, spokeDevices;
pointToPoint.InstallStar (hubNode.Get (0), spokeNodes, hubDevices, spokeDevices);
After:
PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
PointToPointStarHelper star (nSpokes, pointToPoint);
"./waf check" now runs the new unit tests of the core part of ns-3.6. In order to run the complete test package, use "./test.py" which is documented in a new manual -- find it in ./doc/testing. "./waf check" no longer generates the introspected Doxygen. Now use "./waf doxygen" to do this and generate the Doxygen documentation in one step.
When performing route lookup, first match for longest prefix, and then based on metrics (default metric = 0). If metrics are equal, most recent addition is picked. Extends API for support of metrics but preserves backward compatibility. One small change is that the default route is no longer stored as index 0 route in the host route table so GetDefaultRoute () must be used.
Add ability to inject and withdraw routes to Ipv4GlobalRouting. This allows a user to insert a route and have it redistributed like an OSPF external LSA to the rest of the topology.
New classes AthstatsWifiTraceSink and AthstatsHelper.
New trace sources exported by WifiRemoteStationManager: MacTxRtsFailed, MacTxDataFailed, MacTxFinalRtsFailed and MacTxFinalDataFailed.
Add an IPv6 protocol and ICMPv6 capability.
Add nix-vector routing protocol
Add TestCase, TestSuite classes
The method InterferenceHelper::CalculateTxDuration (uint32_t size, WifiMode payloadMode, WifiPreamble preamble) has been made static, so that the frame duration depends only on the characteristics of the frame (i.e., the function parameters) and not on the particular standard which is used by the receiving PHY. This makes it now possible to correctly calculate the duration of incoming frames in scenarios in which devices using different PHY configurations coexist in the same channel (e.g., a BSS using short preamble and another BSS using long preamble).
The following member methods have been added to InterferenceHelper:
static WifiMode GetPlcpHeaderMode (WifiMode, WifiPreamble); static uint32_t GetPlcpHeaderDurationMicroSeconds (WifiMode, WifiPreamble); static uint32_t GetPlcpPreambleDurationMicroSeconds (WifiMode, WifiPreamble); static uint32_t GetPayloadDurationMicroSeconds (size, WifiMode);
The following member methods have been removed from InterferenceHelper:
void Configure80211aParameters (void); void Configure80211bParameters (void); void Configure80211_10MhzParameters (void); void Configure80211_5MhzParameters (void);
WifiMode now has a WifiPhyStandard attribute which identifies the standard the WifiMode belongs to. To properly set this attribute when creating a new WifiMode, it is now required to explicitly pass a WifiPhyStandard parameter to all WifiModeFactory::CreateXXXX() methods. The WifiPhyStandard value of an existing WifiMode can be retrieved using the new method WifiMode::GetStandard().
In order to have multiple link change callback in NetDevice (i.e. to flush ARP and IPv6 neighbor discovery caches), the following member method has been renamed:
- virtual void SetLinkChangeCallback (Callback<void> callback); + virtual void AddLinkChangeCallback (Callback<void> callback);Now each NetDevice subclasses have a TracedCallback<> object (list of callbacks) instead of Callback<void> ones.
The newly supported pcap formats can be adopted by calling the following new method of YansWifiPhyHelper:
+ void SetPcapFormat (enum PcapFormat format);where format is one of PCAP_FORMAT_80211_RADIOTAP, PCAP_FORMAT_80211_PRISM or PCAP_FORMAT_80211. By default, PCAP_FORMAT_80211 is used, so the default PCAP format is the same as before.
class Ipv4 now contains attributes in ipv4.cc; the first one is called "IpForward" that will enable/disable Ipv4 forwarding.
class Packet now contains AddPacketTag, RemovePacketTag and PeekPacketTag which can be used to attach a tag to a packet, as opposed to the old AddTag method which attached a tag to a set of bytes. The main semantic difference is in how these tags behave in the presence of fragmentation and reassembly.
The Ipv4Interface API is private to internet-stack module; this method was just a pass-through to GetDevice ()->GetMtu ().
This API has been moved to the helper API and the above functions will be removed in ns-3.6. The new API is:
Ipv4GlobalRoutingHelper::PopulateRoutingTables (); Ipv4GlobalRoutingHelper::RecomputeRoutingTables ();Additionally, these low-level functions in GlobalRouteManager are now public, allowing more API flexibility at the low level ns-3 API:
GlobalRouteManager::DeleteGlobalRoutes (); GlobalRouteManager::BuildGlobalRoutingDatabase (); GlobalRouteManager::InitializeRoutes ();
Four IPv4 CalcChecksum attributes (which enable the computation of checksums that are disabled by default) have been collapsed into one global value in class Node. These four calls:
Config::SetDefault ("ns3::Ipv4L3Protocol::CalcChecksum", BooleanValue (true));
Config::SetDefault ("ns3::Icmpv4L4Protocol::CalcChecksum", BooleanValue (true));
Config::SetDefault ("ns3::TcpL4Protocol::CalcChecksum", BooleanValue (true));
Config::SetDefault ("ns3::UdpL4Protocol::CalcChecksum", BooleanValue (true));
are replaced by one call to:
GlobalValue::Bind ("ChecksumEnabled", BooleanValue (true));
CreateObject is now able to construct objects with a non-default constructor. If you used to pass attribute lists to CreateObject, you must now use CreateObjectWithAttributes.
To accommodate the possibility of configuring the PCAP format used for wifi promiscuous mode traces, several methods of YansWifiPhyHelper had to be made non-static:
- static void EnablePcap (std::string filename, uint32_t nodeid, uint32_t deviceid); + void EnablePcap (std::string filename, uint32_t nodeid, uint32_t deviceid); - static void EnablePcap (std::string filename, Ptr<NetDevice> nd); + void EnablePcap (std::string filename, Ptr<NetDevice> nd); - static void EnablePcap (std::string filename, std::string ndName); + void EnablePcap (std::string filename, std::string ndName); - static void EnablePcap (std::string filename, NetDeviceContainer d); + void EnablePcap (std::string filename, NetDeviceContainer d); - static void EnablePcap (std::string filename, NodeContainer n); + void EnablePcap (std::string filename, NodeContainer n); - static void EnablePcapAll (std::string filename); + void EnablePcapAll (std::string filename);
To accommodate support for the radiotap and prism headers in PCAP traces, the interface for promiscuos mode sniff in the wifi device was changed. The new implementation was heavily inspired by the way the madwifi driver handles monitor mode. A distinction between TX and RX events is introduced, to account for the fact that different information is to be put in the radiotap/prism header (e.g., RSSI and noise make sense only for RX packets). The following are the relevant modifications to the WifiPhy class:
- void NotifyPromiscSniff (Ptr<const Packet> packet); + void NotifyPromiscSniffRx (Ptr<const Packet> packet, uint16_t channelFreqMhz, uint32_t rate, bool isShortPreamble, double signalDbm, double noiseDbm); + void NotifyPromiscSniffTx (Ptr<const Packet> packet, uint16_t channelFreqMhz, uint32_t rate, bool isShortPreamble); - TracedCallback<Ptr<const Packet> > m_phyPromiscSnifferTrace; + TracedCallback<Ptr<const Packet>, uint16_t, uint32_t, bool, double, double> m_phyPromiscSniffRxTrace; + TracedCallback<Ptr<const Packet>, uint16_t, uint32_t, bool> m_phyPromiscSniffTxTrace;The above mentioned callbacks are expected to be used to call the following method to write Wifi PCAP traces in promiscuous mode:
+ void WriteWifiMonitorPacket(Ptr<const Packet> packet, uint16_t channelFreqMhz, uint32_t rate, bool isShortPreamble, bool isTx, double signalDbm, double noiseDbm);In the above method, the isTx parameter is to be used to differentiate between TX and RX packets. For an example of how to implement these callbacks, see the implementation of PcapSniffTxEvent and PcapSniffRxEvent in src/helper/yans-wifi-helper.cc
All calls of the form "Ipv4::AddHostRouteTo ()" etc. (i.e. to add static routes, both unicast and multicast) have been moved to a new class Ipv4StaticRouting. In addition, class Ipv4 now holds only one possible routing protocol; the previous way to add routing protocols (by ordered list of priority) has been moved to a new class Ipv4ListRouting. Class Ipv4 has a new minimal routing API (just to set and get the routing protocol):
- virtual void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol, int16_t priority) = 0; + virtual void SetRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol) = 0; + virtual Ptr<Ipv4RoutingProtocol> GetRoutingProtocol (void) const = 0;
The abstract base class Ipv4RoutingProtocol has been refactored to align with corresponding Linux Ipv4 routing architecture, and has been moved from ipv4.h to a new file ipv4-routing-protocol.h. The new methods (RouteOutput () and RouteInput ()) are aligned with Linux ip_route_output() and ip_route_input(). However, the general nature of these calls (synchronous routing lookup for locally originated packets, and an asynchronous, callback-based lookup for forwarded packets) is still the same.
- typedef Callback<void, bool, const Ipv4Route&, Ptr<Packet>, const Ipv4Header&> RouteReplyCallback; + typedef Callback<void, Ptr<Ipv4Route>, Ptr<const Packet>, const Ipv4Header &> UnicastForwardCallback; + typedef Callback<void, Ptr<Ipv4MulticastRoute>, Ptr<const Packet>, const Ipv4Header &> MulticastForwardCallback; + typedef Callback<void, Ptr<const Packet>, const Ipv4Header &, uint32_t > LocalDeliverCallback; + typedef Callback<void, Ptr<const Packet>, const Ipv4Header &> ErrorCallback; - virtual bool RequestInterface (Ipv4Address destination, uint32_t& interface) = 0; + virtual Ptr<Ipv4Route> RouteOutput (Ptr<Packet> p, const Ipv4Header &header, uint32_t oif, Socket::SocketErrno &errno) = 0; - virtual bool RequestRoute (uint32_t interface, - const Ipv4Header &ipHeader, - Ptr<Packet> packet, - RouteReplyCallback routeReply) = 0; + virtual bool RouteInput (Ptr<const Packet> p, const Ipv4Header &header, Ptr<const NetDevice> idev, + UnicastForwardCallback ucb, MulticastForwardCallback mcb, + LocalDeliverCallback lcb, ErrorCallback ecb) = 0;
The previous class Ipv4Route and Ipv4MulticastRoute are used by Ipv4StaticRouting and Ipv4GlobalRouting to record internal routing table entries, so they were renamed to class Ipv4RoutingTableEntry and Ipv4MulticastRoutingTableEntry, respectively. In their place, new class Ipv4Route and class Ipv4MulticastRoute have been added. These are reference-counted objects that are analogous to Linux struct rtable and struct mfc_cache, respectively, to achieve better compatibility with Linux routing architecture in the future.
There was some general cleanup of functions that involve mappings from Ipv4Address to either NetDevice or Ipv4 interface index.
- virtual uint32_t FindInterfaceForAddr (Ipv4Address addr) const = 0;
- virtual uint32_t FindInterfaceForAddr (Ipv4Address addr, Ipv4Mask mask) const = 0;
+ virtual int32_t GetInterfaceForAddress (Ipv4Address address) const = 0;
+ virtual int32_t GetInterfaceForPrefix (Ipv4Address address, Ipv4Mask mask) const = 0;
- virtual int32_t FindInterfaceForDevice(Ptr<NetDevice> nd) const = 0;
+ virtual int32_t GetInterfaceForDevice (Ptr<const NetDevice> device) const = 0;
- virtual Ipv4Address GetSourceAddress (Ipv4Address destination) const = 0;
- virtual bool GetInterfaceForDestination (Ipv4Address dest,
- virtual uint32_t GetInterfaceByAddress (Ipv4Address addr, Ipv4Mask mask = Ipv4Mask("255.255.255.255"));
The following methods are not really used in present form since IGMP is not being generated, so they have been removed (planned to be replaced by multicast socket-based calls in the future):
- virtual void JoinMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0; - virtual void LeaveMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0;
All function parameters named "ifIndex" that refer to an Ipv4 interface are instead named "interface".
- static const uint32_t Ipv4RoutingProtocol::IF_INDEX_ANY = 0xffffffff; + static const uint32_t Ipv4RoutingProtocol::INTERFACE_ANY = 0xffffffff; - bool Ipv4RoutingProtocol::RequestIfIndex (Ipv4Address destination, uint32_t& ifIndex); + bool Ipv4RoutingProtocol::RequestInterface (Ipv4Address destination, uint32_t& interface); (N.B. this particular function is planned to be renamed to RouteOutput() in the proposed IPv4 routing refactoring) - uint32_t Ipv4::GetIfIndexByAddress (Ipv4Address addr, Ipv4Mask mask); + int_32t Ipv4::GetInterfaceForAddress (Ipv4Address address, Ipv4Mask mask) const; - bool Ipv4::GetIfIndexForDestination (Ipv4Address dest, uint32_t &ifIndex) const; + bool Ipv4::GetInterfaceForDestination (Ipv4Address dest, uint32_t &interface) const; (N.B. this function is not needed in the proposed Ipv4 routing refactoring)
+ virtual uint32_t AddAddress (uint32_t interface, Ipv4InterfaceAddress address) = 0; + virtual Ipv4InterfaceAddress GetAddress (uint32_t interface, uint32_t addressIndex) const = 0; + virtual uint32_t GetNAddresses (uint32_t interface) const = 0;
ipv4A->SetAddress (ifIndexA, Ipv4Address ("172.16.1.1"));
ipv4A->SetNetworkMask (ifIndexA, Ipv4Mask ("255.255.255.255"));
you now do:
Ipv4InterfaceAddress ipv4IfAddrA = Ipv4InterfaceAddress (Ipv4Address ("172.16.1.1"), Ipv4Mask ("255.255.255.255"));
ipv4A->AddAddress (ifIndexA, ipv4IfAddrA);
Ipv4Address Ipv4InterfaceContainer::GetAddress (uint32_t i) + Ipv4Address Ipv4InterfaceContainer::GetAddress (uint32_t i, uint32_t j)
The type of wifi MAC is now set by two new specific helpers, NqosWifiMacHelper for non QoS MACs and QosWifiMacHelper for Qos MACs. They are passed as argument to WifiHelper::Install methods.
- void WifiHelper::SetMac (std::string type, std::string n0 = "", const AttributeValue &v0 = EmptyAttributeValue (),...) - NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &phyHelper, NodeContainer c) const + NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &phyHelper, const WifiMacHelper &macHelper, NodeContainer c) const - NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &phy, Ptr<Node> node) const + NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &phy, const WifiMacHelper &mac, Ptr<Node> node) const - NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &phy, std::string nodeName) const + NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &phy, const WifiMacHelper &mac, std::string nodeName) constSee src/helper/nqos-wifi-mac-helper.h and src/helper/qos-wifi-mac-helper.h for more details.
This method was considered buggy and unsafe to call. Its replacement is Mac48Address::IsGroup.
Callback<bool,Ptr<NetDevice>,Ptr<Packet>,uint16_t,const Address &>
Callback<bool,Ptr<NetDevice>, Ptr<Packet>, uint16_t,
const Address &, const Address &, enum PacketType >
to:
Callback<bool,Ptr<NetDevice>,Ptr<const Packet>,uint16_t,const Address &>
Callback<bool,Ptr<NetDevice>, Ptr<const Packet>, uint16_t,
const Address &, const Address &, enum PacketType >
to avoid the kind of bugs reported in
bug 273.
Users who implement a subclass of the NetDevice base class need to change the signature
of their SetReceiveCallback and SetPromiscReceiveCallback methods.
virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb) = 0;All NetDevices must support this method, and must call this callback when processing packets in the receive direction (the appropriate place to call this is device-dependent). An approach to stub this out temporarily, if you do not care about immediately enabling this functionality, would be to add this to your device:
void
ExampleNetDevice::SetPromiscReceiveCallback
(NetDevice::PromiscReceiveCallback cb)
{
NS_ASSERT_MSG (false, "No implementation yet for
SetPromiscReceiveCallback");
}
To implement this properly, consult the CsmaNetDevice for examples of
when the m_promiscRxCallback is called.
class UdpEchoServerHelper
{
public:
- UdpEchoServerHelper ();
- void SetPort (uint16_t port);
+ UdpEchoServerHelper (uint16_t port);
+
+ void SetAttribute (std::string name, const AttributeValue &value);
ApplicationContainer Install (NodeContainer c);
class UdpEchoClientHelper
{
public:
- UdpEchoClientHelper ();
+ UdpEchoClientHelper (Ipv4Address ip, uint16_t port);
- void SetRemote (Ipv4Address ip, uint16_t port);
- void SetAppAttribute (std::string name, const AttributeValue &value);
+ void SetAttribute (std::string name, const AttributeValue &value);
ApplicationContainer Install (NodeContainer c);
- csma.SetChannelParameter ("DataRate", DataRateValue (5000000));
- csma.SetChannelParameter ("Delay", TimeValue (MilliSeconds (2)));
+ csma.SetChannelAttribute ("DataRate", DataRateValue (5000000));
+ csma.SetChannelAttribute ("Delay", TimeValue (MilliSeconds (2)));