\chapter{PLM}{\sloppy\label{sec:PLM}This chapter describes the ns  implementation of the PLM protocol\cite{legout_sigmetrics2000}. The code of the PLM protocol  is written in both C++ and OTcl. The PLM Packet Pair generator iswritten in C++ and the PLM core machinery is written in OTcl. The chapter has simplythree parts: the first part shows how to create and configure a PLM session; thesecond part describes the Packet Pair source generator; the third part describesthe architecture and internals of the PLM protocol. In this last part, ratherthan giving a list of procedures and functions, we introduce the mainprocedures per functionality (instantiation of a PLM source, instantiation of aPLM receiver, reception of a packet, detection of a loss, etc.).The procedures, functions, and variables described in this chapter can be found in:\nsf{plm/cbr-traffic-PP.cc}, \nsf{plm/loss-monitor-plm.cc}, \nsf{tcl/plm/plm.tcl},\nsf{tcl/plm/plm-ns.tcl}, \nsf{tcl/plm/plm-topo.tcl}, \nsf{tcl/lib/ns-default.tcl}.\section{Configuration}\label{sec:Configuration}\paragraph{Creating a simple scenario with one PLM flow (only one receiver)\\}This simple example can be run as is (several complex scenarios can be found inthe file \nsf{tcl/ex/simple-plm.tcl}).\begin{program}  set packetSize 500                          \;Packet size (in bytes);  set plm_debug_flag 2                        \;Debugging output;  set rates "50e3 50e3 50e3 50e3 50e3"        \;Rate of each layer;  set rates_cum [calc_cum $rates]       \;Cumulated rate of the layers (mandatory);  set level [llength $rates]            \;Number of layers (mandatory);    set Queue_sched_ FQ                         \;Scheduling of the queues;  set PP_burst_length 2                       \;PP burst length (in packets);  set PP_estimation_length 3                  \;Minimum number of PP required to make an estimate;  Class Scenario0 -superclass PLMTopology  Scenario0 instproc init args \{    eval $self next $args    $self instvar ns node        $self build_link 1 2 100ms 256Kb           \;Build a link;    set addr(1) [$self place_source 1 3]      \;Set a PLM source;    $self place_receiver 2 $addr(1) 5 1       \;Set a PLM receiver;    {\cf #set up the multicast routing}    DM set PruneTimeout 1000                  \;A large PruneTimeout value is required;    set mproto DM    set mrthandle [$ns mrtproto $mproto \{\} ]    \}  set ns [new Simulator -multicast on]            \;PLM needs multicast routing;  $ns multicast  $ns namtrace-all [open out.nam w]               \;Nam output;  set scn [new Scenario0 $ns]                     \;Call of the scenario;  $ns at 20 "exit 0"  $ns run\end{program}Several variables are introduced in this example. They all need to be set in thesimulation script (there is no default value for these variables). In particularthe two following lines  are mandatory and must not be omitted:\begin{program}  set rates_cum [calc_cum $rates]  set level [llength $rates]\end{program}We describe now in detail each variable:\begin{description}\item[\tt packetSize] represents the size of the packets in bytes sent by the PLM  source. \item [\tt plm\_debug\_flag] represents the verbose level of debugging output: from 0 no  output to 3 full output. For \code{plm_debug_flag} set to 3 (full output), long  lines output are   generated which is not compatible with nam visualization. \item [\tt rates] is a list specifying  the bandwidth of each layer (this is not the cumulated bandwidth!). \item [\tt rates\_cum] is a list specifying the cumulated bandwidth of the  layers: the first element of \code{rates_cum} is the bandwidth a layer 1, the  second element of \code{rates_cum} is the sum of the bandwidth of layer 1 and  layer 2, etc. The proc \proc{calc\_cum} computes the cumulated rates. \item [\tt level] is the number of layers. \item [\tt Queue\_sched\_] represents the scheduling of the queues. This is used by the  PLMTopology instproc \code{build_link}. PLM requires FQ scheduling or a  variation. \item [\tt PP\_burst\_length] represents the size of the Packet Pair bursts  in packets. \item [\tt PP\_estimation\_length] represents the minimum number of Packet  Pair required to compute an estimate (see  section~\ref{sec:PLMReception-Packet}). \end{description}All the simulations for PLM should be setup using the PLMTopology environment (asin the example script where we define a PLMTopology superclass called Scenario0). Theuser interface is (all the instproc can be found in \nsf{tcl/plm/plm-topo.tcl}):\begin{description}\item[\tt build\_link a b d bw] creates a duplex link between node  \code{a} and \code{b} with a delay \codeakcgaoe and a bandwidth \code{bw}. If  either node does not exist, \code{build_link} creates it.\item[\tt place\_source n t] creates and places a PLM source at node \code{n} and  starts it at time \code{t}. \code{place_source} returns \code{addr} which  allows to attach receivers to this source.\item[\tt place\_receiver n addr C nb] creates and places a PLM receiver at node  \code{n} and attached it to the source which return the address \code{addr}. The  check value for this PLM receiver is \code{C}. An optional parameter \code{nb}  allows to get an instance of the PLM receiver called \code{PLMrcvr($nb)}. This  instance is only useful to get some specific statistics about this receiver  (mainly the number of packets received or lost). %$\end{description}\section{The Packet Pair Source Generator}This section describes the Packet Pair source generator; the relevant files are:\nsf{plm/cbr-traffic-PP.cc}, \nsf{tcl/lib/ns-default.tcl}. The OTcl class name ofthe PP source is: Application/Traffic/CBR\_PP. The Packet Pair (PP) source generator is in the file\nsf{plm/cbr-traffic-PP.cc}. This source generator is a variation of the CBR source generator in \nsf{cbr\_traffic.cc}.We just describe the salient differences between the code ofthe CBR source and the code of the PP source. The default values in \nsf{tcl/lib/ns-default.tcl} for the PP source generator are the samethan for the CBR source. We need for the PP source generator a new parameter {\tt PBM\_}:\begin{program}Application/Traffic/CBR_PP set PBM_ 2 \;Default value;\end{program}The OTcl instvar bounded variable {\tt PBM\_} (same name in C++ and in OTcl)specifies the number of back-to-back packets to be sent. For {\tt PBM\_}=1 wehave a CBR source, for {\tt PBM\_}=2 we have a Packet Pair source (a source whichsends two packets back-to-back), etc. The mean rate of the PP source is\code{rate_}, but the packets are sent in burst of \code{PBM_} packets. Notethat we also use the terminology Packet Pair source and Packet Pair burst for{\tt PBM\_$>$2}.We compute the \code{next_interval} as:\begin{program}double CBR_PP_Traffic::next_interval(int& size){{\cf /*(PP_ - 1) is the  number of packets in the current burst.*/}        if (PP_ >= (PBM_ - 1)){                         interval_ = PBM_*(double)(size_ << 3)/(double)rate_;                PP_ = 0;        }        else {                interval_ = 1e-100; //zero                PP_ += 1 ;        }...}\end{program}The \proc{timeout} method puts the {\tt NEW\_BURST} flag in the first packet of aburst. This is useful for the PLM protocol to identify the beginning of a PPburst.\begin{program}  void CBR_PP_Traffic::timeout()  {    ...    if (PP_ == 0)       agent_->sendmsg(size_, "NEW_BURST");    else       agent_->sendmsg(size_);        ...    }\end{program}\section{Architecture of the PLM Protocol}The code of the PLM protocol is divided in three files: \nsf{tcl/plm/plm.tcl},which contains the PLM protocol machinery without any specific interface with\ns; \nsf{tcl/plm/plm-ns.tcl}, which contains the specific ns interface.However, we do not guarantee the strict validity of this ns interfacing;\nsf{tcl/plm/plm-topo.tcl}, which contains a user interface to build simulationscenarios with PLM flows. In the following we do not discuss the various procedures per object (forinstance all the instproc of the PLM class)  but rather per functionality (forinstance which instproc among the various classes are involved in the instantiationof a PLM receiver). For a given functionality, we do not describe in details allthe code involved, but we give the principal steps.