1 // -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*-

     2 //

     3 // Copyright (c) 2006 Georgia Tech Research Corporation

     4 //

     5 // This program is free software; you can redistribute it and/or modify

     6 // it under the terms of the GNU General Public License version 2 as

     7 // published by the Free Software Foundation;

     8 //

     9 // This program is distributed in the hope that it will be useful,

    10 // but WITHOUT ANY WARRANTY; without even the implied warranty of

    11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    12 // GNU General Public License for more details.

    13 //

    14 // You should have received a copy of the GNU General Public License

    15 // along with this program; if not, write to the Free Software

    16 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    17 //

    18 // Author: George F. Riley<riley@ece.gatech.edu>

    19 

    20 #ifndef INTERNET_STACK_H

    21 #define INTERNET_STACK_H

    22 

    23 #include "ns3/ptr.h"

    24 

    25 /**

    26  * \ingroup internetStack

    27  * \defgroup internetStackModel Internet Stack Model

    28  *

    29  * \section internetStackTracingModel Tracing in the Internet Stack

    30  *

    31  * The internet stack provides a number of trace sources in its various

    32  * protocol implementations.  These trace sources can be hooked using your own 

    33  * custom trace code, or you can use our helper functions in some cases to 

    34  * arrange for tracing to be enabled.

    35  *

    36  * \subsection internetStackArpTracingModel Tracing in ARP

    37  *

    38  * ARP provides two trace hooks, one in the cache, and one in the layer three

    39  * protocol.  The trace accessor in the cache is given the name "Drop."  When

    40  * a packet is transmitted over an interface that requires ARP, it is first

    41  * queued for transmission in the ARP cache until the required MAC address is

    42  * resolved.  There are a number of retries that may be done trying to get the 

    43  * address, and if the maximum retry count is exceeded the packet in question 

    44  * is dropped by ARP.  The single trace hook in the ARP cache is called,

    45  *

    46  * - If an outbound packet is placed in the ARP cache pending address resolution

    47  *   and no resolution can be made within the maximum retry count, the outbound 

    48  *   packet is dropped and this trace is fired;

    49  *

    50  * A second trace hook lives in the ARP L3 protocol (also named "Drop") and may 

    51  * be called for a  number of reasons.

    52  *

    53  * - If an ARP reply is received for an entry that is not waiting for a reply,

    54  *   the ARP reply packet is dropped and this trace is fired;

    55  * - If an ARP reply is received for a non-existant entry, the ARP reply packet 

    56  *   is dropped and this trace is fired;

    57  * - If an ARP cache entry is in the DEAD state (has timed out) and an ARP reply

    58  *   packet is received, the reply packet is dropped and this trace is fired.

    59  * - Each ARP cache entry has a queue of pending packets.  If the size of the

    60  *   queue is exceeded, the outbound packet is dropped and this trace is fired.

    61  *

    62  * \subsection internetStackIpv4TracingModel Tracing in IPv4

    63  *

    64  * The IPv4 layer three protocol provides three trace hooks.  These are the 

    65  * "Tx" (ns3::Ipv4L3Protocol::m_txTrace), "Rx" (ns3::Ipv4L3Protocol::m_rxTrace) 

    66  * and "Drop" (ns3::Ipv4L3Protocol::m_dropTrace) trace sources.

    67  *

    68  * The "Tx" trace is fired in a number of situations, all of which indicate that

    69  * a given packet is about to be sent down to a given ns3::Ipv4Interface.

    70  *

    71  * - In the case of a packet destined for the broadcast address, the 

    72  *   Ipv4InterfaceList is iterated and for every interface that is up and can

    73  *   fragment the packet or has a large enough MTU to transmit the packet,

    74  *   the trace is hit.  See ns3::Ipv4L3Protocol::Send.

    75  *

    76  * - In the case of a packet that needs routing, the "Tx" trace may be fired

    77  *   just before a packet is sent to the interface appropriate to the default 

    78  *   gateway.  See ns3::Ipv4L3Protocol::SendRealOut.

    79  *

    80  * - Also in the case of a packet that needs routing, the "Tx" trace may be 

    81  *   fired just before a packet is sent to the outgoing interface appropriate

    82  *   to the discovered route.  See ns3::Ipv4L3Protocol::SendRealOut.

    83  *

    84  * The "Rx" trace is fired when a packet is passed from the device up to the

    85  * ns3::Ipv4L3Protocol::Receive function.

    86  *

    87  * - In the receive function, the Ipv4InterfaceList is iterated, and if the

    88  *   Ipv4Interface corresponding to the receiving device is fount to be in the

    89  *   UP state, the trace is fired.

    90  *

    91  * The "Drop" trace is fired in any case where the packet is dropped (in both

    92  * the transmit and receive paths).

    93  *

    94  * - In the ns3::Ipv4Interface::Receive function, the packet is dropped and the

    95  *   drop trace is hit if the interface corresponding to the receiving device

    96  *   is in the DOWN state.

    97  *

    98  * - Also in the ns3::Ipv4Interface::Receive function, the packet is dropped and

    99  *   the drop trace is hit if the checksum is found to be bad.

   100  *

   101  * - In ns3::Ipv4L3Protocol::Send, an outgoing packet bound for the broadcast

   102  *   address is dropped and the "Drop" trace is fired if the "don't fragement"

   103  *   bit is set and fragmentation is available and required.

   104  *

   105  * - Also in ns3::Ipv4L3Protocol::Send, an outgoing packet destined for the 

   106  *   broadcast address is dropped and the "Drop" trace is hit if fragmentation

   107  *   is not available and is required (MTU < packet size).

   108  *

   109  * - In the case of a broadcast address, an outgoing packet is cloned for each

   110  *   outgoing interface.  If any of the interfaces is in the DOWN state, the 

   111  *   "Drop" trace event fires with a reference to the copied packet.

   112  *

   113  * - In the case of a packet requiring a route, an outgoing packet is dropped

   114  *   and the "Drop" trace event fires if no route to the remote host is found.

   115  *

   116  * - In ns3::Ipv4L3Protocol::SendRealOut, an outgoing packet being routed

   117  *   is dropped and the "Drop" trace is fired if the "don't fragement" bit is 

   118  *   set and fragmentation is available and required.

   119  *

   120  * - Also in ns3::Ipv4L3Protocol::SendRealOut, an outgoing packet being routed

   121  *   is dropped and the "Drop" trace is hit if fragmentation is not available 

   122  *   and is required (MTU < packet size).

   123  *

   124  * - An outgoing packet being routed is dropped and the "Drop" trace event fires

   125  *   if the required Ipv4Interface is in the DOWN state.

   126  *

   127  * - If a packet is being forwarded, and the TTL is exceeded (see

   128  *   ns3::Ipv4L3Protocol::DoForward), the packet is dropped and the "Drop" trace 

   129  *   event is fired.

   130  *

   131  * \subsection internetStackNs3TCPTracingModel Tracing in ns-3 TCP

   132  *

   133  * There is currently one trace source in the ns-3 TCP implementation named

   134  * "CongestionWindow" (see ns3::TcpSocketImpl::m_cWnd).  This is set in a number

   135  * of places (see file tcp-socket-impl.cc) whenever the value of the congestion

   136  * window is changed.

   137  *

   138  * \subsection internetStackNscTCPTracingModel Tracing in NSC TCP

   139  *

   140  * There is currently one trace source in the Network Simulation Cradle TCP 

   141  * implementation named "CongestionWindow" (see ns3::NscTcpSocketImpl::m_cWnd).

   142  * This is set in a number of places (see file nsc-tcp-socket-impl.cc) when 

   143  * the value of the cogestion window is initially set.  Note that this is not

   144  * instrumented from the underlying TCP implementaion.

   145  *

   146  * \subsection internetStackNs3UdpTracingModel Tracing in ns-3 UDP

   147  *

   148  * There is currently one trace source in the ns-3 UDP implementation named

   149  * "Drop" (see ns3::UdpSocketImpl::m_dropTrace).  This is set when a packet

   150  * is received in ns3::UdpSocketImpl::ForwardUp and the receive buffer cannot

   151  * accomodate the encapsulated data.

   152  */

   153 

   154 namespace ns3 {

   155 

   156 class Node;

   157 

   158 void AddInternetStack (Ptr<Node> node);

   159 void AddNscInternetStack (Ptr<Node> node, const std::string &soname);

   160 

   161 }//namespace ns3

   162 

   163 #endif /* INTERNET_STACK_H */