/*******************************************************************************

  OPENAIRINTERFACE 0/1/2/3 
  Copyright(c) 1999 - 2011 EURECOM

  This program is free software; you can redistribute it and/or modify it
  under the terms and conditions of the GNU General Public License,
  version 2, as published by the Free Software Foundation.

  This program is distributed in the hope 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.

  The full GNU General Public License is included in this distribution in
  the file called "COPYING".

  Contact Information:
  Openair Admin <openair_admin@eurecom.fr>
  Mailing List <openair_tech@eurecom.fr>
  Forums  http://forums.eurecom.fr/openairinterface
  Eurecom, 2229, route des cretes, 06560 Valbonne Sophia Antipolis, France

*******************************************************************************/
/*________________________OEPNAIR/OPENAIR0/________________________

 File    : readme.txt 
 Authors : Baris Demiray
 Company : EURECOM
 Emails  : baris.demiray@eurecom.fr
________________________________________________________________*/


-----------------
Table of contents
-----------------

The content of this readme is the following: 

  1) What is this block about in OpenAirInterface
  2) Folders and files description
  3) Organization of the folders and their dependancies
  4) Makefile targets and how to build
  4.1) NUMBER_OF_TEST_PACKETS
  4.2) WINDOW_SIZE
  4.3) TEST_RX_AND_TX_WINDOW
  4.4) TEST_PDCP_DATA_REQUEST_AND_INDICATION
  5) Compilation and running
  6) How to use through a tutorial: run a simple experimentation

------------------------------------------------
1) What is this block about in OpenAirInterface?
------------------------------------------------

Code residing here is the test code for PDCP, particularly the 
sequence numbering code, pdcp_data_req(), and pdcp_data_ind().

Sequence numbering code is at pdcp_sequence_number.{c|h}, pdcp_data_req()
and pdcp_data_ind() methods are in pdcp.{c|h}, all residing in PDCP_v10.1.0
directory at openair2/LAYER2/.

Normally, PDCP layer is in interaction with following layers,


     +-----------+       +-----+
     | IP Driver |       | RRC |
     +-----------+       +-----+
                \        /
                +--------+
                |  PDCP  |
                +--------+
                     |
                  +-----+
                  | RRC |
                  +-----+

But in this test PDCP is isolated (by the symbolic constant 
PDCP_UNIT_TEST, defined in LAYER2/PDCP_v10.1.0/pdcp.h) from the rest of the 
layers and tested on its own.

There are two different tests. First is for sequence numbers and the other is 
for PDUs and relevant headers.

All the sections referred herein should be looked in 3GPP TS 36.323 V10.1.0
(2011-03).

--------------------------------
2) Folders and files description
--------------------------------

    File/Folder           Description
    -----------           -----------

    - Makefile            Build targets are `all` and `clean`     
    - test_pdcp.{c|h}     Test code
    - test_util.h         Utility methods for debugging
    - todo.txt            Todo list
    - with_rlc/           Test code to validate interface between PDCP and RLC
                          (written by Lionel)

-----------------------------------------------------
3) Organization of the folders and their dependancies
-----------------------------------------------------

There is only one subfolder named `with_rlc/` and it has no dependency with 
other test code and has its own Makefile.

-------------------------------------
4)  Makefile targets and how to build
-------------------------------------

There is only one build target named `build_test_pdcp` and it can be run 
also through the target `all`.

To configure, there is a number of symbolic constants in test_pdcp.c.

---------------------------
4.1) NUMBER_OF_TEST_PACKETS
---------------------------

NUMBER_OF_TEST_PACKETS configures the number of packets that are to be 
generated during the tests. For TX/RX window tests this is directly the 
number of sequence numbers generated. For SDU test this constant determines
the number of packets passed to pdcp_data_req() (by test_pdcp_data_req()).
Then PDUs generated by PDCP are collected in a linked list and passed to 
pdcp_data_ind() (by test_pdcp_data_ind()) for validation.

This value is currently set to 10000.

----------------
4.2) WINDOW_SIZE
----------------

This symbolic constant configures TX and RX window size.

Currently this value is set to 4096 in accordance with the size of sequence
number field (12 bits, see 6.2.3).

--------------------------
4.3) TEST_RX_AND_TX_WINDOW
--------------------------

Currently PDCP tests are performed either for TX/RX window or for PDUs 
because PDCP states are not reset inbetween two tests. If this constant is
defined then only TX/RX tests are performed generating NUMBER_OF_TEST_PACKETS
packets.

Warning: If this and TEST_PDCP_DATA_REQUEST_AND_INDICATION are both defined 
then secondly run test will fail.

------------------------------------------
4.4) TEST_PDCP_DATA_REQUEST_AND_INDICATION
------------------------------------------

Currently PDCP tests are performed either for TX/RX window or for PDUs 
because PDCP states are not reset inbetween two tests. If this constant is 
defined then only PDU test is performed generating NUMBER_OF_TEST_PACKETS
packets.

Warning: If this and TEST_RX_AND_TX_WINDOW are both defined then secondly run
test will fail.

--------------------------
5) Compilation and running
--------------------------

Since default target is `all` following command suffices,

$ make

To run,

$ ./test_pdcp

---------------------------------------------------------------
6)  How to use through a tutorial: run a simple experimentation
---------------------------------------------------------------

Not applicable, see section 5.