1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 2 /* 3 * Copyright (c) 2007, 2008 University of Washington 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 19 #ifndef POINT_TO_POINT_NET_DEVICE_H 20 #define POINT_TO_POINT_NET_DEVICE_H 21 22 #include <cstring> 23 #include "ns3/address.h" 24 #include "ns3/node.h" 25 #include "ns3/net-device.h" 26 #include "ns3/callback.h" 27 #include "ns3/packet.h" 28 #include "ns3/traced-callback.h" 29 #include "ns3/nstime.h" 30 #include "ns3/data-rate.h" 31 #include "ns3/ptr.h" 32 #include "ns3/mac48-address.h" 33 34 namespace ns3 { 35 36 template <typename Item> class Queue; 37 class PointToPointChannel; 38 class ErrorModel; 39 40 /** 41 * \defgroup point-to-point Point-To-Point Network Device 42 * This section documents the API of the ns-3 point-to-point module. For a 43 * functional description, please refer to the ns-3 manual here: 44 * http://www.nsnam.org/docs/models/html/point-to-point.html 45 * 46 * Be sure to read the manual BEFORE going down to the API. 47 */ 48 49 /** 50 * \ingroup point-to-point 51 * \class PointToPointNetDevice 52 * \brief A Device for a Point to Point Network Link. 53 * 54 * This PointToPointNetDevice class specializes the NetDevice abstract 55 * base class. Together with a PointToPointChannel (and a peer 56 * PointToPointNetDevice), the class models, with some level of 57 * abstraction, a generic point-to-point or serial link. 58 * Key parameters or objects that can be specified for this device 59 * include a queue, data rate, and interframe transmission gap (the 60 * propagation delay is set in the PointToPointChannel). 61 */ 62 class PointToPointNetDevice : public NetDevice 63 { 64 public: 65 /** 66 * \brief Get the TypeId 67 * 68 * \return The TypeId for this class 69 */ 70 static TypeId GetTypeId (void); 71 72 /** 73 * Construct a PointToPointNetDevice 74 * 75 * This is the constructor for the PointToPointNetDevice. It takes as a 76 * parameter a pointer to the Node to which this device is connected, 77 * as well as an optional DataRate object. 78 */ 79 PointToPointNetDevice (); 80 81 /** 82 * Destroy a PointToPointNetDevice 83 * 84 * This is the destructor for the PointToPointNetDevice. 85 */ 86 virtual ~PointToPointNetDevice (); 87 88 /** 89 * Set the Data Rate used for transmission of packets. The data rate is 90 * set in the Attach () method from the corresponding field in the channel 91 * to which the device is attached. It can be overridden using this method. 92 * 93 * \param bps the data rate at which this object operates 94 */ 95 void SetDataRate (DataRate bps); 96 97 /** 98 * Set the interframe gap used to separate packets. The interframe gap 99 * defines the minimum space required between packets sent by this device. 100 * 101 * \param t the interframe gap time 102 */ 103 void SetInterframeGap (Time t); 104 105 /** 106 * Attach the device to a channel. 107 * 108 * \param ch Ptr to the channel to which this object is being attached. 109 * \return true if the operation was successful (always true actually) 110 */ 111 bool Attach (Ptr<PointToPointChannel> ch); 112 113 /** 114 * Attach a queue to the PointToPointNetDevice. 115 * 116 * The PointToPointNetDevice "owns" a queue that implements a queueing 117 * method such as DropTailQueue or RedQueue 118 * 119 * \param queue Ptr to the new queue. 120 */ 121 void SetQueue (Ptr<Queue<Packet> > queue); 122 123 /** 124 * Get a copy of the attached Queue. 125 * 126 * \returns Ptr to the queue. 127 */ 128 Ptr<Queue<Packet> > GetQueue (void) const; 129 130 /** 131 * Attach a receive ErrorModel to the PointToPointNetDevice. 132 * 133 * The PointToPointNetDevice may optionally include an ErrorModel in 134 * the packet receive chain. 135 * 136 * \param em Ptr to the ErrorModel. 137 */ 138 void SetReceiveErrorModel (Ptr<ErrorModel> em); 139 140 /** 141 * Receive a packet from a connected PointToPointChannel. 142 * 143 * The PointToPointNetDevice receives packets from its connected channel 144 * and forwards them up the protocol stack. This is the public method 145 * used by the channel to indicate that the last bit of a packet has 146 * arrived at the device. 147 * 148 * \param p Ptr to the received packet. 149 */ 150 void Receive (Ptr<Packet> p); 151 152 // The remaining methods are documented in ns3::NetDevice* 153 154 virtual void SetIfIndex (const uint32_t index); 155 virtual uint32_t GetIfIndex (void) const; 156 157 virtual Ptr<Channel> GetChannel (void) const; 158 159 virtual void SetAddress (Address address); 160 virtual Address GetAddress (void) const; 161 162 virtual bool SetMtu (const uint16_t mtu); 163 virtual uint16_t GetMtu (void) const; 164 165 virtual bool IsLinkUp (void) const; 166 167 virtual void AddLinkChangeCallback (Callback<void> callback); 168 169 virtual bool IsBroadcast (void) const; 170 virtual Address GetBroadcast (void) const; 171 172 virtual bool IsMulticast (void) const; 173 virtual Address GetMulticast (Ipv4Address multicastGroup) const; 174 175 virtual bool IsPointToPoint (void) const; 176 virtual bool IsBridge (void) const; 177 178 virtual bool Send (Ptr<Packet> packet, const Address &dest, uint16_t protocolNumber); 179 virtual bool SendFrom (Ptr<Packet> packet, const Address& source, const Address& dest, uint16_t protocolNumber); 180 181 virtual Ptr<Node> GetNode (void) const; 182 virtual void SetNode (Ptr<Node> node); 183 184 virtual bool NeedsArp (void) const; 185 186 virtual void SetReceiveCallback (NetDevice::ReceiveCallback cb); 187 188 virtual Address GetMulticast (Ipv6Address addr) const; 189 190 virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb); 191 virtual bool SupportsSendFrom (void) const; 192 193 protected: 194 /** 195 * \brief Handler for MPI receive event 196 * 197 * \param p Packet received 198 */ 199 void DoMpiReceive (Ptr<Packet> p); 200 201 private: 202 203 /** 204 * \brief Assign operator 205 * 206 * The method is private, so it is DISABLED. 207 * 208 * \param o Other NetDevice 209 * \return New instance of the NetDevice 210 */ 211 PointToPointNetDevice& operator = (const PointToPointNetDevice &o); 212 213 /** 214 * \brief Copy constructor 215 * 216 * The method is private, so it is DISABLED. 217 218 * \param o Other NetDevice 219 */ 220 PointToPointNetDevice (const PointToPointNetDevice &o); 221 222 /** 223 * \brief Dispose of the object 224 */ 225 virtual void DoDispose (void); 226 227 private: 228 229 /** 230 * \returns the address of the remote device connected to this device 231 * through the point to point channel. 232 */ 233 Address GetRemote (void) const; 234 235 /** 236 * Adds the necessary headers and trailers to a packet of data in order to 237 * respect the protocol implemented by the agent. 238 * \param p packet 239 * \param protocolNumber protocol number 240 */ 241 void AddHeader (Ptr<Packet> p, uint16_t protocolNumber); 242 243 /** 244 * Removes, from a packet of data, all headers and trailers that 245 * relate to the protocol implemented by the agent 246 * \param p Packet whose headers need to be processed 247 * \param param An integer parameter that can be set by the function 248 * \return Returns true if the packet should be forwarded up the 249 * protocol stack. 250 */ 251 bool ProcessHeader (Ptr<Packet> p, uint16_t& param); 252 253 /** 254 * Start Sending a Packet Down the Wire. 255 * 256 * The TransmitStart method is the method that is used internally in the 257 * PointToPointNetDevice to begin the process of sending a packet out on 258 * the channel. The corresponding method is called on the channel to let 259 * it know that the physical device this class represents has virtually 260 * started sending signals. An event is scheduled for the time at which 261 * the bits have been completely transmitted. 262 * 263 * \see PointToPointChannel::TransmitStart () 264 * \see TransmitComplete() 265 * \param p a reference to the packet to send 266 * \returns true if success, false on failure 267 */ 268 bool TransmitStart (Ptr<Packet> p); 269 270 /** 271 * Stop Sending a Packet Down the Wire and Begin the Interframe Gap. 272 * 273 * The TransmitComplete method is used internally to finish the process 274 * of sending a packet out on the channel. 275 */ 276 void TransmitComplete (void); 277 278 /** 279 * \brief Make the link up and running 280 * 281 * It calls also the linkChange callback. 282 */ 283 void NotifyLinkUp (void); 284 285 /** 286 * Enumeration of the states of the transmit machine of the net device. 287 */ 288 enum TxMachineState 289 { 290 READY, /**< The transmitter is ready to begin transmission of a packet */ 291 BUSY /**< The transmitter is busy transmitting a packet */ 292 }; 293 /** 294 * The state of the Net Device transmit state machine. 295 */ 296 TxMachineState m_txMachineState; 297 298 /** 299 * The data rate that the Net Device uses to simulate packet transmission 300 * timing. 301 */ 302 DataRate m_bps; 303 304 /** 305 * The interframe gap that the Net Device uses to throttle packet 306 * transmission 307 */ 308 Time m_tInterframeGap; 309 310 /** 311 * The PointToPointChannel to which this PointToPointNetDevice has been 312 * attached. 313 */ 314 Ptr<PointToPointChannel> m_channel; 315 316 /** 317 * The Queue which this PointToPointNetDevice uses as a packet source. 318 * Management of this Queue has been delegated to the PointToPointNetDevice 319 * and it has the responsibility for deletion. 320 * \see class DropTailQueue 321 */ 322 Ptr<Queue<Packet> > m_queue; 323 324 /** 325 * Error model for receive packet events 326 */ 327 Ptr<ErrorModel> m_receiveErrorModel; 328 329 /** 330 * The trace source fired when packets come into the "top" of the device 331 * at the L3/L2 transition, before being queued for transmission. 332 */ 333 TracedCallback<Ptr<const Packet> > m_macTxTrace; 334 335 /** 336 * The trace source fired when packets coming into the "top" of the device 337 * at the L3/L2 transition are dropped before being queued for transmission. 338 */ 339 TracedCallback<Ptr<const Packet> > m_macTxDropTrace; 340 341 /** 342 * The trace source fired for packets successfully received by the device 343 * immediately before being forwarded up to higher layers (at the L2/L3 344 * transition). This is a promiscuous trace (which doesn't mean a lot here 345 * in the point-to-point device). 346 */ 347 TracedCallback<Ptr<const Packet> > m_macPromiscRxTrace; 348 349 /** 350 * The trace source fired for packets successfully received by the device 351 * immediately before being forwarded up to higher layers (at the L2/L3 352 * transition). This is a non-promiscuous trace (which doesn't mean a lot 353 * here in the point-to-point device). 354 */ 355 TracedCallback<Ptr<const Packet> > m_macRxTrace; 356 357 /** 358 * The trace source fired for packets successfully received by the device 359 * but are dropped before being forwarded up to higher layers (at the L2/L3 360 * transition). 361 */ 362 TracedCallback<Ptr<const Packet> > m_macRxDropTrace; 363 364 /** 365 * The trace source fired when a packet begins the transmission process on 366 * the medium. 367 */ 368 TracedCallback<Ptr<const Packet> > m_phyTxBeginTrace; 369 370 /** 371 * The trace source fired when a packet ends the transmission process on 372 * the medium. 373 */ 374 TracedCallback<Ptr<const Packet> > m_phyTxEndTrace; 375 376 /** 377 * The trace source fired when the phy layer drops a packet before it tries 378 * to transmit it. 379 */ 380 TracedCallback<Ptr<const Packet> > m_phyTxDropTrace; 381 382 /** 383 * The trace source fired when a packet begins the reception process from 384 * the medium -- when the simulated first bit(s) arrive. 385 */ 386 TracedCallback<Ptr<const Packet> > m_phyRxBeginTrace; 387 388 /** 389 * The trace source fired when a packet ends the reception process from 390 * the medium. 391 */ 392 TracedCallback<Ptr<const Packet> > m_phyRxEndTrace; 393 394 /** 395 * The trace source fired when the phy layer drops a packet it has received. 396 * This happens if the receiver is not enabled or the error model is active 397 * and indicates that the packet is corrupt. 398 */ 399 TracedCallback<Ptr<const Packet> > m_phyRxDropTrace; 400 401 /** 402 * A trace source that emulates a non-promiscuous protocol sniffer connected 403 * to the device. Unlike your average everyday sniffer, this trace source 404 * will not fire on PACKET_OTHERHOST events. 405 * 406 * On the transmit size, this trace hook will fire after a packet is dequeued 407 * from the device queue for transmission. In Linux, for example, this would 408 * correspond to the point just before a device \c hard_start_xmit where 409 * \c dev_queue_xmit_nit is called to dispatch the packet to the PF_PACKET 410 * ETH_P_ALL handlers. 411 * 412 * On the receive side, this trace hook will fire when a packet is received, 413 * just before the receive callback is executed. In Linux, for example, 414 * this would correspond to the point at which the packet is dispatched to 415 * packet sniffers in \c netif_receive_skb. 416 */ 417 TracedCallback<Ptr<const Packet> > m_snifferTrace; 418 419 /** 420 * A trace source that emulates a promiscuous mode protocol sniffer connected 421 * to the device. This trace source fire on packets destined for any host 422 * just like your average everyday packet sniffer. 423 * 424 * On the transmit size, this trace hook will fire after a packet is dequeued 425 * from the device queue for transmission. In Linux, for example, this would 426 * correspond to the point just before a device \c hard_start_xmit where 427 * \c dev_queue_xmit_nit is called to dispatch the packet to the PF_PACKET 428 * ETH_P_ALL handlers. 429 * 430 * On the receive side, this trace hook will fire when a packet is received, 431 * just before the receive callback is executed. In Linux, for example, 432 * this would correspond to the point at which the packet is dispatched to 433 * packet sniffers in \c netif_receive_skb. 434 */ 435 TracedCallback<Ptr<const Packet> > m_promiscSnifferTrace; 436 437 Ptr<Node> m_node; //!< Node owning this NetDevice 438 Mac48Address m_address; //!< Mac48Address of this NetDevice 439 NetDevice::ReceiveCallback m_rxCallback; //!< Receive callback 440 NetDevice::PromiscReceiveCallback m_promiscCallback; //!< Receive callback 441 // (promisc data) 442 uint32_t m_ifIndex; //!< Index of the interface 443 bool m_linkUp; //!< Identify if the link is up or not 444 TracedCallback<> m_linkChangeCallbacks; //!< Callback for the link change event 445 446 static const uint16_t DEFAULT_MTU = 1500; //!< Default MTU 447 448 /** 449 * \brief The Maximum Transmission Unit 450 * 451 * This corresponds to the maximum 452 * number of bytes that can be transmitted as seen from higher layers. 453 * This corresponds to the 1500 byte MTU size often seen on IP over 454 * Ethernet. 455 */ 456 uint32_t m_mtu; 457 458 Ptr<Packet> m_currentPkt; //!< Current packet processed 459 460 /** 461 * \brief PPP to Ethernet protocol number mapping 462 * \param protocol A PPP protocol number 463 * \return The corresponding Ethernet protocol number 464 */ 465 static uint16_t PppToEther (uint16_t protocol); 466 467 /** 468 * \brief Ethernet to PPP protocol number mapping 469 * \param protocol An Ethernet protocol number 470 * \return The corresponding PPP protocol number 471 */ 472 static uint16_t EtherToPpp (uint16_t protocol); 473 }; 474 475 } // namespace ns3 476 477 #endif /* POINT_TO_POINT_NET_DEVICE_H */ 478