@node PointToPoint NetDevice
@chapter PointToPoint NetDevice

This is the introduction to PointToPoint NetDevice chapter, to complement the
PointToPoint model doxygen.

@menu
* Overview of the PointToPoint model::
* Using the PointToPointNetDevice::
* PointToPoint Tracing::
@end menu

@node Overview of the PointToPoint model
@section Overview of the PointToPoint model

The ns-3 point-to-point model is of a very simple point to point data link
connecting exactly two PointToPointNetDevice devices over an
PointToPointChannel.  This can be viewed as equivalent to a full
duplex RS-232 or RS-422 link with null modem and no handshaking.

Data is encapsulated in the Point-to-Point Protocol (PPP -- RFC 1661),
however the Link Control Protocol (LCP) and associated state machine is 
not implemented.  The PPP link is assumed to be established and 
authenticated at all times.

Data is not framed, therefore Address and Control fields will not be found.
Since the data is not framed, there is no need to provide Flag Sequence and
Control Escape octets, nor is a Frame Check Sequence appended.  All that is
required to implement non-framed PPP is to prepend the PPP protocol number
for IP Version 4 which is the sixteen-bit number 0x21 (see
http://www.iana.org/assignments/ppp-numbers).

The PointToPointNetDevice provides following Attributes:

@itemize @bullet
@item Address:  The ns3::Mac48Address of the device (if desired);
@item DataRate:  The data rate (ns3::DataRate) of the device;
@item TxQueue:  The transmit queue (ns3::Queue) used by the device;
@item InterframeGap:  The optional ns3::Time to wait between "frames";
@item Rx:  A trace source for received packets;
@item Drop:  A trace source for dropped packets.
@end itemize

The PointToPointNetDevice models a transmitter section that puts bits
on a corresponding channel "wire."  `The DataRate attribute specifies the
number of bits per second that the device will simulate sending over the 
channel.  In reality no bits are sent, but an event is scheduled for an
elapsed time consistent with the number of bits in each packet and the 
specified DataRate.  The implication here is that the receiving device
models a receiver section that can receive any any data rate.  Therefore
there is no need, nor way to set a receive data rate in this model.  By
setting the DataRate on the transmitter of both devices connected to a 
given PointToPointChannel one can model a symmetric channel; or by 
setting different DataRates one can model an asymmetric channel (e.g., 
ADSL).

The PointToPointNetDevice supports the assignment of a "receive error 
model."  This is an ErrorModel object that is used to simulate data
corruption on the link.

@section  Point-to-Point Channel Model

The point to point net devices are connected via an 
PointToPointChannel.  This channel models two wires transmitting bits
at the data rate specified by the source net device.  There is no overhead
beyond the eight bits per byte of the packet sent.  That is, we do not 
model Flag Sequences, Frame Check Sequences nor do we "escape" any data.

The PointToPointChannel provides following Attributes:

@itemize @bullet
@item Delay:  An ns3::Time specifying the speed of light transmission delay for
the channel.
@end itemize

@node Using the PointToPointNetDevice
@section Using the PointToPointNetDevice

The PointToPoint net devices and channels are typically created and configured using
the associated @code{PointToPointHelper} object.  The various ns3 device helpers 
generally work in a similar way, and their use is seen in many of our example
programs and is also covered in the ns-3 tutorial.

The conceptual model of interest is that of a bare computer ``husk'' into which 
you plug net devices.  The bare computers are created using a @code{NodeContainer}
helper.  You just ask this helper to create as many computers (we call them
@code{Nodes}) as you need on your network:

@verbatim
  NodeContainer nodes;
  nodes.Create (2);
@end verbatim

Once you have your nodes, you need to instantiate a @code{PointToPointHelper} and set
any attributes you may want to change.  Note that since this is a point-to-point 
(as compared to a point-to-multipoint) there may only be two nodes with associated 
net devices connected by a PointToPointChannel.

@verbatim

  PointToPointHelper pointToPoint;
  pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
  pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
@end verbatim
 
Once the attributes are set, all that remains is to create the devices
and install them on the required nodes, and to connect the devices 
together using a PointToPoint channel.  When we create the net devices, we add
them to a container to allow you to use them in the future.  This all
takes just one line of code.

@verbatim
  NetDeviceContainer devices = pointToPoint.Install (nodes);
@end verbatim

@node PointToPoint Tracing
@section PointToPoint Tracing

Like all ns-3 devices, the Point-to-Point Model provides a number of trace 
sources.  These trace sources can be hooked using your own custom trace code,
or you can use our helper functions to arrange for tracing to be enabled on 
devices you specify.

@subsection Upper-Level (MAC) Hooks

From the point of view of tracing in the net device, there are several 
interesting points to insert trace hooks.  A convention inherited from other
simulators is that packets destined for transmission onto attached networks
pass through a single "transmit queue" in the net device.  We provide trace 
hooks at this point in packet flow, which corresponds (abstractly) only to a 
transition from the network to data link layer, and call them collectively
the device MAC hooks.

When a packet is sent to the Point-to-Point net device for transmission it 
always passes through the transmit queue.  The transmit queue in the 
PointToPointNetDevice inherits from Queue, and therefore inherits three 
trace sources:

@itemize @bullet
@item An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
@item A Dequeue operation source (see ns3::Queue::m_traceDequeue);
@item A Drop operation source (see ns3::Queue::m_traceDrop).
@end itemize

The upper-level (MAC) trace hooks for the PointToPointNetDevice are, in fact, 
exactly these three trace sources on the single transmit queue of the device.  

The m_traceEnqueue event is triggered when a packet is placed on the transmit
queue.  This happens at the time that ns3::PointtoPointNetDevice::Send or 
ns3::PointToPointNetDevice::SendFrom is called by a higher layer to queue a 
packet for transmission.  An Enqueue trace event firing should be interpreted
as only indicating that a higher level protocol has sent a packet to the device.

The m_traceDequeue event is triggered when a packet is removed from the
transmit queue.  Dequeues from the transmit queue can happen in two
situations:  1) If the underlying channel is idle when 
PointToPointNetDevice::Send is called, a packet is dequeued from the transmit
queue and immediately transmitted;  2) a packet may be dequeued and 
immediately transmitted in an internal TransmitCompleteEvent that functions 
much  like a transmit complete interrupt service routine.  An Dequeue trace 
event firing may be viewed as indicating that the PointToPointNetDevice has
begun transmitting a packet.

@subsection Lower-Level (PHY) Hooks

Similar to the upper level trace hooks, there are trace hooks available at
the lower levels of the net device.  We call these the PHY hooks.  These 
events fire from the device methods that talk directly to the 
PointToPointChannel.

The trace source m_dropTrace is called to indicate a packet that is dropped
by the device.  This happens when a packet is discarded as corrupt due to a 
receive error model indication (see ns3::ErrorModel and the associated 
attribute "ReceiveErrorModel").

The other low-level trace source fires on reception of a packet (see 
ns3::PointToPointNetDevice::m_rxTrace) from the PointToPointChannel.
