Read Me

================================================================================
NOTE, only Gilbert-Elliott (GE) model and Specified Loss Sequence (SLS) model 
are working on FreeBSD-8.0 now. I will implement other models and port to other
version of FreeBSD if I get chance.

						-Ji Li update on 10/19/2011
================================================================================

* Installation

1. Install FreeBSD-8.0 Release with full source tree installed
2. Copy the following files in svn repository to your source tree (backup first 
   if needed):
	dnpktloss/src/freebsd/8.0-Release/usr/src/sys/netinet/ipfw/ip_dummynet.c -> /usr/src/sys/netinet/ipfw/ip_dummynet.c
	dnpktloss/src/freebsd/8.0-Release/usr/src/sys/netinet/ip_dummynet.h -> /usr/src/sys/netinet/ip_dummynet.h
	dnpktloss/src/freebsd/8.0-Release/usr/src/sbin/ipfw/dummynet.c -> /usr/src/sbin/ipfw/dummynet.c
	dnpktloss/src/freebsd/8.0-Release/usr/src/sbin/ipfw/ipfw2.c -> /usr/src/sbin/ipfw/ipfw2.c
	dnpktloss/src/freebsd/8.0-Release/usr/src/sbin/ipfw/ipfw2.h -> /usr/src/sbin/ipfw/ipfw2.h
3. Copy /usr/src/sys/netinet/ip_dummynet.h to /usr/include/netinet/ip_dummnet.h 
   or make a symbolic link, in order to compile objects under /usr/src/sbin/ipfw/.
   Also, make a symbolic link /usr/src/sbin/ipfw/dnburstyloss.h by doing
	ln -s path_to_dnpktloss/src/dnburstyloss/dnburstyloss.h /usr/src/sbin/ipfw/
4. Create a folder outside of your svn working copy for building dnburstyloss.ko 
   (This may not be necessary, just to keep working copy clean)
	cd ~; mkdir dnpktloss_build; cd dnpktloss_build; 
	ln -s path_to_dnpktloss/src/dnburstyloss/Makefile .
	ln -s path_to_dnpktloss/src/dnburstyloss/dnburstyloss.c .
	ln -s path_to_dnpktloss/src/dnburstyloss/dnburstyloss.h .

* Rebuild kernel modules and user land program 

(Don't forget backup your original binary files, if needed.)

5. Rebuild ipfw.ko kernel module and install
	cd /usr/src/sys/modules/ipfw; make && sudo make install
6. Rebuild dummynet.ko kernel module and install
	cd /usr/src/sys/modules/dummynet; make && sudo make install
7. Rebuild ipfw user land program and install
	cd /usr/src/sbin/ipfw; make && sudo make install

* Build dnburstyloss module and load it

8. Build dnburstyloss.ko 
	cd ~/dnpktloss_build/ ; make
9. Load dnpktloss module after loading ipfw.ko and dummynet.ko
	sudo kldload ./dnburstyloss.ko

* Configure loss module with certain dummynet pipe
  
10. Write your own loss module pipe profile by referring to those under dnpktloss/install/example
  and configure certain pipe with that moduel by running ipfw.
  e.g.	ipfw pipe 1 config plm ./ge_profile
  Also, you can modify path_to_dnpktloss/install/example/plm_set_dn and run that script.

==============================================
Loss Model Description:


I. Gilbert-Elliott model 
In GE model, there are two states: GOOD and BAD
GOOD state has much lower packet loss rate than BAD state does, 
i.e. p_g << p_b. Model can transition from GOOD to BAD with prob
of p_g2b, or from BAD to GOOD with prob of p_b2g. 

 struct plm_parms_ge {
         int p_g2b, p_b2g;       /* state transition probability */
         int p_g, p_b;           /* pkt loss probability in Good/Bad, p_g<<p_b */
 };
 

II. Gilbert-Elliott model with multiple states
GEMS model is en extension of GE model by increasing state number
from 2 to more. Likewise, each state has independant packet drop rate,
and the model could transition from any state to any other one, with
prob controlled by a two dimension matrix p_tr[][].

 struct plm_parms_gems {
         unsigned int nstate;    /* the size of state space, <= GE_MAX */
 #define GEMS_MAX        4       /* maximum num of states supported */
         int p_tr[GEMS_MAX][GEMS_MAX];   /* state transition probability matrix */
         int p_loss[GEMS_MAX];   /* packet loss probability of each state*/
 
 };
 
 
III. k-th order (two-state i.e. loss or not) Markov Chain Model. 
 We convert it to first-order Markov Chain with 2^k states. e.g. for 3rd order
 model, we transfer it to first-order Chain with 8 states. State 0x010 reprents 
 that the 2nd latest packet was lost, the latest and the 3rd lastest were not.
 Conditional probabilities of P{drop current pkt | previous state is n} for 
 any n: 0~2^k -1 are stored in p_tr[2^k]. They also state transition 
 probabilities.

 struct plm_parms_kmc {
         unsigned int k;         /* order */
 #define KMC_MAX         4       /* maximum num of states supported */
 #define KMC_SIZE        (1 << KMC_MAX)  /* size of conditional prob array */
         int p_tr[KMC_SIZE];     /* contional prob of state transition */
 };


IV. Specified Loss Sequence (SLS) model.
With this model, you can specify a number, i.e. sequence, in whose binary
format "1" indicates loss, "0" means no loss. We start from its highest bit 
to examine the incoming packets and then move on towards lowest bit, until it
hits its lowest bit or mask_boundary. Then repeat it over.

 struct plm_parms_sls {
         uint64_t loss_seq;
         uint64_t mask_boundary; /* seq_len is translated to mask_boundary. */
                                 /* it can range from 0x800000000000 to 0x1. */
 #define SEQ_LEN_MAX     (sizeof(uint64_t) * 8)
 #define SEQ_LEN_MIN     1       
 };