--- a/doc/manual/manual.texi	Sat Sep 20 15:45:31 2008 -0700
+++ b/doc/manual/manual.texi	Sun Sep 21 13:10:08 2008 -0700
@@ -81,6 +81,7 @@
 * Random variables::
 * Callbacks::
 * Attributes::
+* RealTime::
 * Packets::
 * Sockets APIs::
 * Node and Internet Stack::
@@ -92,6 +93,7 @@
 @include random.texi
 @include callbacks.texi
 @include attributes.texi
+@include realtime.texi
 @include packets.texi
 @include sockets.texi
 @include node.texi

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/realtime.texi	Sun Sep 21 13:10:08 2008 -0700
@@ -0,0 +1,100 @@
+@node RealTime
+@chapter Real-Time Scheduler
+@anchor{chap:RealTime}
+
+ns-3 has been designed for integration into testbed and virtual machine
+environments.  To integrate with real network stacks and emit/consume
+packets, a real-time scheduler is needed to try to lock the simulation
+clock with the hardware clock.  We describe here a component of this:
+the RealTime scheduler. 
+
+The purpose of the realtime scheduler is to cause the progression of 
+the simulation clock to occur synchronously with respect to some 
+external time base. Without the presence of an external time base 
+(wall clock), simulation time jumps instantly from one simulated time to 
+the next.
+
+@section Behavior
+
+When using a non-realtime scheduler (the default in ns-3), the simulator
+advances the simulation time to the next scheduled event.  During event
+execution, simulation time is frozen.  With the realtime scheduler, the 
+behavior is similar from the perspective of simulation models (i.e.,
+simulation time is frozen during event execution), but between events,
+the simulator will attempt to keep the simulation clock aligned with
+the machine clock.
+
+When an event is finished executing, and the scheduler moves to the next
+event, the scheduler compares the next event execution time with the
+machine clock.  If the next event is scheduled for a future time,
+the simulator sleeps until that realtime is reached and then executes
+the next event.
+
+It may happen that, due to the processing inherent in the execution
+of simulation events, that the simulator cannot keep up with realtime.
+In such a case, it is up to the user configuration what to do.  There
+are two ns-3 attributes that govern the behavior.  The first is
+@code{ns3::RealTimeSimulatorImpl::SynchronizationMode}.  The two
+entries possible for this attribute are @code{BestEffort} (the default)
+or @code{HardLimit}.  In "BestEffort" mode, the simulator will just
+try to catch up to realtime by executing events until it reaches
+a point where the next event is in the (realtime) future, or else
+the simulation ends.  In BestEffort mode, then, it is possible for
+the simulation to consume more time than the wall clock time.  The
+other option "HardLimit" will cause the simulation to abort if the tolerance
+threshold is exceeded.  This attribute is
+@code{ns3::RealTimeSimulatorImpl::HardLimit} and the default is 0.1 seconds.   
+
+A different mode of operation is one in which simulated time is @strong{not}
+frozen during an event execution.  This mode of realtime simulation was
+implemented but removed from the ns-3 tree because of questions of whether
+it would be useful.  If users are interested in a realtime simulator
+for which simulation time does not freeze during event execution (i.e.,
+every call to @code{Simulator::Now()} returns the current wall clock time,
+not the time at which the event started executing), please contact the
+ns-developers mailing list.
+
+@section Usage
+
+The usage of the realtime simulator is straightforward, from a scripting
+perspective.  Users just need to set the attribute 
+@code{SimulatorImplementationType} to the Realtime simulator, such as follows:
+@verbatim
+  GlobalValue::Bind ("SimulatorImplementationType",
+    StringValue ("ns3::RealtimeSimulatorImpl"));
+@end verbatim
+
+There is a script in @code{examples/realtime-udp-echo.cc} that has an
+example of how to configure the realtime behavior.  Try:
+@verbatim
+./waf --run realtime-udp-echo
+@end verbatim
+
+Whether the simulator will work in a best effort or hard limit policy
+fashion is governed by the attributes explained in the previous section.
+
+@section Implementation
+
+The implementation is contained in the following files:
+@itemize @bullet
+@item @code{src/simulator/realtime-simulator-impl.{cc,h}}
+@item @code{src/simulator/wall-clock-synchronizer.{cc,h}}
+@end itemize
+
+In order to create a realtime scheduler, to a first approximation you 
+just want to cause simulation time jumps to consume real time. We propose 
+doing this using a combination of sleep- and busy- waits. Sleep-waits cause 
+the calling process (thread) to yield the processor for some amount of time. 
+Even though this specified amount of time can be passed to nanosecond 
+resolution, it is actually converted to an OS-specific granularity. 
+In Linux, the granularity is called a Jiffy. Typically this resolution is 
+insufficient for our needs (on the order of a ten milliseconds), so we 
+round down and sleep for some smaller number of Jiffies. The process is 
+then awakened after the specified number of Jiffies has passed. At this 
+time, we have some residual time to wait. This time is generally smaller 
+than the minimum sleep time, so we busy-wait for the remainder of the time. 
+This means that the thread just sits in a for loop consuming cycles until 
+the desired time arrives. After the combination of sleep- and busy-waits, 
+the elapsed realtime (wall) clock should agree with the simulation time 
+of the next event and the simulation proceeds. 
+