CHANGES.html
author Tom Henderson <tomh@tomh.org>
Thu, 02 Jul 2009 21:57:00 -0700
changeset 4646 c25ca2e38845
parent 4637 34e6d141c227
parent 4642 b40170d32073
permissions -rw-r--r--
some fixes to the manual for IPv4 refactoring
     1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
     2 <html>
     3 <head>
     4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
     5    <title>ns-3 Change Log</title>
     6 </head>
     7 <body>
     8 
     9 <h1>
    10 ns-3: API and model change history</h1>
    11 <!--
    12 This ChangeLog is updated in the reverse order 
    13 with the most recent changes coming first.  Date format:  DD-MM-YYYY
    14 -->
    15 <p>
    16 ns-3 is an evolving system and there will be API or behavioral changes
    17 from time to time.   Users who try to use scripts or models across
    18 versions of ns-3 may encounter problems at compile time, run time, or
    19 may see the simulation output change.  </p>
    20 <p>
    21 We have adopted the development policy that we are going to try to ease
    22 the impact of these changes on users by documenting these changes in a
    23 single place (this file), and not by providing a temporary or permanent
    24 backward-compatibility software layer.  </p>
    25 <p>
    26 The goal is that users who encounter a problem when trying to use older
    27 code with newer code should be able to consult this file to find
    28 guidance as to how to fix the problem.  For instance, if a method name
    29 or signature has changed, it should be stated what the new replacement
    30 name is. </p>
    31 <p>
    32 Note that users who upgrade the simulator across versions, or who work
    33 directly out of the development tree, may find that simulation output
    34 changes even when the compilation doesn't break, such as when a
    35 simulator default value is changed.  Therefore, it is good practice for
    36 _anyone_ using code across multiple ns-3 releases to consult this file,
    37 as well as the RELEASE_NOTES, to understand what has changed over time.
    38 </p>
    39 <p>
    40 This file is a best-effort approach to solving this issue; we will do
    41 our best but can guarantee that there will be things that fall through
    42 the cracks, unfortunately.  If you, as a user, can suggest improvements
    43 to this file based on your experience, please contribute a patch or drop
    44 us a note on ns-developers mailing list.  </p>
    45 
    46 <hr>
    47 <h1>Changes from ns-3.4 to ns-3.5</h1>
    48 
    49 <h2>Changes to build system:</h2>
    50 <ul>
    51 </ul>
    52 
    53 <h2>New API:</h2>
    54 
    55 <ul>
    56 <li><b>YansWifiPhyHelper supporting radiotap and prism PCAP output</b>
    57 <p>The newly supported pcap formats can be adopted by calling the following new method of YansWifiPhyHelper:</p>
    58 <pre>
    59  +  void SetPcapFormat (enum PcapFormat format);
    60 </pre>
    61 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.</p>
    62 </li>
    63 
    64 <li> <b>attributes for class Ipv4</b>
    65 <p> class Ipv4 now contains attributes in ipv4.cc; the first one
    66 is called "IpForward" that will enable/disable Ipv4 forwarding.  
    67 </li>
    68 
    69 <li> <b>packet tags</b>
    70 <p>class Packet now contains AddPacketTag, RemovePacketTag and PeekPacketTag 
    71 which can be used to attach a tag to a packet, as opposed to the old 
    72 AddTag method which attached a tag to a set of bytes. The main 
    73 semantic difference is in how these tags behave in the presence of 
    74 fragmentation and reassembly.
    75 </li>
    76 
    77 </ul>
    78 
    79 <h2>Changes to existing API:</h2>
    80 <ul>
    81 
    82 <li><b>Ipv4Interface::GetMtu () deleted</b>
    83   <p>The Ipv4Interface API is private to internet-stack module; this method
    84 was just a pass-through to GetDevice ()-&gt;GetMtu ().
    85   </p>
    86 </li>
    87 
    88 <li><b>GlobalRouteManager::PopulateRoutingTables () and RecomputeRoutingTables () are deprecated </b>
    89   <p>This API has been moved to the helper API and the above functions will
    90 be removed in ns-3.6.  The new API is:
    91 <pre>
    92 Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
    93 Ipv4GlobalRoutingHelper::RecomputeRoutingTables ();
    94 </pre>
    95 Additionally, these low-level functions in GlobalRouteManager are now public,
    96 allowing more API flexibility at the low level ns-3 API:
    97 <pre>
    98 GlobalRouteManager::DeleteGlobalRoutes ();
    99 GlobalRouteManager::BuildGlobalRoutingDatabase ();
   100 GlobalRouteManager::InitializeRoutes ();
   101 </pre>
   102   </p>
   103 </li>
   104 
   105 <li><b>CalcChecksum attribute changes</b>
   106   <p>Four IPv4 CalcChecksum attributes (which enable the computation of 
   107 checksums that are disabled by default) have been collapsed into one global 
   108 value in class Node.  These four calls: 
   109 <pre>
   110 Config::SetDefault ("ns3::Ipv4L3Protocol::CalcChecksum", BooleanValue (true)); 
   111 Config::SetDefault ("ns3::Icmpv4L4Protocol::CalcChecksum", BooleanValue (true));
   112 Config::SetDefault ("ns3::TcpL4Protocol::CalcChecksum", BooleanValue (true));
   113 Config::SetDefault ("ns3::UdpL4Protocol::CalcChecksum", BooleanValue (true));
   114 </pre>
   115 are replaced by one call to:
   116 <pre>
   117 GlobalValue::Bind ("ChecksumEnabled", BooleanValue (true));
   118 </pre>
   119   </p>
   120 </li>
   121 
   122 <li><b>CreateObject changes</b>
   123   <p>CreateObject is now able to construct objects with a non-default constructor.
   124    If you used to pass attribute lists to CreateObject, you must now use CreateObjectWithAttributes.
   125   </p>
   126 </li>
   127 
   128 <li> <b>packet byte tags renaming</b>
   129   <ul>
   130   <li>Packet::AddTag to Packet::AddByteTag</li>
   131   <li>Packet::FindFirstMatchingTag to Packet::FindFirstMatchingByteTag</li>
   132   <li>Packet::RemoveAllTags to Packet::RemoveAllByteTags</li>
   133   <li>Packet::PrintTags to Packet::PrintByteTags</li>
   134   <li>Packet::GetTagIterator to Packet::GetByteTagIterator</li>
   135   </ul>
   136 </li>
   137 
   138 <li><b>YansWifiPhyHelper::EnablePcap* methods not static any more</b>
   139 <p>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:
   140 <pre>
   141 -  static void EnablePcap (std::string filename, uint32_t nodeid, uint32_t deviceid);
   142 +         void EnablePcap (std::string filename, uint32_t nodeid, uint32_t deviceid);
   143 -  static void EnablePcap (std::string filename, Ptr<NetDevice> nd);
   144 +         void EnablePcap (std::string filename, Ptr<NetDevice> nd);
   145 -  static void EnablePcap (std::string filename, std::string ndName);
   146 +         void EnablePcap (std::string filename, std::string ndName);
   147 -  static void EnablePcap (std::string filename, NetDeviceContainer d);
   148 +         void EnablePcap (std::string filename, NetDeviceContainer d);
   149 -  static void EnablePcap (std::string filename, NodeContainer n);
   150 +         void EnablePcap (std::string filename, NodeContainer n);
   151 -  static void EnablePcapAll (std::string filename);
   152 +         void EnablePcapAll (std::string filename);
   153 </pre>
   154 </p>
   155 </li>
   156 
   157 <li><b>Wifi Promisc Sniff interface modified </b>
   158 <p> 
   159 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:
   160 <pre>
   161 -  void NotifyPromiscSniff (Ptr&lt;const Packet&gt; packet);
   162 +  void NotifyPromiscSniffRx (Ptr&lt;const Packet&gt; packet, uint16_t channelFreqMhz, uint32_t rate, bool isShortPreamble, double signalDbm, double noiseDbm);
   163 +  void NotifyPromiscSniffTx (Ptr&lt;const Packet&gt; packet, uint16_t channelFreqMhz, uint32_t rate, bool isShortPreamble);
   164 -  TracedCallback&lt;Ptr&lt;const Packet&gt; &gt; m_phyPromiscSnifferTrace;
   165 +  TracedCallback&lt;Ptr&lt;const Packet&gt;, uint16_t, uint32_t, bool, double, double&gt; m_phyPromiscSniffRxTrace;
   166 +  TracedCallback&lt;Ptr&lt;const Packet&gt;, uint16_t, uint32_t, bool&gt; m_phyPromiscSniffTxTrace;
   167 </pre>
   168 The above mentioned callbacks are expected to be used to call the following method to write Wifi PCAP traces in promiscuous mode:
   169 <pre>
   170 +  void WriteWifiMonitorPacket(Ptr&lt;const Packet&gt; packet, uint16_t channelFreqMhz, uint32_t rate, bool isShortPreamble, bool isTx, double signalDbm, double noiseDbm);
   171 </pre>
   172 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
   173 </p>
   174 </li>
   175 
   176 <li><b> Routing decoupled from class Ipv4</b>
   177 <p> All calls of the form "Ipv4::AddHostRouteTo ()" etc. (i.e. to 
   178 add static routes, both unicast and multicast) have been moved to a new 
   179 class Ipv4StaticRouting.  In addition, class Ipv4 now holds only
   180 one possible routing protocol; the previous way to add routing protocols
   181 (by ordered list of priority) has been moved to a new class Ipv4ListRouting.
   182 Class Ipv4 has a new minimal routing API (just to set and get the routing
   183 protocol):
   184 <pre>
   185 -  virtual void AddRoutingProtocol (Ptr&lt;Ipv4RoutingProtocol&gt; routingProtocol, int16_t priority) = 0;
   186 +  virtual void SetRoutingProtocol (Ptr&lt;Ipv4RoutingProtocol&gt; routingProtocol) = 0;
   187 +  virtual Ptr&lt;Ipv4RoutingProtocol&gt; GetRoutingProtocol (void) const = 0;
   188 </pre>
   189 </li>
   190 
   191 <li><b> class Ipv4RoutingProtocol is refactored</b>
   192 <p> The abstract base class Ipv4RoutingProtocol has been refactored to
   193 align with corresponding Linux Ipv4 routing architecture, and has been
   194 moved from ipv4.h to a new file ipv4-routing-protocol.h.  The new
   195 methods (RouteOutput () and RouteInput ()) are aligned with Linux 
   196 ip_route_output() and ip_route_input().  However,
   197 the general nature of these calls (synchronous routing lookup for
   198 locally originated packets, and an asynchronous, callback-based lookup
   199 for forwarded packets) is still the same.
   200 <pre>
   201 -  typedef Callback&lt;void, bool, const Ipv4Route&amp;, Ptr&lt;Packet&gt;, const Ipv4Header&amp;&gt; RouteReplyCallback;
   202 +  typedef Callback&lt;void, Ptr&lt;Ipv4Route&gt;, Ptr&lt;const Packet&gt;, const Ipv4Header &amp;&gt; UnicastForwardCallback;
   203 +  typedef Callback&lt;void, Ptr&lt;Ipv4MulticastRoute&gt;, Ptr&lt;const Packet&gt;, const Ipv4Header &amp;&gt; MulticastForwardCallback;
   204 +  typedef Callback&lt;void, Ptr&lt;const Packet&gt;, const Ipv4Header &amp;, uint32_t &gt; LocalDeliverCallback;
   205 +  typedef Callback&lt;void, Ptr&lt;const Packet&gt;, const Ipv4Header &amp;&gt; ErrorCallback;
   206 -  virtual bool RequestInterface (Ipv4Address destination, uint32_t&amp; interface) = 0;
   207 +  virtual Ptr&lt;Ipv4Route&gt; RouteOutput (Ptr&lt;Packet&gt; p, const Ipv4Header &amp;header, uint32_t oif, Socket::SocketErrno &amp;errno) = 0;
   208 -  virtual bool RequestRoute (uint32_t interface,
   209 -                            const Ipv4Header &amp;ipHeader,
   210 -                            Ptr&lt;Packet&gt; packet,
   211 -                            RouteReplyCallback routeReply) = 0;
   212 +  virtual bool RouteInput  (Ptr&lt;const Packet&gt; p, const Ipv4Header &amp;header, Ptr&lt;const NetDevice&gt; idev,
   213 +                             UnicastForwardCallback ucb, MulticastForwardCallback mcb,
   214 +                             LocalDeliverCallback lcb, ErrorCallback ecb) = 0;
   215 </pre>
   216 
   217 </li>
   218 <li><b> previous class Ipv4Route, Ipv4MulticastRoute renamed; new classes with
   219 those same names added</b>
   220 <p> The previous class Ipv4Route and Ipv4MulticastRoute are used by 
   221 Ipv4StaticRouting and Ipv4GlobalRouting to record internal routing table
   222 entries, so they were renamed to class Ipv4RoutingTableEntry and
   223 Ipv4MulticastRoutingTableEntry, respectively.  In their place, new
   224 class Ipv4Route and class Ipv4MulticastRoute have been added.  These
   225 are reference-counted objects that are analogous to Linux struct
   226 rtable and struct mfc_cache, respectively, to achieve better compatibility
   227 with Linux routing architecture in the future.  
   228 
   229 <li><b> class Ipv4 address-to-interface mapping functions changed</b>
   230 <p>  There was some general cleanup of functions that involve mappings
   231 from Ipv4Address to either NetDevice or Ipv4 interface index.  
   232 <pre>
   233 -  virtual uint32_t FindInterfaceForAddr (Ipv4Address addr) const = 0;
   234 -  virtual uint32_t FindInterfaceForAddr (Ipv4Address addr, Ipv4Mask mask) const = 0;
   235 +  virtual int32_t GetInterfaceForAddress (Ipv4Address address) const = 0;
   236 +  virtual int32_t GetInterfaceForPrefix (Ipv4Address address, Ipv4Mask mask) const = 0;
   237 -  virtual int32_t FindInterfaceForDevice(Ptr&lt;NetDevice&gt; nd) const = 0;
   238 +  virtual int32_t GetInterfaceForDevice (Ptr&lt;const NetDevice&gt; device) const = 0;
   239 -  virtual Ipv4Address GetSourceAddress (Ipv4Address destination) const = 0;
   240 -  virtual bool GetInterfaceForDestination (Ipv4Address dest,
   241 -  virtual uint32_t GetInterfaceByAddress (Ipv4Address addr, Ipv4Mask mask = Ipv4Mask("255.255.255.255"));
   242 </pre>
   243 
   244 <li><b> class Ipv4 multicast join API deleted</b>
   245 <p> The following methods are not really used in present form since IGMP
   246 is not being generated, so they have been removed (planned to be replaced
   247 by multicast socket-based calls in the future):
   248 
   249 <pre>
   250 - virtual void JoinMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0;
   251 - virtual void LeaveMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0;
   252 </pre>
   253 
   254 
   255 <li><b>Deconflict NetDevice::ifIndex and Ipv4::ifIndex (bug 85).</b>
   256 <p>All function parameters named "ifIndex" that refer 
   257 to an Ipv4 interface are instead named "interface".
   258 <pre>
   259 - static const uint32_t Ipv4RoutingProtocol::IF_INDEX_ANY = 0xffffffff;
   260 + static const uint32_t Ipv4RoutingProtocol::INTERFACE_ANY = 0xffffffff;
   261 
   262 - bool Ipv4RoutingProtocol::RequestIfIndex (Ipv4Address destination, uint32_t&amp; ifIndex);
   263 + bool Ipv4RoutingProtocol::RequestInterface (Ipv4Address destination, uint32_t&amp; interface);
   264 (N.B. this particular function is planned to be renamed to RouteOutput() in the
   265 proposed IPv4 routing refactoring)
   266 
   267 - uint32_t Ipv4::GetIfIndexByAddress (Ipv4Address addr, Ipv4Mask mask);
   268 + int_32t Ipv4::GetInterfaceForAddress (Ipv4Address address, Ipv4Mask mask) const;
   269 
   270 - bool Ipv4::GetIfIndexForDestination (Ipv4Address dest, uint32_t &amp;ifIndex) const;
   271 + bool Ipv4::GetInterfaceForDestination (Ipv4Address dest, uint32_t &amp;interface) const;
   272 (N.B. this function is not needed in the proposed Ipv4 routing refactoring)
   273 </pre>
   274 
   275 
   276 <li><b>Allow multiple IPv4 addresses to be assigned to an interface (bug 188)</b>
   277   <ul>
   278   <li> Add class Ipv4InterfaceAddress:  
   279   This is a new class to resemble Linux's struct in_ifaddr.  It holds IP addressing information, including mask,
   280   broadcast address, scope, whether primary or secondary, etc.
   281   <pre>
   282 +  virtual uint32_t AddAddress (uint32_t interface, Ipv4InterfaceAddress address) = 0;
   283 +  virtual Ipv4InterfaceAddress GetAddress (uint32_t interface, uint32_t addressIndex) const = 0;
   284 +  virtual uint32_t GetNAddresses (uint32_t interface) const = 0;
   285   </pre>
   286   <li>Regarding legacy API usage, typically where you once did the following,
   287   using the public Ipv4 class interface (e.g.):
   288   <pre>
   289   ipv4A-&gt;SetAddress (ifIndexA, Ipv4Address ("172.16.1.1"));
   290   ipv4A-&gt;SetNetworkMask (ifIndexA, Ipv4Mask ("255.255.255.255"));
   291   </pre>
   292   you now do:
   293   <pre>
   294   Ipv4InterfaceAddress ipv4IfAddrA = Ipv4InterfaceAddress (Ipv4Address ("172.16.1.1"), Ipv4Mask ("255.255.255.255"));
   295   ipv4A-&gt;AddAddress (ifIndexA, ipv4IfAddrA);
   296   </pre>
   297   <li> At the helper API level, one often gets an address from an interface
   298   container.  We preserve the legacy GetAddress (uint32_t i) but it
   299   is documented that this will return only the first (address index 0)
   300   address on the interface, if there are multiple such addresses. 
   301   We provide also an overloaded variant for the multi-address case: 
   302 
   303   <pre>
   304 Ipv4Address Ipv4InterfaceContainer::GetAddress (uint32_t i)
   305 + Ipv4Address Ipv4InterfaceContainer::GetAddress (uint32_t i, uint32_t j)
   306   </pre>
   307 
   308   </ul>
   309 
   310 <li><b>New WifiMacHelper objects</b>
   311 <p>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.</li>
   312   <pre>
   313 - void WifiHelper::SetMac (std::string type, std::string n0 = "", const AttributeValue &amp;v0 = EmptyAttributeValue (),...)
   314 
   315 - NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &amp;phyHelper, NodeContainer c) const
   316 + NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &amp;phyHelper, const WifiMacHelper &amp;macHelper, NodeContainer c) const
   317 
   318 - NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &amp;phy, Ptr&lt;Node&gt; node) const
   319 + NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &amp;phy, const WifiMacHelper &amp;mac, Ptr&lt;Node&gt; node) const
   320 
   321 - NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &amp;phy, std::string nodeName) const
   322 + NetDeviceContainer WifiHelper::Install (const WifiPhyHelper &amp;phy, const WifiMacHelper &amp;mac, std::string nodeName) const
   323   </pre>
   324   See src/helper/nqos-wifi-mac-helper.h and src/helper/qos-wifi-mac-helper.h for more details.
   325   </p>
   326 
   327 <li><b>Remove Mac48Address::IsMulticast</b>
   328   <p>This method was considered buggy and unsafe to call. Its replacement is Mac48Address::IsGroup.
   329   </li>
   330 
   331 </ul>
   332 
   333 <h2>Changed behavior:</h2>
   334 <ul>
   335 </ul>
   336 
   337 <hr>
   338 <h1>Changes from ns-3.3 to ns-3.4</h1>
   339 
   340 <h2>Changes to build system:</h2>
   341 <ul>
   342 <li>A major option regarding the downloading and building of ns-3 has been
   343 added for ns-3.4 -- the ns-3-allinone feature.  This allows a user to
   344 get the most common options for ns-3 downloaded and built with a minimum
   345 amount of trouble.  See the ns-3 tutorial for a detailed explanation of
   346 how to use this new feature.</li>
   347 
   348 <li>The build system now runs build items in parallel by default.  This includes
   349 the regression tests.</li>
   350 </ul>
   351 
   352 <h2>New API:</h2>
   353 <ul>
   354 <li>XML support has been added to the ConfigStore in src/contrib/config-store.cc</li>
   355 
   356 <li>The ns-2 calendar queue scheduler option has been ported to src/simulator</li>
   357 
   358 <li>A ThreeLogDistancePropagationLossModel has been added to src/devices/wifi</li>
   359 
   360 <li>ConstantAccelerationMobilityModel in src/mobility/constant-acceleration-mobility-model.h</li>
   361 
   362 <li>A new emulation mode is supported with the TapBridge net device (see
   363 src/devices/tap-bridge)</li>
   364 
   365 <li>A new facility for naming ns-3 Objects is included (see
   366 src/core/names.{cc,h})</li>
   367 
   368 <li>Wifi multicast support has been added in src/devices/wifi</li>
   369 </ul>
   370 
   371 <h2>Changes to existing API:</h2>
   372 
   373 <ul>
   374 <li>Some fairly significant changes have been made to the API of the
   375 random variable code.  Please see the ns-3 manual and src/core/random-variable.cc
   376 for details.</li>
   377 
   378 <li>The trace sources in the various NetDevice classes has been completely
   379 reworked to allow for a consistent set of trace sources across the
   380 devices.  The names of the trace sources have been changed to provide
   381 some context with respect to the level at which the trace occurred.
   382 A new set of trace sources has been added which emulates the behavior
   383 of packet sniffers.  These sources have been used to implement tcpdump-
   384 like functionality and are plumbed up into the helper classes.  The 
   385 user-visible changes are the trace source name changes and the ability
   386 to do promiscuous-mode pcap tracing via helpers.  For further information
   387 regarding these changes, please see the ns-3 manual</li>
   388 
   389 <li>StaticMobilityModel has been renamed ConstantPositionMobilityModel
   390 StaticSpeedMobilityModel has been renamed ConstantVelocityMobilityModel</li>
   391 
   392 <li>The Callback templates have been extended to support more parameters.
   393 See src/core/callback.h</li>
   394 
   395 <li>Many helper API have been changed to allow passing Object-based parameters
   396 as string names to ease working with the object name service.</li>
   397 
   398 <li>The Config APIs now accept path segments that are names defined by the
   399 object name service.</li>
   400 
   401 <li>Minor changes were made to make the system build under the Intel C++ compiler.</li>
   402 
   403 <li>Trace hooks for association and deassociation to/from an access point were
   404 added to src/devices/wifi/nqsta-wifi-mac.cc</li>
   405 </ul>
   406 
   407 <h2>Changed behavior:</h2>
   408 
   409 <ul>
   410 <li>The tracing system rework has introduced some significant changes in the
   411 behavior of some trace sources, specifically in the positioning of trace sources
   412 in the device code.  For example, there were cases where the packet transmit 
   413 trace source was hit before the packet was enqueued on the device transmit quueue.
   414 This now happens just before the packet is transmitted over the channel medium.
   415 The scope of the changes is too large to be included here.  If you have concerns
   416 regarding trace semantics, please consult the net device documentation for details.
   417 As is usual, the ultimate source for documentation is the net device source code.</li>
   418 </ul>
   419 
   420 <hr>
   421 <h1>Changes from ns-3.2 to ns-3.3</h1>
   422 
   423 <h2>New API:</h2>
   424 <ul>
   425 <li>
   426 ns-3 ABORT macros in src/core/abort.h
   427 Config::MatchContainer
   428 ConstCast and DynamicCast helper functions for Ptr casting
   429 StarTopology added to several topology helpers
   430 NetDevice::IsBridge () 
   431 </li>
   432 
   433 <li>17-11-2008; changeset 
   434 <a href="http://code.nsnam.org/ns-3-dev/rev/4c1c3f6bcd03">4c1c3f6bcd03</a></li>
   435 <ul>
   436 <li>
   437 The PppHeader previously defined in the point-to-point-net-device code has been 
   438 made public.
   439 </li>
   440 </ul>
   441 
   442 <li>17-11-2008; changeset 
   443 <a href="http://code.nsnam.org/ns-3-dev/rev/16c2970a0344">16c2970a0344</a></li>
   444 <ul>
   445 <li>
   446 An emulated net device has been added as enabling technology for ns-3 emulation
   447 scenarios.  See src/devices/emu and examples/emu-udp-echo.cc for details.
   448 </li>
   449 </ul>
   450 
   451 <li>17-11-2008; changeset 
   452 <a href="http://code.nsnam.org/ns-3-dev/rev/4222173d1e6d">4222173d1e6d</a></li>
   453 <ul>
   454 <li>
   455 Added method InternetStackHelper::EnableAsciiChange to allow allow a user to 
   456 hook ascii trace to the drop trace events in Ipv4L3Protocol and ArpL3Protocol.
   457 </li>
   458 </ul>
   459 
   460 </ul>
   461 <h2>Changes to existing API:</h2>
   462 <ul>
   463 
   464 <li> NetDevice::MakeMulticastAddress() was renamed to NetDevice::GetMulticast()
   465 and the original GetMulticast() removed </li>
   466 
   467 <li> Socket API changes:
   468 <ul>
   469 <li> return type of SetDataSentCallback () changed from bool to void </li>
   470 <li> Socket::Listen() no longer takes a queueLimit argument</li>
   471 </ul>
   472 
   473 <li> As part of the Wifi Phy rework, there have been several API changes
   474 at the low level and helper API level.  </li>
   475 <ul>
   476 <li>  At the helper API level, the WifiHelper was split to three classes: 
   477 a WifiHelper, a YansWifiChannel helper, and a YansWifiPhy helper.  Some
   478 functions like Ascii and Pcap tracing functions were moved from class
   479 WifiHelper to class YansWifiPhyHelper. 
   480 <li>  At the low-level API, there have been a number of changes to
   481 make the Phy more modular:</li>
   482 <ul>
   483 <li> composite-propagation-loss-model.h is removed</li>
   484 <li> DcfManager::NotifyCcaBusyStartNow() has changed name</li>
   485 <li> fragmentation related functions (e.g. DcaTxop::GetNFragments()) have
   486 changed API to account for some implementation changes</li>
   487 <li> Interference helper and error rate model added </li>
   488 <li> JakesPropagationLossModel::GetLoss() moved to PropagationLoss() class</li>
   489 <li> base class WifiChannel made abstract </li>
   490 <li> WifiNetDevice::SetChannel() removed </li>
   491 <li> a WifiPhyState helper class added </li>
   492 <li> addition of the YansWifiChannel and YansWifiPhy classes </li>
   493 </ul>
   494 </ul>
   495 
   496 <li>17-11-2008; changeset 
   497 <a href="http://code.nsnam.org/ns-3-dev/rev/dacfd1f07538">dacfd1f07538</a></li>
   498 <ul>
   499 <li>
   500 Change attribute "RxErrorModel" to "ReceiveErrorModel" in CsmaNetDevice for 
   501 consistency between devices.
   502 </li>
   503 </ul>
   504 
   505 </ul>
   506 <h2>changed behavior:</h2>
   507 <ul>
   508 
   509 <li>17-11-2008; changeset 
   510 <a href="http://code.nsnam.org/ns-3-dev/rev/ed0dfce40459">ed0dfce40459</a></li>
   511 <ul>
   512 <li>
   513 Relax reasonableness testing in Ipv4AddressHelper::SetBase to allow the 
   514 assignment of /32 addresses.
   515 </li>
   516 </ul>
   517 
   518 <li>17-11-2008; changeset 
   519 <a href="http://code.nsnam.org/ns-3-dev/rev/756887a9bbea">756887a9bbea</a></li>
   520 <ul>
   521 <li>
   522 Global routing supports bridge devices.
   523 </li>
   524 </ul>
   525 </ul>
   526 
   527 <hr>
   528 <h1>Changes from ns-3.1 to ns-3.2</h1>
   529 
   530 <h2>New API:</h2>
   531 <ul>
   532 
   533 <li>26-08-2008; changeset 
   534 <a href="http://code.nsnam.org/ns-3-dev/rev/5aa65b1ea001">5aa65b1ea001</a></li>
   535 <ul>
   536 <li>
   537 Add multithreaded and real-time simulator implementation.  Allows for emulated
   538 net devices running in threads other than the main simulation thread to schedule
   539 events.  Allows for pacing the simulation clock at 1x real-time.
   540 </li>
   541 </ul>
   542 
   543 
   544 <li>26-08-2008; changeset 
   545 <a href="http://code.nsnam.org/ns-3-dev/rev/c69779f5e51e">c69779f5e51e</a></li>
   546 <ul>
   547 <li>
   548 Add threading and synchronization primitives.  Enabling technology for 
   549 multithreaded simulator implementation.
   550 </li>
   551 </ul>
   552 
   553 </ul>
   554 <h2>New API in existing classes:</h2>
   555 <ul>
   556 
   557 <li>01-08-2008; changeset 
   558 <a href="http://code.nsnam.org/ns-3-dev/rev/a18520551cdf">a18520551cdf</a></li>
   559 <ul>
   560 <li>class ArpCache has two new attributes:  MaxRetries 
   561 and a Drop trace.  It also has some new public methods but these are 
   562 mostly for internal use.
   563 </ul>
   564 </li>
   565 
   566 </ul>
   567 <h2>Changes to existing API:</h2>
   568 <ul>
   569 
   570 <li>05-09-2008; changeset 
   571 <a href="http://code.nsnam.org/ns-3-dev/rev/aa1fb0f43571">aa1fb0f43571</a></li>
   572 <ul>
   573 <li>
   574 Change naming of MTU and packet size attributes in CSMA and Point-to-Point devices<br>
   575 After much discussion it was decided that the preferred way to think about 
   576 the different senses of transmission units and encapsulations was to call the 
   577 MAC MTU simply MTU and to use the overall packet size as the PHY-level attribute
   578 of interest.  See the Doxygen of CsmaNetDevice::SetFrameSize and 
   579 PointToPointNetDevice::SetFrameSize for a detailed description.
   580 </li>
   581 </ul>
   582 
   583 <li>25-08-2008; changeset 
   584 <a href="http://code.nsnam.org/ns-3-dev/rev/e5ab96db540e">e5ab96db540e</a></li>
   585 <ul>
   586 <li>
   587 bug 273: constify packet pointers.<br>
   588 The normal and the promiscuous receive callbacks of the NetDevice API
   589 have been changed from:
   590 <pre>
   591 Callback&lt;bool,Ptr&lt;NetDevice&gt;,Ptr&lt;Packet&gt;,uint16_t,const Address &amp;&gt;
   592 Callback&lt;bool,Ptr&lt;NetDevice&gt;, Ptr&lt;Packet&gt;, uint16_t,
   593          const Address &amp;, const Address &amp;, enum PacketType &gt;
   594 </pre>
   595 to:
   596 <pre>
   597 Callback&lt;bool,Ptr&lt;NetDevice&gt;,Ptr&lt;const Packet&gt;,uint16_t,const Address &amp;&gt;
   598 Callback&lt;bool,Ptr&lt;NetDevice&gt;, Ptr&lt;const Packet&gt;, uint16_t,
   599          const Address &amp;, const Address &amp;, enum PacketType &gt;
   600 </pre>
   601 to avoid the kind of bugs reported in 
   602 <a href="http://www.nsnam.org/bugzilla/show_bug.cgi?id=273">bug 273</a>.
   603 Users who implement a subclass of the NetDevice base class need to change the signature
   604 of their SetReceiveCallback and SetPromiscReceiveCallback methods.
   605 </li>
   606 </ul>
   607 
   608 
   609 <li>04-08-2008; changeset 
   610 <a href="http://code.nsnam.org/ns-3-dev/rev/cba7b2b80fe8">cba7b2b80fe8</a></li>
   611 <ul>
   612 <li>
   613 Cleanup of MTU confusion and initialization in CsmaNetDevice<br>
   614 The MTU of the CsmaNetDevice defaulted to 65535.  This did not correspond with
   615 the expected MTU found in Ethernet-like devices.  Also there was not clear 
   616 documentation regarding which MTU was being set.  There are two MTU here, one
   617 at the MAC level and one at the PHY level.  We split out the MTU setting to make
   618 this more clear and set the default PHY level MTU to 1500 to be more like
   619 Ethernet.  The encapsulation mode defaults to LLC/SNAP which then puts the
   620 MAC level MTU at 1492 by default.  We allow users to now set the encapsulation
   621 mode, MAC MTU and PHY MTU while keeping the three values consistent.  See the
   622 Doxygen of CsmaNetDevice::SetMaxPayloadLength for a detailed description of the
   623 issues and solution.
   624 </li>
   625 </ul>
   626 
   627 <li>21-07-2008; changeset 
   628 <a href="
   629 http://code.nsnam.org/ns-3-dev/rev/99698bc858e8">99698bc858e8</a></li>
   630 <ul>
   631 <li> class NetDevice has added a pure virtual method that
   632 must be implemented by all subclasses:
   633 <pre>
   634 virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb) = 0;
   635 </pre>
   636 All NetDevices must support this method, and must call this callback
   637 when processing packets in the receive direction (the appropriate place
   638 to call this is device-dependent).  An approach to stub this out
   639 temporarily, if you do not care about immediately enabling this
   640 functionality, would be to add this to your device:
   641 <pre>
   642 void
   643 ExampleNetDevice::SetPromiscReceiveCallback
   644 (NetDevice::PromiscReceiveCallback cb)
   645 { 
   646   NS_ASSERT_MSG (false, "No implementation yet for
   647 SetPromiscReceiveCallback");
   648 }
   649 </pre>
   650 To implement this properly, consult the CsmaNetDevice for examples of
   651 when the m_promiscRxCallback is called.
   652 </li>
   653 </ul>
   654 
   655 <li>03-07-2008; changeset 
   656 <a href="http://code.nsnam.org/ns-3-dev/rev/d5f8e5fae1c6">d5f8e5fae1c6</a></li>
   657 <ul>
   658 <li>
   659 Miscellaneous cleanup of Udp Helper API, to fix bug 234
   660 <pre>
   661 class UdpEchoServerHelper
   662 {
   663 public:
   664 - UdpEchoServerHelper ();
   665 - void SetPort (uint16_t port); 
   666 + UdpEchoServerHelper (uint16_t port);
   667 + 
   668 + void SetAttribute (std::string name, const AttributeValue &amp;value);
   669 ApplicationContainer Install (NodeContainer c);
   670 
   671 class UdpEchoClientHelper
   672 {
   673 public:
   674 - UdpEchoClientHelper ();
   675 + UdpEchoClientHelper (Ipv4Address ip, uint16_t port);
   676 - void SetRemote (Ipv4Address ip, uint16_t port);
   677 - void SetAppAttribute (std::string name, const AttributeValue &amp;value);
   678 + void SetAttribute (std::string name, const AttributeValue &amp;value);
   679 ApplicationContainer Install (NodeContainer c);
   680 </pre>
   681 </li>
   682 </ul>
   683 
   684 <li>03-07-2008; changeset 
   685 <a href="
   686 http://code.nsnam.org/ns-3-dev/rev/3cdd9d60f7c7">3cdd9d60f7c7</a></li>
   687 <ul>
   688 <li>
   689 Rename all instances method names using "Set..Parameter" to "Set..Attribute"
   690 (bug 232)
   691 </li>
   692 <li> How to fix your code:  Any use of helper API that was using a method
   693 "Set...Parameter()" should be changed to read "Set...Attribute()".  e.g.
   694 <pre>
   695 - csma.SetChannelParameter ("DataRate", DataRateValue (5000000));
   696 - csma.SetChannelParameter ("Delay", TimeValue (MilliSeconds (2)));
   697 + csma.SetChannelAttribute ("DataRate", DataRateValue (5000000));
   698 + csma.SetChannelAttribute ("Delay", TimeValue (MilliSeconds (2)));
   699 </pre>
   700 </li>
   701 </ul>
   702 </li>
   703 
   704 </ul>
   705 <h2>Changed behavior:</h2>
   706 <ul>
   707 
   708 <li>07-09-2008; changeset 
   709 <a href="http://code.nsnam.org/ns-3-dev/rev/5d836ab1523b">5d836ab1523b</a></li>
   710 <ul>
   711 
   712 <li>
   713 Implement a finite receive buffer for TCP<br>
   714 The native TCP model in TcpSocketImpl did not support a finite receive buffer.
   715 This changeset adds the following functionality in this regard:
   716 <ul>
   717 <li>
   718 Being able to set the receiver buffer size through the attributes system.
   719 </li>
   720 <li>
   721 This receiver buffer size is now correctly exported in the TCP header as the
   722 advertised window.  Prior to this changeset, the TCP header advertised window
   723 was set to the maximum size of 2^16 bytes.
   724 window
   725 </li>
   726 <li>
   727 The aforementioned window size is correctly used for flow control, i.e. the
   728 sending TCP will not send more data than available space in the receiver's
   729 buffer.
   730 </li>
   731 <li>
   732 In the case of a receiver window collapse, when a advertised zero-window
   733 packet is received, the sender enters the persist probing state in which
   734 it sends probe packets with one payload byte at exponentially backed-off
   735 intervals up to 60s.  The reciever will continue to send advertised 
   736 zero-window ACKs of the old data so long as the receiver buffer remains full.
   737 When the receiver window clears up due to an application read, the TCP
   738 will finally ACK the probe byte, and update its advertised window appropriately.
   739 </li>
   740 </ul>
   741 See 
   742 <a href="http://www.nsnam.org/bugzilla/show_bug.cgi?id=239"> bug 239 </a> for
   743 more.
   744 </li>
   745 </ul>
   746 
   747 <li>07-09-2008; changeset 
   748 <a href="http://code.nsnam.org/ns-3-dev/rev/7afa66c2b291">7afa66c2b291</a></li>
   749 <ul>
   750 <li>
   751 Add correct FIN exchange behavior during TCP closedown<br>
   752 The behavior of the native TcpSocketImpl TCP model was such that the final
   753 FIN exchange was not correct, i.e. calling Socket::Close didn't send a FIN
   754 packet, and even if it had, the ACK never came back, and even if it had, the
   755 ACK would have incorrect sequence number.  All these various problems have been
   756 addressed by this changeset.  See 
   757 <a href="http://www.nsnam.org/bugzilla/show_bug.cgi?id=242"> bug 242 </a> for
   758 more.
   759 </li>
   760 </ul>
   761 
   762 <li> 28-07-2008; changeset 
   763 <a href="http://code.nsnam.org/ns-3-dev/rev/6f68f1044df1">6f68f1044df1</a>
   764 <ul>
   765 <li>
   766 OLSR: HELLO messages hold time changed to 3*hello
   767 interval from hello interval.  This is an important bug fix as
   768 hold time == refresh time was never intentional, as it leads to
   769 instability in neighbor detection.
   770 </ul>
   771 </li>
   772 
   773 </ul>
   774 
   775 </body>
   776 </html>