/*
 * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The OpenAirInterface Software Alliance licenses this file to You under
 * the OAI Public License, Version 1.1  (the "License"); you may not use this file
 * except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.openairinterface.org/?page_id=698
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *-------------------------------------------------------------------------------
 * For more information about the OpenAirInterface (OAI) Software Alliance:
 *      contact@openairinterface.org
 */

/*________________________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.

