/*
 * Copyright (c) Xerox Corporation 1997. All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * Linking this file statically or dynamically with other modules is making
 * a combined work based on this file.  Thus, the terms and conditions of
 * the GNU General Public License cover the whole combination.
 *
 * In addition, as a special exception, the copyright holders of this file
 * give you permission to combine this file with free software programs or
 * libraries that are released under the GNU LGPL and with code included in
 * the standard release of ns-2 under the Apache 2.0 license or under
 * otherwise-compatible licenses with advertising requirements (or modified
 * versions of such code, with unchanged license).  You may copy and
 * distribute such a system following the terms of the GNU GPL for this
 * file and the licenses of the other code concerned, provided that you
 * include the source code of that other code when and as the GNU GPL
 * requires distribution of source code.
 *
 * Note that people who make modified versions of this file are not
 * obligated to grant this special exception for their modified versions;
 * it is their choice whether to do so.  The GNU General Public License
 * gives permission to release a modified version without this exception;
 * this exception also makes it possible to release a modified version
 * which carries forward this exception.
 */

The script test-suite-intserv.tcl helps runs various measurement based admission
control algorithms for controlled-load services in ns. 

A. FUNCTIONALITY :
------------------
To support controlled load services, there have been essentially 2
pieces of functionality added :
1. End to End signalling mechanism to request a new connection.
2. Enhanced Link Structure.


1.End to End Signalling Mechanism(sa.cc,saack.cc):
  ------------------------------------------------
A very simple end-to-end signalling protocol(which uses a 3 way handshake)
has been implemented to request services. 

The signalling protocol is sender-initiated wherein
the sender sends a "request message"(PT_REQUEST) with the token bucket
parameters(r,b).The message  goes all the way to the receiver thru the
intserv enhanced links. 

The receiver reverses the "request message" as a
"reply message"(PT_REPLY) to the sender. The sender then resends the
"reply message" as "confirm message"(PT_CONFIRM) to the receiver. The reply
message is needed to indicate to the sender about the successful
establishment of connection, after which it may start transmitting
data packets. If the reply is a reject, then the source sends the
"confirm message" and no more packets.
Since, in the ns framework, the reply message traverses through
different simple-links than the request message, the confirm message is
required to indicate to the signal-support boxes(see below) in the links about
the fate of the connection. This is particularly significant for the
state of those links which said "yes" to a connection but the
connection got rejected on a downstream link.

Finally the sender sends a teardown message at the end of the connection.

Consequently there are 4 new packet types added :
PT_REQUEST
PT_REPLY
PT_CONFIRM
PT_TEARDOWN

In addition, a new header type (hdr-resv) (in resv.h) defines fields
(for token bucket parameters) for integrated services.

2. Intserv Link :
---------------
The SimpleLink structure has been enhanced to look like :
                      ______________________________________
                     |         |                |           |
                     |Admission|            ____|____   ____|____
       |-------------|Control  |           |         | |         |
       |             |         |           |Estimator| |Estimator|
       |             |_________|           |____1____| |____n____|
       |                                       |       |
       |                                    ___|___    |
       |                                   |       |   |         _____ 
    ___|____     _________     _____     _>|Meas-  |   |        |     |
   |        |   |         |   |     \   | >|urement|   |        |Delay|
__>| Signal |__>|Scheduler|__>|Class-\__|  | for   |___|_______>|Link |
  >| Support|  >|(Queue)  |  >|-ifier/  |  |class 1|   |    |  >|_____| 
   |________|   |_________|   |_____/   |  |_______|   |    |       
                                        |   ......     |    |
                                        |   ......     |    |
                                        |_> _______    |    |
                                        | >|       |   |    |            
                                        |  |Meas-  |   |    |
                                        |  |urement|___|    |
                                        |  | for   |________|
                                        |  |class n|        |
                                        |  |_______|        |
                                        |                   |
                                        |>__________________|
                                         > Best Effort traffic
___> indicates packet flow
   >


For supporting controlled load service only, it is assumed that there
would be only 2 classes of traffic : controlled load and best effort and
so the above link model simplifies to one where there is only 1
measurement and 1 estimator box (tcl/ex/ns-intserv.tcl implements the
above link structure).


A detailed description of each of the components is as follows :

Signal-support(salink.cc):
-------------------------
The links need to maintain some transient state about flows requesting
service (specifically the link needs to remember its decision for a
new flow until it gets the PT_CONFIRM message).

Scheduler(simple-intserv-sched.cc):
------------------------------
For controlled load service support, a very simple scheduler queue is
implemented as a 2 level service priority queue. Also all signalling
control messages are explicitly prevented from drops.

Classifier:
----------
Currently, the classifier is a flow-classifier. It treats all traffic
with non-zero fid as controlled load traffic and those with zero fid
as best effort traffic.


Measurement, Estimator and Admission Control Objects:
----------------------------------------------------
The measurement object is a very simple object that measures per-class
packets. The Estimator estimates the used bandwidth based on the
etimation algorithm in play (which could one of TimeWindow,
PointSample or Exponential Average). The admission control object
makes an admission control decision based on the load estimate (from
the estimator) and the admission control algorithm in play (which could
be one of Measured Sum, Hoeffding bounds, Acceptance region-Tangent at
Origin or Acceptance region-Tangent at Peak). When a new connection
request comes to a link, the signal-support module asks the admission
control for a decision which in turn looks at the current load
estimate and the new flow parameters.  


B.USER-LEVEL API :
-----------------
To create a int-serv enabled link, use :

$ns duplex-intserv-link $n1 $n2 <link bw> <propgn delay> <sched type>
<signal-support type>  <adc type > <est type> <service class 1>
<service class 1 params>... <service class n) <service class n params>


A very simple example of controlled load service class can be found in 
test-suite-intserv.tcl.

This support can be tested by saying something like:
% ns tcl/ex/test-suite-intserv.tcl ADC=MS EST=TimeWindow
utilization_=0.95 SM=5e3

which would run the test-suite for measured sum admission control 
with a time-window estimator. The remaining command line params above are 
specific to the measured-sum algorithm.
