00001 // -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- 00002 // 00003 // Copyright (c) 2006 Georgia Tech Research Corporation 00004 // 00005 // This program is free software; you can redistribute it and/or modify 00006 // it under the terms of the GNU General Public License version 2 as 00007 // published by the Free Software Foundation; 00008 // 00009 // This program is distributed in the hope that it will be useful, 00010 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 // GNU General Public License for more details. 00013 // 00014 // You should have received a copy of the GNU General Public License 00015 // along with this program; if not, write to the Free Software 00016 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 // 00018 // Author: George F. Riley<riley@ece.gatech.edu> 00019 00020 #ifndef INTERNET_STACK_H 00021 #define INTERNET_STACK_H 00022 00023 #include "ns3/ptr.h" 00024 00025 /** 00026 * \ingroup internetStack 00027 * \defgroup internetStackModel Internet Stack Model 00028 * 00029 * \section internetStackTracingModel Tracing in the Internet Stack 00030 * 00031 * The internet stack provides a number of trace sources in its various 00032 * protocol implementations. These trace sources can be hooked using your own 00033 * custom trace code, or you can use our helper functions in some cases to 00034 * arrange for tracing to be enabled. 00035 * 00036 * \subsection internetStackArpTracingModel Tracing in ARP 00037 * 00038 * ARP provides two trace hooks, one in the cache, and one in the layer three 00039 * protocol. The trace accessor in the cache is given the name "Drop." When 00040 * a packet is transmitted over an interface that requires ARP, it is first 00041 * queued for transmission in the ARP cache until the required MAC address is 00042 * resolved. There are a number of retries that may be done trying to get the 00043 * address, and if the maximum retry count is exceeded the packet in question 00044 * is dropped by ARP. The single trace hook in the ARP cache is called, 00045 * 00046 * - If an outbound packet is placed in the ARP cache pending address resolution 00047 * and no resolution can be made within the maximum retry count, the outbound 00048 * packet is dropped and this trace is fired; 00049 * 00050 * A second trace hook lives in the ARP L3 protocol (also named "Drop") and may 00051 * be called for a number of reasons. 00052 * 00053 * - If an ARP reply is received for an entry that is not waiting for a reply, 00054 * the ARP reply packet is dropped and this trace is fired; 00055 * - If an ARP reply is received for a non-existant entry, the ARP reply packet 00056 * is dropped and this trace is fired; 00057 * - If an ARP cache entry is in the DEAD state (has timed out) and an ARP reply 00058 * packet is received, the reply packet is dropped and this trace is fired. 00059 * - Each ARP cache entry has a queue of pending packets. If the size of the 00060 * queue is exceeded, the outbound packet is dropped and this trace is fired. 00061 * 00062 * \subsection internetStackIpv4TracingModel Tracing in IPv4 00063 * 00064 * The IPv4 layer three protocol provides three trace hooks. These are the 00065 * "Tx" (ns3::Ipv4L3Protocol::m_txTrace), "Rx" (ns3::Ipv4L3Protocol::m_rxTrace) 00066 * and "Drop" (ns3::Ipv4L3Protocol::m_dropTrace) trace sources. 00067 * 00068 * The "Tx" trace is fired in a number of situations, all of which indicate that 00069 * a given packet is about to be sent down to a given ns3::Ipv4Interface. 00070 * 00071 * - In the case of a packet destined for the broadcast address, the 00072 * Ipv4InterfaceList is iterated and for every interface that is up and can 00073 * fragment the packet or has a large enough MTU to transmit the packet, 00074 * the trace is hit. See ns3::Ipv4L3Protocol::Send. 00075 * 00076 * - In the case of a packet that needs routing, the "Tx" trace may be fired 00077 * just before a packet is sent to the interface appropriate to the default 00078 * gateway. See ns3::Ipv4L3Protocol::SendRealOut. 00079 * 00080 * - Also in the case of a packet that needs routing, the "Tx" trace may be 00081 * fired just before a packet is sent to the outgoing interface appropriate 00082 * to the discovered route. See ns3::Ipv4L3Protocol::SendRealOut. 00083 * 00084 * The "Rx" trace is fired when a packet is passed from the device up to the 00085 * ns3::Ipv4L3Protocol::Receive function. 00086 * 00087 * - In the receive function, the Ipv4InterfaceList is iterated, and if the 00088 * Ipv4Interface corresponding to the receiving device is fount to be in the 00089 * UP state, the trace is fired. 00090 * 00091 * The "Drop" trace is fired in any case where the packet is dropped (in both 00092 * the transmit and receive paths). 00093 * 00094 * - In the ns3::Ipv4Interface::Receive function, the packet is dropped and the 00095 * drop trace is hit if the interface corresponding to the receiving device 00096 * is in the DOWN state. 00097 * 00098 * - Also in the ns3::Ipv4Interface::Receive function, the packet is dropped and 00099 * the drop trace is hit if the checksum is found to be bad. 00100 * 00101 * - In ns3::Ipv4L3Protocol::Send, an outgoing packet bound for the broadcast 00102 * address is dropped and the "Drop" trace is fired if the "don't fragement" 00103 * bit is set and fragmentation is available and required. 00104 * 00105 * - Also in ns3::Ipv4L3Protocol::Send, an outgoing packet destined for the 00106 * broadcast address is dropped and the "Drop" trace is hit if fragmentation 00107 * is not available and is required (MTU < packet size). 00108 * 00109 * - In the case of a broadcast address, an outgoing packet is cloned for each 00110 * outgoing interface. If any of the interfaces is in the DOWN state, the 00111 * "Drop" trace event fires with a reference to the copied packet. 00112 * 00113 * - In the case of a packet requiring a route, an outgoing packet is dropped 00114 * and the "Drop" trace event fires if no route to the remote host is found. 00115 * 00116 * - In ns3::Ipv4L3Protocol::SendRealOut, an outgoing packet being routed 00117 * is dropped and the "Drop" trace is fired if the "don't fragement" bit is 00118 * set and fragmentation is available and required. 00119 * 00120 * - Also in ns3::Ipv4L3Protocol::SendRealOut, an outgoing packet being routed 00121 * is dropped and the "Drop" trace is hit if fragmentation is not available 00122 * and is required (MTU < packet size). 00123 * 00124 * - An outgoing packet being routed is dropped and the "Drop" trace event fires 00125 * if the required Ipv4Interface is in the DOWN state. 00126 * 00127 * - If a packet is being forwarded, and the TTL is exceeded (see 00128 * ns3::Ipv4L3Protocol::DoForward), the packet is dropped and the "Drop" trace 00129 * event is fired. 00130 * 00131 * \subsection internetStackNs3TCPTracingModel Tracing in ns-3 TCP 00132 * 00133 * There is currently one trace source in the ns-3 TCP implementation named 00134 * "CongestionWindow" (see ns3::TcpSocketImpl::m_cWnd). This is set in a number 00135 * of places (see file tcp-socket-impl.cc) whenever the value of the congestion 00136 * window is changed. 00137 * 00138 * \subsection internetStackNscTCPTracingModel Tracing in NSC TCP 00139 * 00140 * There is currently one trace source in the Network Simulation Cradle TCP 00141 * implementation named "CongestionWindow" (see ns3::NscTcpSocketImpl::m_cWnd). 00142 * This is set in a number of places (see file nsc-tcp-socket-impl.cc) when 00143 * the value of the cogestion window is initially set. Note that this is not 00144 * instrumented from the underlying TCP implementaion. 00145 * 00146 * \subsection internetStackNs3UdpTracingModel Tracing in ns-3 UDP 00147 * 00148 * There is currently one trace source in the ns-3 UDP implementation named 00149 * "Drop" (see ns3::UdpSocketImpl::m_dropTrace). This is set when a packet 00150 * is received in ns3::UdpSocketImpl::ForwardUp and the receive buffer cannot 00151 * accomodate the encapsulated data. 00152 */ 00153 00154 namespace ns3 { 00155 00156 class Node; 00157 00158 void AddInternetStack (Ptr<Node> node); 00159 void AddNscInternetStack (Ptr<Node> node, const std::string &soname); 00160 00161 }//namespace ns3 00162 00163 #endif /* INTERNET_STACK_H */