/*!
* \file usr_vp880
* \defgroup vp880_user_guide VP880 User Guide
* @{
*/

------------------------------------------------------------------------------
/*! \defgroup vp880_introduction Introduction
@{

The VP880 Call Control Software is a collection of various functional software blocks with different owners, as follows:

<table style="text-align: left; width: 640px" border="0" cellpadding="2" cellspacing="0">
<tr>
	<td style="background-color: rgb(213, 225, 232);"><b>Software Component</b></td>
	<td style="background-color: rgb(213, 225, 232);"><b>Owner</b></td>
	<td style="background-color: rgb(213, 225, 232);"><b>SiSP Component</b></td>
</tr>
<tr>
	<td style="vertical-align: top;">Linux Kernel</td>
	<td style="vertical-align: top;">Mindspeed</td>
	<td style="vertical-align: top;">Linux Board Support Package (SiSP)</td>
</tr>
<tr>
	<td style="vertical-align: top;">VAPI</td>
	<td style="vertical-align: top;">Mindspeed</td>
	<td style="vertical-align: top;">VAPI (SiSP)</td>
</tr>
<tr>
	<td style="vertical-align: top;">Comcerto Call Ctrl App</td>
	<td style="vertical-align: top;">Mindspeed</td>
	<td style="vertical-align: top;">VAPI (SiSP)</td>
</tr>
<tr>
	<td style="vertical-align: top;">API-II</td>
	<td style="vertical-align: top;">Zarlink</td>
	<td style="vertical-align: top;">Zarlink Package</td>
</tr>
</table>

@} */




------------------------------------------------------------------------------
/*! \defgroup vp880_callctrl Zarlink VP880 Call Control Software
@{

\section vp880_callctrl_1 Overview

The VP880 Call Control Software is a component of the Mindspeed Silicon Software Package (SiSP) and is targeted to provide a standard Call Control interface to any User applications while driving the following devices: 
-	Zarlink Timeslot Interchanger (or TSI)
-	Zarlink VP880 SLIC/SLAC
-	Zarlink TimeSlot Interchanger

\section vp880_callctrl_2 Zarlink Timeslot Interchanger
The Zarlink TSI device is a TDM matrix, mapping timeslots of different TDMs together.
On Mindspeed Comcerto EVMs, all TDMs are connected to the TSI, obviously the Comcerto TDMs and the VP880 SLIC/SLAC TDM.

The Comcerto VP880 Call Control software needs to configure the TSI to map, as required, timeslots of the Comcerto TDM to timeslots of the Zarlink SLIC/SLAC TDM.

\section vp880_callctrl_3 Zarlink VP880 SLIC/SLAC

VP880 refers to the family of Zarlink (former Legerity) devices labeled Le88xxx.
Mindspeed Comcerto EVMs are usually populated with two Le88231 or Le88276 SLIC/SLAC silicon.
VP880 SLIC/SLAC are mapped to RJ11 or POTS connectors.

\section vp880_callctrl_4 Comcerto EVMs

Mindspeed designed different kinds of Comcerto EVMs, populated with different SLIC/SLAC devices of the Zarlink VP880 family:
- Comcerto300-Narrowband EVM
  Those boards are populated with Le88231 SLIC/SLAC devices 
- Comcerto300-Wideband EVM
  Those boards are populated with Le88276 SLIC/SLAC devices

All Comcerto300 EVMs are populated with two VP880 SLIC/SLAC devices as follows:

<table style="text-align: left; width: 640px" border="0" cellpadding="2" cellspacing="0">
<tr>
	<td style="background-color: rgb(213, 225, 232);"><b>Zarlink Device</b></td>
	<td style="background-color: rgb(213, 225, 232);"><b>Board Reference</b></td>
	<td style="background-color: rgb(213, 225, 232);"><b>Mapped to TSI TDM#</b></td>
	<td style="background-color: rgb(213, 225, 232);"><b>Dual RJ11 Connector#</b></td>
</tr>
<tr>
	<td style="vertical-align: top;">Le88231 or Le88276</td>
	<td style="vertical-align: top;">U18</td>
	<td style="vertical-align: top;">TDM #7</td>
	<td style="vertical-align: top;">JSLIC0-1</td>
</tr>
<tr>
	<td style="vertical-align: top;">Le88231 or Le88276</td>
	<td style="vertical-align: top;">U15</td>
	<td style="vertical-align: top;">TDM #6</td>
	<td style="vertical-align: top;">JSLIC0-2</td>
</tr>
</table>

\section vp880_callctrl_5 Comcerto300 EVM Configuration

\subsection vp880_callctrl_5_1 TSI Mapping

When running on a Comcerto300 EVM, the Comcerto VP880 Call Control Software setups the TSI as described in the above graphic. Please note that this configuration applies for both Comcerto300-Narrowband and Comcerto300-Wideband EVMs. 

\image html c300evm_tsi_mapping.JPG
\image rtf c300evm_tsi_mapping.JPG

\subsection vp880_callctrl_5_2 Comcerto300-Narrowband Timeslot Mapping

Narrowband SLIC/SLAC devices requires 1 timeslot per POTS Line, as described in the enclosed graphic hence some of the mapped timeslots are not used in this configuration. 

\image html c300evm_narrowband_ch_ts_mapping.JPG
\image rtf c300evm_narrowband_ch_ts_mapping.JPG

\subsection vp880_callctrl_5_3 Comcerto300-Wideband EVM Mapping

In wideband mode, up to 4 timeslots are required per SLIC/SLAC line and therefore per Comcerto channel. Those timeslots are distributed as follows on the SLIC/SLACdevice:
-	2 timeslots for transmitting data
-	2 timeslots for receiving data

For Zarlink devices from the VP880 SLIC/SLAC family and used in widebamd mode, the programmed time slot must be in the lower half of the frame. At 8.192MHz, time slots 0-63 are programmable timeslots.
A second timeslot, half a frame delayed, will be automatically used for the second sample that is processed per 8kHz frame in wideband mode. 

If timeslot #0 is setup as a transmit timeslot on the Zarlink SLIC/SLAC device then timeslot #1 will be automatically used as transmit timeslot while timeslots 64 and 65 will be used as receive timeslots.
If timeslot #2 is setup as a transmit timeslot on the Zarlink SLIC/SLAC device then timeslot #3 will be automatically used as transmit timeslot while timeslots 66 and 67 will be used as receive timeslots.

\image html c300evm_wideband_ch_ts_mapping.JPG
\image rtf c300evm_wideband_ch_ts_mapping.JPG

@} */



------------------------------------------------------------------------------
/*! \defgroup vp880_build VP880 Build Procedure
@{

\section vp880_build_1 Automated Linux build using the OpenWrt distribution

Starting with SiSP L26.7.3, the SiSP package includes a new distribution called OpenWRT updated by Mindspeed to support the Comcerto300EVM and generate all Mindspeed binaries (including Zarlink VP880 Call Control binaries) from Mindspeed sources. This distribution automates the build procedure. For further details, please refer to the "M82xxx OpenWRT Guide" released by Mindspeed.

\section vp880_build_2 Manual Build 

Please follow the step-by-step process as follows: 

1.	Uncompress the Linux kernel sources and build the Linux kernel image:
	\code
	# tar -jxvf kernel-linux_2.6.22.19-4.05.1.tar.bz2
	# cd kernel-linux_2.6.22.19-4.05.1
	# make c300evm_defconfig && make
	\endcode

2.	Uncompress the Comcerto VP880 Sofware Package:
	\code
	# tar -jxvf vp880-call-ctrl-c300evm-2.06.0.tar.bz2
	\endcode

3.	Move to the created "vp880-call-ctrl-c300evm-2.06.0" folder:
	\code
	# cd vp880-callctrl-c300evm-2.06.0
	\endcode

4.	Move to the created "driver-Linux" folder:
	\code
	# cd vp880-callctrl-c300evm-2.06.0
	\endcode

5.	Edit the Makefile and fill out the Makefile options:
	\code
	# Full path to previously unpacked and configured kernel sources
	KERNEL_SOURCES  :=

	# Full path to the filesystem where the driver should be installed INSTALL_DIR ()
	# Enable/disable debug information at the kernel level 
	DEBUG := 

	# Enable/disable debug information at the kernel level
	TARGET_BOARD := 
	\endcode

6.	Save the Makefile changes and build the kernel module and legerity_app:
	\code
	# make
	\endcode
	This command will:
	-	Compile the Zarlink API-II Library
	-	Compile the Mindspeed Call Control Layer
	-	Generate a Linux kernel module called "legerity.ko" out of the Zarlink API-II Library and the Mindspeed Call Control Layer
	-	Compile and build the "legerity_app" application

@} */




------------------------------------------------------------------------------
/*! \defgroup vp880_install VP880 Install Procedure
@{

\section vp880_install_1 Automated Install using the OpenWRT distribution

Same as for the "Build Procedure", the VP880 Call Control software installation is fully automated when using the Mindspeed OpenWRT distribution. For further details, please refer to the "M82xxx OpenWRT Guide" released by Mindspeed.

\section vp880_install_2 Manual Install

Please follow the instructions:

1.	Install the Linux kernel module
	\code
	# make install
	\endcode
	This command will:
	-	Install the "legerity.ko" Linux kernel and "legerity_app" application into the filesystem
	-	Create the char device for I/O control operations

2.	Four new files are installed on the filesystem: 
	/dev/legerity
	/lib/modules/"kernel version"/extra/legerity.ko
   	/usr/local/bin/legerity_app
   	/etc/modprobe.d/legerity

3.	To complete the installation process, the following command should be executed from the embedded environment running on the Comcerto platform:
	\code
	# depmod -a
	\endcode
	From now on, the Linux kernel driver can be used

@} */



------------------------------------------------------------------------------
/*! \defgroup vp880_start VP880 Start Procedure
@{

\section vp880_start_1 Setup

\subsection vp880_start_1_1 Changing the driver module parameters

The Linux environment provides the Legerity-Mindspeed driver with parameter values set in
the /etc/modprobe.d/legerity file. Changing the option settings in this file will change the
driver's behavior. Once these parameters have been modified, the driver needs to be restarted.

\subsection vp880_start_1_2 Changing PCM encoding

Edit "/etc/modprobe.d/legerity" file to use :
	\code
	options legerity_pcm_encoding=1
	\endcode

This parameter can take 3 different values :
-	0 : The driver will use Alaw for PCM encoding.
-	1 : The driver will use Ulaw for PCM encoding
-	2 : The driver will use linear PCM encoding

\section vp880_start_2 Launch

\subsection vp880_start_2_1 Loading the kernel module

Prior to load the Legerity driver into Kernel space, make sure that the Legerity char file is created on your Linux PC as  follows:
	\code
	mknod /dev/legerity c 119 0
	chmod 666 /dev/legerity
	\endcode

The Linux kernel module can be loaded as follows:
	\code
	# modprobe legerity
	\endcode

The Linux kernel module can be unloaded as follows:
	\code
	# modprobe -r legerity
	\endcode

Note: Once loaded, the kernel module will start initializing the Zarlink API-II Library and then the Zarlink SLIC/SLAC devices available on the ComcertoEVM, which will fail if the expected TDM clock is not delivered to the SLIC/SLAC device. Please look to the "Getting Started" section for further details.

\subsection vp880_start_2_2 Running the legerity_app utility

The legerity_app application can only be used once the legerity driver kernel module has
been loaded. The application allows interacting with the legerity driver kernel module. It allows:
-	Reading from a legerity slic register
-	Writing to a legerity slic register
-	Launching line tests (only available if the driver has been compiled with the line_testing capability).

Look to the legerity_app capabilities as follows:
	\code
	# legerity_app --help
	\endcode

\subsection vp880_start_2_3 SLIC/SLAC Register Read

To read the value of a legerity slic register, the command sequence should be as follows:
	\code
	# legerity_app -s<register_size> -l<line_number> -r<register_number>
	\endcode

-	register_size : this field should match the number of bytes to be read from the register.
-	line_number : this field should match the phone connection that needs to be accessed.
-	register_number : this field should match the register number in hexadecimal value.

Example: To read 1 byte from the SLIC register 0x47 of the 3rd POTS:
	\code
	# legerity_app -s1 -l3 -r0x47
	\endcode

\subsection vp880_start_2_4 SLIC/SLAC Register Write

To write a given value to a legerity slic register, the command sequence should be as follows:
	\code
	# legerity_app -s<register_size> -b<bytes_to_write> -l<line_number> -w<register_number>
	\endcode

-	register_size : this field should match the number of bytes to be read from the register.
-	Bytes_to_write :List of bytes to be written into the specified register
-	line_number : this field should match the phone connection that needs to be accessed.
-	register_number : this field should match the register number in hexadecimal value.

Example: To write  2 bytes *0x12 and 0x32) into register 0x34 of the 3rd POTS:
	\code
	# legerity_app -s2 -b0x12,0x32 -l3 -w0x34
	\endcode

@} */


/*! @} */
