--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/csma.texi	Fri Dec 12 11:27:05 2008 -0800
@@ -0,0 +1,334 @@
+@node CSMA NetDevice
+@chapter CSMA NetDevice
+
+This is the introduction to CSMA NetDevice chapter, to complement the
+Csma model doxygen.
+
+@menu
+* Overview of the model::
+* Using the CsmaNetDevice::
+* CSMA Tracing::
+@end menu
+
+@node Overview of the model
+@section Overview of the model
+
+The ns-3 CSMA device models a simple bus network in the spirit of Ethernet.
+Although it does not model any real physical network you could ever build 
+or buy, it does provide some very useful functionality.
+
+Typically when one thinks of a bus network Ethernet or IEEE 802.3 comes to
+mind.  Ethernet uses CSMA/CD (Carrier Sense Multiple Access with Collision
+Detection with exponentially increasing backoff to contend for the shared 
+transmission medium.  The ns-3 CSMA device models only a portion of this 
+process, using the nature of the globally available channel to provide 
+instantaneous (faster than light) carrier sense and priority-based 
+collision "avoidance."  Collisions in the sense of Ethernet never happen and
+so the ns-3 CSMA device does not model collision detection, nor will any
+transmission in progress be "jammed."
+
+@subsection CSMA Layer Model
+
+There are a number of conventions in use for describing layered 
+communications architectures in the literature and in textbooks.  The most
+common layering  model is the ISO seven layer reference model.  In this view
+the CsmaNetDevice and CsmaChannel pair occupies the lowest two 
+layers -- at the physical (layer one), and data link (layer two) positions.
+Another important reference model is that specified by RFC 1122, 
+"Requirements for Internet Hosts -- Communication Layers."  In this view the
+CsmaNetDevice and CsmaChannel pair occupies the lowest layer -- 
+the link layer.  There is also a seemingly endless litany of alternative 
+descriptions found in textbooks and in the literature.  We adopt the naming
+conventions used in the IEEE 802 standards which speak of LLC, MAC, MII
+and PHY layering.  These acronyms are defined as:
+
+@itemize @bullet
+@item LLC:  Logical Link Control;
+@item MAC:  Media Access Control;
+@item MII:  Media Independent Interface;
+@item PHY:  Physical Layer.
+@end itemize
+
+In this case the @emph{LLC} and @emph{MAC }are sublayers of the OSI data link 
+layer and the @emph{MII} and @emph{PHY} are sublayers of the OSI physical layer.
+
+The "top" of the CSMA device defines the transition from the network layer
+to the data link layer.  This transition is performed by higher layers by 
+calling either CsmaNetDevice::Send or CsmaNetDevice::SendFrom.
+
+In contrast to the IEEE 802.3 standards, there is no precisely specified
+PHY in the CSMA model in the sense of wire types, signals or pinouts.  The
+"bottom" interface of the CsmaNetDevice can be thought of as as a kind
+of Media Independent Interface (MII) as seen in the "Fast Ethernet" 
+(IEEE 802.3u) specifications.  This MII interface fits into a corresponding
+media independent interface on the CsmaChannel.  You will not find the
+equivalent of a 10BASE-T or a 1000BASE-LX PHY.
+
+The CsmaNetDevice calls the CsmaChannel through a media independent
+interface.  There is a method defined to tell the channel when to start 
+"wiggling the wires" using the method CsmaChannel::TransmitStart, and 
+a method to tell the channel when the transmission process is done and
+the channel should begin propagating the last bit across the "wire":
+CsmaChannel::TransmitEnd.
+
+When the TransmitEnd method is executed, the channel will model a single 
+uniform signal propagation delay in the medium and deliver copes of the packet
+to each of the devices attached to the packet via the 
+CsmaNetDevice::Receive method.
+
+There is a "pin" in the device media independent interface corresponding to 
+"COL" (collision).  The state of the channel may be sensed by calling 
+CsmaChannel::GetState.  Each device will look at this "pin" before 
+starting a send and will perform appropriate backoff operations if required.
+
+Properly received packets are forwarded up to higher levels from the 
+CsmaNetDevice via a callback mechanism.  The callback function is
+initialized by the higher layer (when the net device is attached) using
+CsmaNetDevice::SetReceiveCallback and is invoked upon "proper"
+ reception of a packet by the net device in order to forward the packet up
+the protocol stack.
+
+@section CSMA Channel Model
+
+The class CsmaChannel models the actual transmission medium.
+There is no fixed limit for the number of devices connected to the channel.
+The CsmaChannel models a data rate and a speed-of-light delay which can
+be accessed via the attributes "DataRate" and "Delay" respectively.
+The data rate provided to the channel is used to set the data rates
+used by the transmitter sections of the CSMA devices connected to the 
+channel.  There is no way to independently set data rates in the
+devices.  Since the data rate is only used to calculate a delay time, there
+is no limitation (other than by the data type holding the value) on the 
+speed at which CSMA channels and devices can operate; and no restriction
+based on any kind of PHY characteristics.
+
+The CsmaChannel has three states, @code{IDLE}, @code{TRANSMITTING} and 
+@code{PROPAGATING}.  These three states are "seen" instantaneously by all 
+devices on the channel.  By this we mean that if one device begins or ends a
+simulated transmission, all devices on the channel are @emph{immediately}
+aware of the change in state.  There is no time during which one device may
+see an @code{IDLE} channel while another device physically further away in 
+the collision domain may have begun transmitting with the associated signals 
+not propagated down the channel to other devices.  Thus there is no need for
+collision detection in the CsmaChannel model and it is not implemented in any
+way.
+
+We do, as the name indicates, have a Carrier Sense aspect to the model.
+Since the simulator is single threaded, access to the common channel will
+be serialized by the simulator.  This provides a deterministic mechanism
+for contending for the channel.  The channel is allocated (transitioned from
+state @code{IDLE} to state @code{TRANSMITTING}) on a first-come first-served 
+basis.  The channel always goes through a three state process:
+
+@verbatim
+  IDLE -> TRANSMITTING -> PROPAGATING -> IDLE
+@end verbatim
+
+The @code{TRANSMITTING} state models the time during which the source net device
+is actually wiggling the signals on the wire.  The @code{PROPAGATING} state 
+models the time after the last bit was sent, when the signal is propagating down 
+the wire to the "far end."  
+
+The transition to the @code{TRANSMITTING} state is  driven by a call to 
+CsmaChannel::TransmitStart which is called by the net device that 
+transmits the packet.  It is the responsibility of that device to end the
+transmission with a call to CsmaChannel::TransmitEnd at the appropriate
+simulation time that reflects the time elapsed to put all of the packet bits
+on the wire.  When TransmitEnd is called, the channel schedules an event
+corresponding to a single speed-of-light delay.  This delay applies to all
+net devices on the channel identically.  You can think of a symmetrical hub
+in which the packet bits propagate to a central location and then back out
+equal length cables to the other devices on the channel.  The single ``speed
+of light'' delay then corresponds to the time it takes for: 1) a singal to 
+propagate from one CsmaNetDevice through its cable to the hub; plus 2) the
+time it takes for the hub to forward the packet out a port; plus 3) the time
+it takes for the signal in question to propagate to the destination net 
+device.
+
+The CsmaChannel models a broadcast medium so the packet is delivered
+to all of the devices on the channel (including the source) at the end of 
+the propagation time.  It is the responsibility of the sending device to 
+determine whether or not it receives a packet broadcast over the channel.
+
+The CsmaChannel provides following Attributes:
+
+@itemize @bullet
+@item DataRate:  The bitrate for packet transmission on connected devices;
+@item Delay: The speed of light transmission delay for the channel.
+@end itemize
+
+@section CSMA Net Device Model
+
+ The CSMA network device appears somewhat like an Ethernet device.  The
+ CsmaNetDevice provides following Attributes:
+
+@itemize @bullet
+@item Address:  The Mac48Address of the device;
+@item SendEnable:  Enable packet transmission if true;
+@item ReceiveEnable:  Enable packet reception if true;
+@item EncapsulationMode:  Type of link layer encapsulation to use;
+@item RxErrorModel:  The receive error model;
+@item TxQueue:  The trasmit queue used by the device;
+@item InterframeGap:  The optional time to wait between "frames";
+@item Rx:  A trace source for received packets;
+@item Drop:  A trace source for dropped packets.
+@end itemize
+
+The CsmaNetDevice supports the assignment of a "receive error model."
+This is an ErrorModel object that is used to simulate data corruption
+on the link.
+
+Packets sent over the CsmaNetDevice are always routed through the 
+transmit queue to provide a trace hook for packets sent out over the 
+network.  This transmit queue can be set (via attribute) to model different
+queueing strategies.
+
+Also configurable by attribute is the encapsulation method used by the
+device.  Every packet gets an EthernetHeader that includes the 
+destination and source MAC addresses, and a length/type field.  Every packet
+also gets an EthernetTrailer which includes the FCS.  Data in the
+packet may be encapsulated in different ways.  
+
+By default, or by setting the "EncapsulationMode" attribute to "Dix", the 
+encapsulation is according to the DEC, Intel, Xerox standard.  This is sometimes
+called EthernetII framing and is the familiar destination MAC, source MAC, 
+EtherType, Data, CRC format.
+
+If the "EncapsulationMode" attribute is set to "Llc", the encapsulation is by 
+LLC SNAP.  In this case, a SNAP header is added that contains the EtherType
+(IP or ARP).  
+
+The other implemented encapsulation modes are IP_ARP (set "EncapsulationMode" to
+"IpArp") in which the length type of the Ethernet header receives the protocol 
+number of the packet; or ETHERNET_V1 (set "EncapsulationMode" to "EthernetV1") 
+in which the length type of the Ethernet header receives the length of the packet.
+A "Raw" encapsulation mode is defined but not implemented -- use of the RAW mode 
+results in an assertion.  
+
+Note that all net devices on a channel must be set to the same encapsulation mode
+for correct results.  The encapsulation mode is not sensed at the receiver.
+
+The CsmaNetDevice implements a random exponential backoff algorithm 
+that is executed if the channel is determined to be busy (@code{TRANSMITTING} or
+@code{PPROPAGATING}) when the device wants to start propagating.  This results in a
+random delay of up to pow (2, retries) - 1 microseconds before a retry is
+attempted.  The default maximum number of retries is 1000.
+
+@node Using the CsmaNetDevice
+@section Using the CsmaNetDevice
+
+The CSMA net devices and channels are typically created and configured using
+the associated @code{CsmaHelper} object.  The various ns3 device dhelpers 
+generatlly work in a simlar way, and their use is seen in many of our example
+programs.
+
+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 csmaNodes;
+  csmaNodes.Create (nCsmaNodes);
+@end verbatim
+
+Once you have your nodes, you need to instantiate a @code{CsmaHelper} and set
+any attributes you may want to change.
+
+@verbatim
+  CsmaHelper csma;
+  csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
+  csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));
+
+  csma.SetDeviceAttribute ("EncapsulationMode", StringValue ("Dix"));
+  csma.SetDeviceAttribute ("FrameSize", UintegerValue (2000));
+@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 CSMA 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 csmaDevices = csma.Install (csmaNodes);
+@end verbatim
+
+@node Csma Tracing
+@section CSMA Tracing
+
+Like all ns-3 devices, the CSMA 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 CSMA net device for transmission it always 
+passes through the transmit queue.  The transmit queue in the 
+CsmaNetDevice inherits from Queue, and therefore inherits three 
+trace sources:
+
+@itemize @bullet
+@item An Enqueue operation source (see Queue::m_traceEnqueue);
+@item A Dequeue operation source (see Queue::m_traceDequeue);
+@item A Drop operation source (see Queue::m_traceDrop).
+@end itemize
+
+The upper-level (MAC) trace hooks for the CsmaNetDevice 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 CsmaNetDevice::Send or 
+CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for 
+transmission.
+
+The m_traceDequeue event is triggered when a packet is removed from the
+transmit queue.  Dequeues from the transmit queue can happen in three 
+situations:  1) If the underlying channel is idle when the 
+CsmaNetDevice::Send or CsmaNetDevice::SendFrom is called, a packet
+is dequeued from the transmit queue and immediately transmitted;  2) If the
+underlying channel is idle, a packet may be dequeued and immediately 
+transmitted in an internal TransmitCompleteEvent that functions much 
+like a transmit complete interrupt service routine; or 3) from
+the random exponential backoff handler if a timeout is detected.
+
+Case (3) implies that a packet is dequeued from the transmit queue if it is 
+unable to be transmittted according to the backoff rules.  It is important 
+to understand that this will appear as a Dequeued packet and it is easy to 
+incorrectly assume that the packet was transmitted since it passed through
+the transmit queue.  In fact, a packet is actually dropped by the net device
+in this case.  The reason for this behavior is due to the definition of the 
+Queue Drop event.  The m_traceDrop event is, by defintion, fired when a 
+packet cannot be enqueued on the transmit queue becasue it is full.  This 
+event only fires if the queue is full and we do not overload this event
+to indicate that the CsmaChannel is "full."
+
+@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 CsmaChannel.
+
+The trace source m_dropTrace is called to indicate a packet that is dropped
+by the device.  This happens in two cases:  First, if the receive side of 
+the net device is not enabled (see CsmaNetDevice::m_receiveEnable and the 
+associated attribute "ReceiveEnable").
+
+The m_dropTrace is also used to indicate that a packet was discarded as 
+corrupt if a receive error model is used (see 
+CsmaNetDevice::m_receiveErrorModel and the associated attribute 
+"ReceiveErrorModel").
+
+The other low-level trace source fires on reception of an accepted packet
+(see CsmaNetDevice::m_rxTrace).  A packet is accepted if it is destined
+for the broadcast address, a multicast address, or to the MAC address 
+assigned to the net device.

--- a/src/devices/csma/csma.h	Fri Dec 12 11:40:59 2008 +0000
+++ b/src/devices/csma/csma.h	Fri Dec 12 11:27:05 2008 -0800
@@ -161,19 +161,21 @@
  * queueing strategies.
  *
  * Also configurable by attribute is the encapsulation method used by the
- * device.  Every packet gets an EthernetHeader that includes the 
- * destination and source MAC addresses, and a length/type field.  Every packet
- * also gets an EthernetTrailer which includes the FCS.  Data in the
- * packet may be encapsulated in different ways.  By default, or by setting
- * the "EncapsulationMode" attribute to "Llc", the encapsulation is by 
+ * device.  By default, or by setting the "EncapsulationMode" attribute to 
+ * "Dix", the encapsulation is according to the DEC, Intel, Xerox standard.
+ * This is sometimes called EthernetII framing and is the familiar destination
+ * MAC, source MAC, EtherType, Data, CRC format.
+ *
+ * If the "EncapsulationMode" attribute is set to "Llc", the encapsulation is by 
  * LLC SNAP.  In this case, a SNAP header is added that contains the EtherType
- * (IP or ARP).  The other implemented encapsulation modes are IP_ARP (set
- * "EncapsulationMode" to "IpArp") in which the length type of the Ethernet 
- * header receives the protocol number of the packet; or ETHERNET_V1 (set
- * "EncapsulationMode" to "EthernetV1") in which the length type of the 
- * Ethernet header receives the length of the packet.  A "Raw" encapsulation
- * mode is defined but not implemented -- use of the RAW mode results in an
- * assert firing.
+ * (IP or ARP).  
+ *
+ * The other implemented encapsulation modes are IP_ARP (set "EncapsulationMode"
+ * to "IpArp") in which the length type of the Ethernet header receives the 
+ * protocol number of the packet; or ETHERNET_V1 (set "EncapsulationMode" to 
+ * "EthernetV1") in which the length type of the Ethernet header receives the 
+ * length of the packet.  A "Raw" encapsulation mode is defined but not 
+ * implemented -- use of the RAW mode results in an assertion.
  *
  * The CsmaNetDevice implements a random exponential backoff algorithm 
  * that is executed if the channel is determined to be busy (TRANSMITTING or
@@ -241,7 +243,7 @@
  * 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 CsmaChannel.
-
+ *
  * The trace source m_dropTrace is called to indicate a packet that is dropped
  * by the device.  This happens in two cases:  First, if the receive side of 
  * the net device is not enabled (see ns3::CsmaNetDevice::m_receiveEnable and the 

--- a/src/devices/emu/emu-net-device.cc	Fri Dec 12 11:40:59 2008 +0000
+++ b/src/devices/emu/emu-net-device.cc	Fri Dec 12 11:27:05 2008 -0800
@@ -88,11 +88,8 @@
                    MakePointerAccessor (&EmuNetDevice::m_queue),
                    MakePointerChecker<Queue> ())
     .AddTraceSource ("Rx", 
-                     "Trace source to fire on reception of a MAC packet.",
+                     "Trace source indicating recvfrom of packet destined for broadcast, multicast or local address.",
                      MakeTraceSourceAccessor (&EmuNetDevice::m_rxTrace))
-    .AddTraceSource ("Drop", 
-                     "Trace source to fire on when a MAC packet is dropped.",
-                     MakeTraceSourceAccessor (&EmuNetDevice::m_dropTrace))
     ;
   return tid;
 }