i (software development kit) - welcome to freescale

© Motorola, Inc., 2002. All rights reserved.

Embedded SDK(Software Development Kit)

V.21 Library

SDK133/DRev. 1, 07/25/2002

Fre

esc

ale

Se

mic

on

du

cto

r, I

Freescale Semiconductor, Inc.

For More Information On This Product, Go to: www.freescale.com

nc

...

ARCHIVED BY FREESCALE SEMICONDUCTOR, INC. 2005A

RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Table of Contents i

About This Document

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixOrganization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixSuggested Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixConventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xDefinitions, Acronyms, and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xReferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1Introduction

1.1 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-11.2 Overview of V.21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-11.2.1 Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-21.2.2 Features and Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

Chapter 2Directory Structure

2.1 Required Core Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12.2 Optional (Domain-Specific) Directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2

Chapter 3V.21 Library Interfaces

3.1 V.21 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13.2 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13.3 Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-63.3.1 v21Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-73.3.2 V21Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-133.3.3 v21TxProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-173.3.4 v21RxProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-183.3.5 v21Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-193.3.6 v21Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20

Chapter 4Building the V.21 Library

4.1 Building the V.21 Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14.1.1 Dependency Build. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14.1.2 Direct Build. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2

Contents

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

ii V.21 Library MOTOROLA

Chapter 5Linking Applications with V.21 Library

5.1 V.21 Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-15.1.1 Library Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-1

Chapter 6V.21 Applications

6.1 Test and Demo Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-1

Chapter 7License

7.1 Limited Use License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA List of Tables iii

Table 1-1 Frequencies Used in V.21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Table 3-1 v21Create Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

Table 3-2 v21Init Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13

Table 3-3 Description of the Fields of v21Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14

Table 3-4 v21TxProcess Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17

Table 3-5 v21RxProcess Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18

Table 3-6 v21Control Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19

Table 3-7 v21Destroy Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20

List of Tables

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

iv V.21 Library MOTOROLA

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA List of Figures v

Figure 2-1 Core Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Figure 2-2 DSP56824 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Figure 2-3 v21 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Figure 4-1 Dependency Build for the V.21 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Figure 4-2 v21.mcp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Figure 4-3 Execute Make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

List of Figures

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

vi V.21 Library MOTOROLA

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA List of Examples vii

Code Example 3-1 C Header File v21.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Code Example 3-2 Use of mem Library in v21Create function . . . . . . . . . . . . . . . . . . . . . . 3-7

Code Example 3-3 Use of v21Create Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Code Example 3-4 Sample Callback Procedure for V.21 Transmitter . . . . . . . . . . . . . . . . 3-15

Code Example 3-5 Sample Callback Procedure for V.21 Receiver . . . . . . . . . . . . . . . . . . 3-16

Code Example 5-1 linker.cmd File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

List of Examples

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

viii V.21 Library MOTOROLA

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Preface ix

About This DocumentThis manual describes the V.21 algorithm for use with Motorola’s Embedded Software Development Kit (SDK).

AudienceThis document targets software developers implementing the V.21 function within software applications.

OrganizationThis manual is arranged in the following sections:

• Chapter 1, Introduction—provides a brief overview of this document• Chapter 2, Directory Structure—provides a description of the required core directories• Chapter 3, V.21 Library Interfaces—describes all of the V.21 Library functions• Chapter 4, Building the V.21 Library—tells how to execute the system library project build• Chapter 5, Linking Applications with V.21 Library—describes organization of the V.21 Library• Chapter 6, V.21 Applications—describes the use of V.21 Library through test and demo

applications• Chapter 7, License—provides the license required to use this product

Suggested ReadingWe recommend that you have a copy of the following references:

• DSP56800 Family Manual, DSP56800FM/AD• DSP568xx User’s Manual for the DSP device being implemented• Inside CodeWarrior: Core Tools, Metrowerks Corp.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

x V.21 Library MOTOROLA

ConventionsThis document uses the following notational conventions:

Definitions, Acronyms, and AbbreviationsThe following list defines the acronyms and abbreviations used in this document. As this template develops, this list will be generated from the document. As we develop more group resources, these acronyms will be easily defined from a common acronym dictionary. Please note that while the acronyms are in solid caps, terms in the definition should be initial capped ONLY IF they are trademarked names or proper nouns

Typeface, Symbol or Term

Meaning Examples

Courier Monospaced Type

Code examples //Process command for line flash

Italic Directory names, project names, calls, functions, statements, procedures, routines, arguments, file names, applications, variables, directives, code snippets in text

...and contains these core directories:applications contains applications software...

...CodeWarrior project, 3des.mcp is...

...the pConfig argument....

...defined in the C header file, aec.h....

Bold Reference sources, paths, emphasis

...refer to the Targeting DSP56F80x Platform manual.......see: C:\Program Files\Motorola\Embedded SDK\help\tutorials

Blue Text Linkable on-line ...refer to Chapter 7, License....

Number Any number is consid-ered a positive value, unless preceded by a minus symbol to signify a negative value

3V-10

DES-1

ALL CAPITAL LETTERS

# defines/defined constants

# define INCLUDE_STACK_CHECK

Brackets [...] Function keys ...by pressing function key [F7]

Quotation marks, “...”

Returned messages ...the message, “Test Passed” is displayed....

...if unsuccessful for any reason, it will return “NULL”...

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Preface xi

CPFSK Continuous Phase Frequency Shift Keying

DSP Digital Signal Processor or Digital Signal Processing

I/O Input/Output

LSB Least Significant Bit

MIPS Million Instructions Per Second

MSB Most Significant Bit

OnCE™ On-Chip Emulation

OMR Operating Mode Register

Rx Receiver

SDK Software Development Kit

SRC Source

Tx Transmitter

V.21 ITU-T V.21 Recommendation

ReferencesThe following sources were referenced to produce this book:

1. DSP56800 Family Manual, DSP56800FM/AD2. DSP568xx User’s Manual, DSP56F801-7UM/D3. Embedded SDK Programmer’s Guide, SDK101/D4. ITU-T V.21: 300bps duplex modem standardized for use in the general switched telephone

network

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

xii V.21 Library MOTOROLA

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Introduction 1-1

Chapter 1Introduction

Welcome to Motorola’s Family of Digital Signal Processors (DSPs). This document describes the ITUT -V.21 Library (a 300bps duplex modem), which is a part of Motorola’s comprehensive SoftwareDevelopment Kit (SDK) for its DSPs. In this document, you will find all the information required to useand maintain the V.21 Library interface and algorithms.

Motorola provides these algorithms to you for use on the Motorola Digital Signal Processors to expediteyour application development and reduce the time it takes to bring your own products to market.

Motorola’s V.21 Library is licensed for your use on Motorola processors. Please refer to the standardSoftware License Agreement in Chapter 7 for license terms and conditions; please consult with yourMotorola representative for premium product licensing.

1.1 Quick StartMotorola Embedded SDK is targeted to a large variety of hardware platforms. To take full advantage of aparticular hardware platform, use Quick Start from the Targeting DSP568xx Platform documentation.

For example, the Targeting DSP56824 Platform manual provides more specific information andexamples about this hardware architecture. If you are developing an application for the DSP56824EVMboard or any other DSP56824 development system, refer to the Targeting DSP56824 Platform manualfor Quick Start or any other information specific to the DSP56824.

1.2 Overview of V.21V.21 is a 300bps duplex modem for use in the general switched telephone network. The V.21 uses a binarymodulation obtained by frequency shift, resulting in a modulation rate equal to the data signaling rate (i.e.,baud rate = bit rate). Since V.21 is a duplex modem, each unit has two channels, one for transmission andone for reception. The frequencies at which the channels work are shown in Table 1-1. The V.21 libraryworks at a 7200Hz sampling rate.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

1-2 V.21 Library MOTOROLA

Introduction

1.2.1 BackgroundEven high-end modems like V.90 might require a fallback to lower data-rate modes (e.g., 300bps, 75bps).V.21 provides a solution to this requirement by allowing a data rate of 300bps.

1.2.2 Features and PerformanceThe V.21 library is multichannel and re-entrant.

For details on Memory and MIPS for a particular DSP, refer to the Libraries chapter of the appropriateTargeting manual.

Table 1-1. Frequencies Used in V.21

Channel No.

Nominal Mean Frequency

Mark Frequency

Zero Frequency

1 1080Hz 980Hz 1180Hz

2 1750Hz 1650Hz 1850Hz

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Directory Structure 2-1

Chapter 2Directory Structure

2.1 Required Core DirectoriesFigure 2-1 details required platform directories:

Figure 2-1. Core Directories

As shown in Figure 2-1, DSP56824EVM has no operating system (nos) support and contains these coredirectories:

• applications contains applications software that can be exercised on this platform• bsp contains the board support package specific for this platform• config contains default hardware and software configurations for this platform• include contains SDK header files which define the Application Programming Interface• sys contains required system components• tools contains utilities used by system components

There are also optional directories that include domain-specific libraries.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


Directory Structure

2.2 Optional (Domain-Specific) DirectoriesFigure 2-2 demonstrates how the V.21 algorithm is encapsulated in the domain-specific directories underthe directory modem.

Figure 2-2. DSP56824 Directories

The modem directory includes modem-specific algorithms. Figure 2-3 shows the v21 directory structureunder the modem directory.

Figure 2-3. v21 Directory Structure

The v21 directory includes the following sub-directories:

• api_sources contains APIs for V.21• asm_sources includes asm sources required for V.21• c_sources includes c_sources required for V.21• test includes C source files and configuration necessary for testing V.21 library modules

— c_sources contains example test code for both digital and analog loopback tests for V.21— configextram contains the configuration files appconfig.c, appconfig.h and linker.cmd specific

to V.21

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA V.21 Library Interfaces 3-1

Chapter 3V.21 Library Interfaces

3.1 V.21 ServicesThe V.21 library supports modem functionality through two services: Modulation and Demodulation. The data to be supplied must be in 16-bit word, fixed-point (1.15) format, as shown below:

i = information bit

s = sign bit

3.2 InterfaceThe C interface for the V.21 library services is defined in the C header file v21.h, shown in Code Example 3-1 as a reference.

Code Example 3-1. C Header File v21.h

#ifndef __V21_H

#define __V21_H

#include "v21_typedef.h"

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

Foundational Include Files

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

#include "port.h"

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

Kind of station

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

sMSB

i i i i i i i i i i i i i i iLSB

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


V.21 Library Interfaces

/* To be used by the user to configure V21 of

* his end as either Call modem or answering

* modem. Please refer to v21_loopback.c for more

* details.

*/

#define V21_CALL_MODEM 0

#define V21_ANS_MODEM 1

#define V21_LOOPBACK_ENABLE 1 /* Indicates that loopback mode is enabled */

#define V21_LOOPBACK_DISABLE 0 /* Indicates that loopback mode is disabled */

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

Flags

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

/* Bit positions for flags */

#define V21_LOOPBACK 0x0001 /* Flag for Loop-back Enable/disable */

#define V21_DIGITAL_LOOPBACK 0x0002 /* Flag for digital loopback */

#define V21_ANALOG_LOOPBACK 0x0004 /* Flag for analog loopback */

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

Return values from v21Process() function

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

#define V21_TX_FREE 1 /* Says, tx. is free to transmit

* next data */

#define V21_RX_PASS 2 /* Says, rx. has passed */

#define V21_RX_CARRIER_FOUND 3 /* Indicates carrier is found at

* the receiver */

#define V21_TX_BUSY -1 /* Indicates, tx. is busy

* transmitting data */

#define V21_RX_CARRIER_LOST -2 /* Indicates loss of carrier at

* the receiver */

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

Structures for V21

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

/* Receiver callback structure */

typedef struct

{

void (*pCallback) (void *pCallbackArg,

char *pByte,

UWord16 NumberBytes);

void *pCallbackArg;

} v21_sRXCallback;

/* Transmitter callback structure */

typedef struct

{

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Interface


void (*pCallback) (void *pCallbackArg,

Word16 *pSamples,

UWord16 NumberSamples);

void *pCallbackArg;

} v21_sTXCallback;

/* User configurable structure. This is the format

* in which the user can pass the parameters to V.21

* library. Please see the test file v21_loopback.c

* for more details.

*/

typedef struct

{

UWord16 v21Flag; /* V21 flag */

UWord16 Station; /* Station type */

Word16 Gain; /* Transmission gain */

v21_sTXCallback TxCallback; /* Tx. Callback structure */

v21_sRXCallback RxCallback; /* Rx. Callback structure */

} v21_sConfigure;

/* V21 handle structure. This is strictly for V.21

* internal use only.

*/

typedef struct

{

Word16 tx_sinetable_len; /* Length of sine table (tx) */

Word16 tx_sinetable_ptr; /* Sine table pointer (tx) */

Word16 index_inc1; /* Offset in sine table for bit 1 */

Word16 index_inc0; /* Offset in sine table for bit 0 */

Word16 rx_sinetable_len; /* Length of sine table (rx) */

Word16 rx_sinetable_ptr; /* Sine table pointer (rx) */

Word16 *p_fs_rl_buf; /* Real part of demodulation by e^jw */

Word16 *p_fs_im_buf; /* Im. part of demodulation by e^jw */

Word16 *p_lpfout_rl_buf; /* Real part of LPF */

Word16 *p_lpfout_im_buf; /* Im. part of LPF */

Word16 *p_lpfst_rl_buf; /* Circular buffer, LPF state-realpart */

Word16 *p_lpfst_im_buf; /* Circular buffer, LPF state-im. part */

Word16 lpfst_rl_buf_ptr; /* LPF state pointer (real part) */

Word16 lpfst_im_buf_ptr; /* LPF state pointer (im. part) */

Word16 *p_divout_buf; /* Divider output */

Word16 *p_avgout_buf; /* Circular buffer, Avg. filter o/p */

Word16 decision_buf[2]; /* Decision buffer, decoder o/p */

Word16 zero_cross_index; /* Distance of zero cross from sampling ptr */

Word16 zero_cross_ptr; /* Zero cross pointer */

Word16 sampling_ptr; /* Sampling pointer */

Word16 tau; /* Interpolated value */

Word16 first_zero_cross; /* First zero cross flag */

Word16 cos_index;

Word16 sine_index;

Word16 avgout_buf_ptr; /* Pointer to avgout_buf buffer */

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



Word16 v21_cdflag; /* Carrier detect flag */

Word16 v21_rxctr; /* Rx. counter */

Word16 v21_rxstchg; /* Rx state change */

Word16 v21_rxstid; /* Rx. state ID */

Word16 *p_v21_rxq; /* Rx. Q buffer */

Word16 v21_rxq_ptr; /* Pointer to Rx. Q */

Word16 v21_rxsti_ptr; /* Pointer to Rx. initial state */

Word16 v21_agcg; /* AGC gain */

Word16 v21_acenergy[2]; /* Accumulated energy over different bauds */

Word16 baud_enrg[2]; /* Energy over a baud */

Word16 *p_samples_buf_ptr; /* Pointer to samples’ buffer */

FLAGS v21_flags; /* V21 flags */

Word16 v21_rx_decision_length;

/* Decision length (max = 2) */

Word16 v21_rxdemod_bits; /* Demodulated bits */

UWord16 v21Flag; /* V21 flag */

UWord16 Station; /* Station type */

Word16 Gain; /* Transmission gain */

UWord16 fcTx; /* Nominal carrier freq. for Tx. of

* a station */

UWord16 fcRx; /* Nominal carrier freq. for Rx. of

* the same station */

Word16 BitCounterTx; /* Bit counter to count bits in a

byte, in V21 Tx. */

Word16 BitCounterRx; /* Bit counter to count bits in a

byte, in V21 Rx. */

Word16 ByteCounterTx; /* Byte counter to count the number

of user supplied bytes */

UWord16 CountStatusTx; /* Keeps track of bit and byte

counters */

Word16 CpFskSamples[24]; /* CPFSK samples buffer */

Word16 ContextBufRx[24]; /* Context buffer */

Word16 ContextLen; /* Context length (<=24) */

Word16 MsgByteRx; /* Demodulated byte */

Word16 StatusFlagRx; /* Receiver status flag */

Word16 syncFlag; /* Flag used to register first carrier

* detection and first zero cross */

Word16 skipFlag; /* Flag to get the first pre-amble 0x7e */

v21_sTXCallback *pTxCallback; /* Tx. Callback structure */

v21_sRXCallback *pRxCallback; /* Rx. Callback structure */

} v21_sHandle;

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

Function Prototypes

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

EXPORT v21_sHandle *v21Create (v21_sConfigure *pConfig);

EXPORT void v21Init (v21_sHandle *pV21, v21_sConfigure *pConfig);

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Interface


EXPORT Result v21TxProcess (v21_sHandle *pV21,

char *pBytes,

UWord16 NumBytes);

EXPORT Result v21RxProcess (v21_sHandle *pV21,

Word16 *pSamples,

UWord16 NumSamples);

EXPORT Result v21Control (v21_sHandle *pV21, UWord16 Command);

EXPORT void v21Destroy (v21_sHandle *pV21);

#endif

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



3.3 SpecificationsThe following pages describe the V.21 library functions.

Function arguments for each routine are described as in, out, or inout. An in argument means that the parameter value is an input only to the function. An out argument means that the parameter value is an output only from the function. An inout argument means that a parameter value is an input to the function, but the same parameter is also an output from the function.

Typically, inout parameters are input pointer variables in which the caller passes the address of a preallocated data structure to a function. The function stores its results within that data structure. The actual value of the inout pointer parameter is not changed.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


3.3.1 v21Create Call(s):

v21_sHandle *v21Create (v21_sConfigure *pConfig);

Required Header: v21.h

Arguments:

Table 3-1. v21Create Arguments

Description: The v21Create function creates an instance of V.21, then initializes it by calling the v21Init function. During the v21Create call, any dynamic resources required by the V.21 algorithm are allocated. The V.21 library is multichannel and re-entrant.

The memory allocations are:

External Memory: 248 words per channel

Internal Memory: 0 words

The pConfig argument points to the v21_sConfigure structure used to configure V.21 operation; for details about this structure, see Section 3.3.2.

The v21Create function allocates memory dynamically using the mem library routines as shown in Code Example 3-2.

Code Example 3-2. Use of mem Library in v21Create function

#include "v21.h"

#include "v21_api.h"

#include "mem.h"

v21_sHandle *v21Create (v21_sConfigure *pConfig)

{

v21_sHandle *pV21;

/* Allocate memory for Handle structure */

pV21 = (v21_sHandle *) memMallocEM (sizeof (v21_sHandle));

if (pV21 == NULL) return (NULL);

/* Allocate memory for Tx Callback structure */

pV21->pTxCallback = (v21_sTXCallback *) memMallocEM (sizeof (v21_sTXCallback));

/* Allocate memory for Rx Callback structure */

pV21->pRxCallback = (v21_sRXCallback *) memMallocEM (sizeof (v21_sRXCallback));

/* Allocate linear memory for demodulator output (real and imaginary) */

pV21->p_fs_rl_buf = (Word16 *) memMallocEM (V21_SAMPLES_PER_BAUD * sizeof (Word16));

/* Allocate circular memory for LPF states */

pV21->p_lpfst_rl_buf = (Word16 *) memMallocAlignedEM (V21_LPF_ST_SIZE * sizeof (Word16));

pConfig in Points to the configuration data for V.21

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



pV21->p_fs_im_buf = (Word16 *) memMallocEM (V21_SAMPLES_PER_BAUD * sizeof (Word16));

/* Allocate linear memory for LPF output (real and imaginary) */

pV21->p_lpfout_rl_buf = (Word16 *) memMallocEM (V21_LPF_SIZE * sizeof (Word16));

pV21->p_lpfout_im_buf = (Word16 *) memMallocEM (V21_LPF_SIZE * sizeof (Word16));

/* Allocate linear memory for divider output */

pV21->p_divout_buf = (Word16 *) memMallocEM (V21_DIV_SIZE * sizeof (Word16));

/* Allocate linear memory for divider output */

pV21->p_v21_rxq = (Word16 *) memMallocEM (V21_RXQ_SIZE * sizeof (Word16));

pV21->p_lpfst_im_buf = (Word16 *) memMallocAlignedEM (V21_LPF_ST_SIZE * sizeof (Word16));

/* Allocate circular memory for division buffer */

pV21->p_avgout_buf = (Word16 *) memMallocAlignedEM (V21_AVGOUT_BUF_SIZE * sizeof (Word16));

/* Initialize V.21 instance */

v21Init (pV21, pConfig);

return (pV21);

}

For details on the v21_sHandle structure and constants used in Code Example 3-2, please refer to Code Example 3-2.

If the v21Create function is called to create an instance, then v21Destroy (see Section 3.3.6) should be used to destroy the instance.

Alternatively, the user can allocate memory statically, which requires duplicating all statements in the v21Create function. In this case, the user can call the v21Init function directly, bypassing the v21Create function. If the user dynamically allocates memory without calling the v21Create function, then the user himself must destroy the memory allocated.

Returns: Upon successful completion, the v21Create function will return a pointer to the specific instance of V.21created. If v21Create is unsuccessful for any reason, it will return “NULL”.

Special Considerations:

• The V.21 library is multichannel and re-entrant• If v21Create is called, then the user need not call the v21Init function, which is called internally in

the v21create function

In Code Example 3-3, the application creates an instance of V.21.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


Code Example 3-3. Use of v21Create Interface

NOTE: The example below illustrates both Digital and Analog loopback tests.

#include "stdio.h"

#include "assert.h"

/* Tool’s include */

#include "test.h"

/* V.21 library related include file */

#include "v21.h"

/* Codec related header files */

#include "codec.h"

#include "bsp.h"

/* Some #defines used here */

#define NUM_SAMPLES 24 /* NOTE: Number of samples per baud, at 7200Hz sampling rate

and 300 bps data rate, is 24. The receiver will

malfunction if this is anything other than 24 due

to sync/phase error. */

#define NUM_CHARS 21 /* Number of characters to be transmitted is 21 - 3 = 18. The 3

extra characters correspond to starting and ending

characters. See the NOTE below for testVector regarding

these 3 extra characters. */

/* Function prototypes */

void v21Loopback ();

void TxCallback (void *pCallbackArg, Word16 *pSamples, UWord16 NumberSamples);

void RxCallback (void *pCallbackArg, char *pChars, UWord16 NumberChars);

/* Variable declaration */

char testVector[NUM_CHARS] = { /* Characters to be transmitted */

0x7e, 0x7e, 0xfe, 0xff,

0x7e, 0xff, 0xab, 0x01,

0x02, 0x34, 0x56, 0x78,

0x9a, 0xbc, 0xde, 0xf0,

0x1f, 0x2e, 0x3d, 0x4c,

0x7e}; /* NOTE: The number of characters (actual data) to be

transmitted are only 18. The two extra characters (0x7e)

in the beginning has to be sent to establish the sync.

The last extra character (0x7e) is the ending character

to say that data transfer is over. */

/* NOTE: The structure of type WriteOutputTrn below is given here for illustration

* purposes only. The structure is to be decided by the user (who must write this

* kind of test file) depending on the callback function. This example assumes that the

* callback function just copies the output given by the V21 library to the

* “buffer” in the structure below. */

typedef struct /* An example structure for storing the output */

{

char buffer[NUM_CHARS];

UWord16 offset;

} WriteOutput;

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



/* Codec TX & RX buffers and variables */

Word16 CodecTxBuffer[NUM_SAMPLES]; /* Samples generated by the transmitter */

Word16 CodecRxBuffer[NUM_SAMPLES]; /* Samples for the receiver */

Word16 Codec;

void v21Loopback ()

{

v21_sHandle *pV21;

v21_sConfigure Config;

Result resTx, resRx;

Int16 charCount;

WriteOutput DemodOut;

int i, loopback;

test_sRec testRec;

/* Codec structure */

codec_sParams CodecParams;

UWord16 num_words;

/* Codec initialization */

Codec = open (BSP_DEVICE_NAME_CODEC_0, O_RDWR);

CodecParams.Buffer.Size = 2 * NUM_SAMPLES;

CodecParams.Buffer.Threshold = 0;

ioctl (Codec, CODEC_DEVICE_RESET, (void *) &CodecParams);

testStart (&testRec, "Testing V21 ...");

/* The following for-loop runs for V21_DIGITAL_LOOPBACK and

* V21_ANALOG_LOOPBACK */

for (loopback = 2; loopback < 8; loopback <<= 1)

{

if (loopback == V21_DIGITAL_LOOPBACK)

{

testComment (&testRec, "Testing V21 for Digital Loopback ...");

}

else if (loopback == V21_ANALOG_LOOPBACK)

{

testComment (&testRec, "Testing V21 for Analog Loopback ...");

}

else

{

testFailed (&testRec, "Invalid loopback option");

return;

}

DemodOut.offset = 0;

/* Set-up the configuration structure */

Config.v21Flag = V21_LOOPBACK_ENABLE + loopback;

Config.Station = V21_CALL_MODEM;

Config.Gain = 0x01ff;

Config.TxCallback.pCallback = TxCallback;

Config.TxCallback.pCallbackArg = NULL;

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


Config.RxCallback.pCallback = RxCallback;

Config.RxCallback.pCallbackArg = (WriteOutput *) &DemodOut;

/* Create V.21 instance and initialize it */

pV21 = v21Create (&Config);

if (pV21 == NULL) assert (!"Out of memory");

/* Start V.21 process. */

resTx = V21_TX_BUSY;

while (resTx == V21_TX_BUSY)

{

resTx = v21TxProcess (pV21, testVector, NUM_CHARS);

if (resTx == V21_TX_FREE) break;

/* Read from codec. */

/* Counter to count the number of samples received */

num_words = 0;

/* Collect NUM_SAMPLES samples */

do

{

num_words += read (Codec, (CodecRxBuffer + num_words),

NUM_SAMPLES - num_words);

} while (num_words < NUM_SAMPLES);

/* If digital loopback, copy Tx. buffer to Rx. buffer */

if ((pV21->v21Flag & V21_DIGITAL_LOOPBACK) ==

V21_DIGITAL_LOOPBACK)

{

for (i = 0; i < NUM_SAMPLES; i++)

{

CodecRxBuffer[i] = CodecTxBuffer[i];

}

}

/* Process the received samples */

resRx = v21RxProcess (pV21, CodecRxBuffer, NUM_SAMPLES);

if (resRx == V21_RX_CARRIER_LOST) break;

}

archDisableInt (); /* Disable the codec interrupt */

close (Codec);

if (resRx == V21_RX_CARRIER_LOST)

{

testFailed (&testRec, "Carrier Lost");

testEnd (&testRec);

v21Destroy (pV21);

return;

}

/* Compare the results. The valid data characters are

* only the first (NUM_CHARS-3) characters in DemodOut.buffer */

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



for (i = 0; i < NUM_CHARS-3; i++)

{

if (DemodOut.buffer[i] != testVector[2+i])

{

if ((pV21->v21Flag & V21_DIGITAL_LOOPBACK) ==

V21_DIGITAL_LOOPBACK)

{

testFailed (&testRec, "V.21 Digital Loopback Failed");

}

else if ((pV21->v21Flag & V21_ANALOG_LOOPBACK) ==

V21_ANALOG_LOOPBACK)

{

testFailed (&testRec, "V.21 Analog Loopback Failed");

}

else

{

testFailed (&testRec, "Invalid loopback option");

}

testEnd (&testRec);

v21Destroy (pV21);

return;

}

}

/* Just make the elements of output buffer zeros */

for (i = 0; i < NUM_CHARS; i++)

{

DemodOut.buffer[i] = 0;

}

if ((pV21->v21Flag & V21_DIGITAL_LOOPBACK) == V21_DIGITAL_LOOPBACK)

{

testComment (&testRec, "V.21 Digital Loopback Passed\n");

v21Destroy (pV21);

}

else if ((pV21->v21Flag & V21_ANALOG_LOOPBACK) == V21_ANALOG_LOOPBACK)

{

testComment (&testRec, "V.21 Analog Loopback Passed\n");

v21Destroy (pV21);

}

}

testEnd (&testRec);

return;

}

For details on structures used in Code Example 3-3, see Code Example 3-1.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


3.3.2 V21Init Call(s):

void v21Init (v21_sHandle *pV21, v21_sConfigure *pConfig);


Arguments:

Table 3-2. v21Init Arguments

Description: The v21Init function initializes the V.21 algorithm and verifies that the pointers in pConfig point to valid memory blocks (i.e., if a pointer is required to be on an aligned boundary, this function will verify that the pointer actually is on an aligned boundary). During initialization, each resource will be set to its initial values in preparation for V.21 operation. Before calling the v21Init function, a V.21 instance must be created. The V.21 instance (pV21) can be created either by calling the v21Create function (see Section 3.3.1) or by statically allocating memory, which does not require a call to the v21Create function.

The parameter pConfig points to a data structure of type v21_sConfigure; its fields initialize V.21 operation in the following manner:

v21Flag - The bits of v21Flag are shown below. The numbers inside the box indicate the bitnumber.

pV21 in Handle to an instance of V.21

pConfig in A pointer to a data structure containing data for initializing the V.21 algorithm

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 (LSB)

V21_LOOPBACK

V21_DIGITAL_LOOPBACK

V21_ANALOG_LOOPBACK

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



Station - Indicates the kind of station. This variable can take any one of the following values:

V21_CALL_MODEM - Indicates that the modem under consideration is the initiating modem

V21_ANS_MODEM - Indicates that the modem under consideration is the responding modem

Gain - Indicates transmitter gain. Value can range from 0x0000 to 0x7fff. Note that the gain is represented in 1.15 fixed-point format. For instance, 0x7fff represents 1 - 2-15 = 0.9999695.

TxCallback - A structure of type v21_sTxCallback; it describes the procedure which V.21 will call once a sufficient number of samples are ready for transmission. V.21 Transmitter does callback once 24 samples are ready for transmission. The callback procedure has the following declaration:

void (*pCallback) (void *pCallbackArg, Word16 *pSamples,UWord16 NumberSamples);

The callback procedure parameter, pCallbackArg, is supplied by the user in the v21_sTxCallback structure; this value is passed back to the user during the call to the callback procedure. Typically, pCallbackArg points to context information used by the callback procedure, which the user must write.

pSamples points to the buffer containing V.21 modulated samples (at a 7200Hz sampling rate) for transmission. The samples are in 1.15 fixed-point format.

NumberSamples indicate the number of samples to be transmitted, pointed to by pSamples.

Table 3-3. Description of the Fields of v21Flag

Bit Name Bit Status Description

V21_LOOPBACK set Indicates that loopback mode isenabled and the test can be foreither digital or analog loopback.(If this bit is reset, it indicates thatloopback mode is disabled).

The following constants can beused to enable or disable theloopback:• V21_LOOPBACK_ENABLE• V21_LOOPBACK_DISABLE

V21_DIGITAL_LOOPBACK set Indicates that digital loopbackmode is enabled

V21_ANALOG_LOOPBACK set Indicates that analog loopback

mode is enabled1

1. V21_DIGITAL_LOOPBACK or V21_ANALOG_LOOPBACK can be set only after settingV21_LOOPBACK

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


A sample callback procedure for V.21 Transmitter is shown in Code Example 3-4 for reference. You must write your own callback procedure. This callback procedure writes the samples given by the transmitter to the codec.

Code Example 3-4. Sample Callback Procedure for V.21 Transmitter

void TxCallback (void *pCallbackArg, Word16 *pSamples, UWord16 NumberSamples)

{

Word16 i;

/* Make a copy of the samples to be transmitted */

for (i = 0; i < NumberSamples; i++)

{

CodecTxBuffer[i] = pSamples[i];

}

/* Write the samples to be transmitted into codec buffer */

write (Codec, CodecTxBuffer, NumberSamples);

return;

}

Code Example 3-4 is an example of the callback function to the samples given by the v21TxProcess function (Transmitter) of the V.21 library. This callback function must be written by the user. The transmitter gives 24 samples through callback, which should be collected by the user. In this example, samples pointed to by pSamples are copied into CodecTxBuffer, and then written into the codec.

RxCallback - A structure of type v21_sRxCallback; it describes the procedure which V.21 will call once every character is received. The callback procedure has the following declaration:

void (*pCallback) (void *pCallbackArg, char *pByte,UWord16 NumberBytes);

The callback procedure parameter, pCallbackArg, is supplied by the user in the v21_sRxCallback structure; this value is passed back to the user during the call to the callback procedure. Typically, pCallbackArg points to context information used by the callback procedure, which the user must write.

pByte points to the buffer containing received characters. The received characters are in the same format as that at the transmitter.

NumberBytes indicate the number of received characters pointed to by pByte.

A sample callback procedure for the Receiver is shown in Code Example 3-5 for reference.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



Code Example 3-5. Sample Callback Procedure for V.21 Receiver

void RxCallback (void *pCallbackArg, char *pChars, UWord16 NumberBytes)

{

Int16 i;

WriteOutput *temp = (WriteOutput *) pCallbackArg;

for (i = 0; i < NumberBytes; i++)

{

temp->buffer[i + (temp->offset)] = pChars[i];

}

temp->offset += NumberBytes;

return;

}

Code Example 3-5 is an example of the callback function, which collects the output given by the v21RxProcess function (Receiver) of the V.21 library. This callback function must be written by the user. Every time the callback is made, the receiver gives one demodulated byte, which should be collected by the user. This example illustrates just one of the simple ways of collecting these outputs. The received bytes are stored in a buffer, which is a member of the WriteOutput-type structure (defined in Code Example 3-3). The “offset” keeps track of the location from which the next entry is to be made into the buffer.

Returns: None


• The v21Init function need not be called if the v21Create function is used to create the V.21 instance, because the v21Create function internally calls the v21Init function to initialize V.21

Code Example: See Code Example 3-3 to learn how to use the v21Init function.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


3.3.3 v21TxProcess Call(s):

Result v21TxProcess (v21_sHandle *pV21, char *pBytes, UWord16 NumBytes);


Arguments:

Table 3-4. v21TxProcess Arguments

Description: The v21TxProcess function processes characters to generate the CPFSK samples to be transmitted. The user must call the v21TxProcess function in a loop until the “V21_TX_FREE” flag is returned from the v21TxProcess function.

Returns: These are the return values:

• “V21_TX_BUSY” indicates that the transmitter is still transmitting data• “V21_TX_FREE” indicates that the transmitter has transmitted data


• Until the “V21_TX_FREE” flag is received from v21TxProcess, the transmitter v21TxProcess must be called without disturbing the buffer pointed to by pBytes

• Note that the Transmitter cannot be called alone; the Receiver must be called after calling the Transmitter. See Code Example 3-3 for information on calling Transmitter and Receiver.

• The user must transmit the sync pattern of 0x7e at least twice before sending any data. Code Example 3-3 explains how to do this. Also, one ending character of 0x7e must be sent after sending all the data characters.

Code Example: See Code Example 3-3 to learn how to use the v21TxProcess function.


pBytes in Pointer to characters to be transmitted

NumBytes in The number of characters to be transmitted

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



3.3.4 v21RxProcess Call(s):

Result v21RxProcess (v21_sHandle *pV21, Word16 *pSamples, UWord16 NumSamples);


Arguments:

Table 3-5. v21RxProcess Arguments

Description: The v21RxProcess function will demodulate the received signal and return the characters transmitted at the transmitter. The user must call the v21RxProcess function after the v21TxProcess function.

Returns: These are the return values:

• “V21_RX_CARRIER_LOST” indicates loss of carrier• “V21_RX_PASS” indicates that the receiver has passed


• The receiver v21RxProcess function can process only 24 samples at a time. If 24 samples are not supplied, there will be a sync or phase error, resulting in inaccurate demodulation. In other words, demodulation is accurate if there is a corresponding received sample in the relevant buffer for every sample transmitted.

• The V21_RX_CARRIER_LOST error makes sense only when the carrier has been detected before it’s lost

• The receiver first looks for the 0x7e pattern and only then goes into data-reception mode

Code Example: See Code Example 3-3 to learn how to use the v21RxProcess function.


Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Specifications


3.3.5 v21Control Call(s):

Result v21Control (v21_sHandle *pV21, UWord16 Command);


Arguments:

Table 3-6. v21Control Arguments

Description: Reserved for future use

Returns: None

Special Considerations: None

pV21 in Handle to an instance of V.21 generated by a call to v21Create

Command in Command for controlling V.21

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005



3.3.6 v21Destroy Call(s):

void v21Destroy (v21_sHandle *pV21);


Arguments:

Table 3-7. v21Destroy Arguments

Description: The v21Destroy function destroys the instance of V.21 originally created by a call to v21Create. If the user bypassed the v21Create function to create an instance on his own, the v21Destroy function should not be called.

Returns: None

Special Considerations: None

Code Example: See Code Example 3-3 to learn how to use the v21Destroy function.

pV21 in Handle to an instance of V.21 generated by a call to v21Create

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Building the V.21 Library 4-1

Chapter 4Building the V.21 Library

4.1 Building the V.21 LibraryThe V.21 library combines all of the components described in the previous chapter into one library:v21.lib. To build this library, a Metrowerks CodeWarrior project, v21.mcp, is provided. This project and allthe necessary components to build the V.21 library are located in the ...\nos\modem\v21 directory of theSDK directory structure.

There are two methods to execute a system library project build: dependency build and direct build.

4.1.1 Dependency BuildDependency build is the easiest approach and requires no additional work on the user’s part. If you add theV.21 library project, v21.mcp, to your application project, as shown in Figure 4-1, the V.21 library willautomatically build when the application is built.

Figure 4-1. Dependency Build for the V.21 Project

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


Building the V.21 Library

4.1.2 Direct BuildDirect build allows you to build the V.21 library independently of any other build. Follow these steps:

Step 1. Open the v21.mcp project, as shown in Figure 4-2.

Figure 4-2. v21.mcp Project

Step 2. Execute the build by pressing function key [F7] or by choosing the Make command from theProject menu; see Figure 4-3.

Figure 4-3. Execute Make

At this point, if the build is successful, the v21.lib library file is created in the ...\nos\modem\v21\Debugdirectory.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Linking Applications with V.21 Library 5-1

Chapter 5Linking Applications with V.21 Library

5.1 V.21 LibraryThe library includes APIs, which define the interface between the user application and the V.21 modules.To invoke V.21, APIs must be called in this order:

— v21Create (.......);— v2Init (.......);— v21TxProcess (.......);— v21RxProcess (.......);— v21Destroy (.......);

5.1.1 Library SectionsThe V.21 Library contains only one section for code, called “rtlib”. The data ROM sections are v21_xrom,v21_xrom1, and v21_xrom2.

See Code Example 5-1 for an example linker.cmd file used in the test application.

Code Example 5-1. linker.cmd File

# Linker.cmd file for DSP56824EVM External RAM# using both internal and external data memory (EX = 0)# and using external program memory (Mode = 3)

#*******************************************************************************MEMORY {

.pInterruptVector (RWX) : ORIGIN = 0x0000, LENGTH = 0x002C

.pExtRAM (RWX) : ORIGIN = 0x002C, LENGTH = 0xFFD4

.xAvailable (RW) : ORIGIN = 0x0000, LENGTH = 0x0030

.xCWRegisters (RW) : ORIGIN = 0x0030, LENGTH = 0x0010

.xIntRAM_DynamicMem1 (RW) : ORIGIN = 0x0040, LENGTH = 0x07C0

.xIntROM (R) : ORIGIN = 0x0800, LENGTH = 0x0800

.xIntRAM_DynamicMem2 (RW) : ORIGIN = 0x1000, LENGTH = 0x0600

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


Linking Applications with V.21 Library

.xHole (R) : ORIGIN = 0x1600, LENGTH = 0x0A00

.xExtRAM (RW) : ORIGIN = 0x2000, LENGTH = 0xC000

.xExtRAM_DynamicMem (RW) : ORIGIN = 0xE000, LENGTH = 0x1000

.xStack (RW) : ORIGIN = 0xF000, LENGTH = 0x0F80

.xPeripherals1 (RW) : ORIGIN = 0xFF80, LENGTH = 0x0040

.xPeripherals2 (RW) : ORIGIN = 0xFFC0, LENGTH = 0x0040 }#*******************************************************************************

FORCE_ACTIVE {FconfigInterruptVector}

SECTIONS {

#*******************************************************************************## Data (X) Memory Layout#_EX_BIT = 0;

# Internal Memory Partitions (for mem.h partitions)_NUM_IM_PARTITIONS = 2; # .xIntRAM_DynamicMem1 and .xIntRAM_DynamicMem2

# External Memory Partition (for mem.h partitions)_NUM_EM_PARTITIONS = 1; # .xExtRAM_DynamicMem

#*******************************************************************************.ApplicationInterruptVector :{

vector.c (.text)

} > .pInterruptVector#*******************************************************************************

.ApplicationCode :{

# Place all code into External Program RAM

* (.text)* (rtlib.text)* (fp_engine.text)* (user.text)

} > .pExtRAM

#*******************************************************************************

.ApplicationData :{

# Define variables for C initialization code

F_Xdata_start_addr_in_ROM = ADDR(.xIntROM) + SIZEOF(.xIntROM) / 2;F_StackAddr = ADDR(.xStack);F_StackEndAddr = ADDR(.xStack) + SIZEOF(.xStack) / 2 - 1;F_Xdata_start_addr_in_RAM = .;

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

V.21 Library

MOTOROLA Linking Applications with V.21 Library 5-3

# Define variables for SDK mem library

FmemEXbit = .;WRITEH(_EX_BIT);

FmemNumIMpartitions = .;WRITEH(_NUM_IM_PARTITIONS);

FmemNumEMpartitions = .;WRITEH(_NUM_EM_PARTITIONS);

FmemIMpartitionList = .;WRITEH(ADDR(.xIntRAM_DynamicMem1));WRITEH(SIZEOF(.xIntRAM_DynamicMem1) / 2);WRITEH(ADDR(.xIntRAM_DynamicMem2));WRITEH(SIZEOF(.xIntRAM_DynamicMem2) / 2);

FmemEMpartitionList = .;WRITEH(ADDR(.xExtRAM_DynamicMem));WRITEH(SIZEOF(.xExtRAM_DynamicMem) /2);

# Place all data into External RAM

* (.data)* (fp_state.data)* (rtlib.data)

# V21 data ROM sections start here#---------------------------------

* (v21_xrom.data)

.=ALIGN(256);* (v21_xrom1.data)

.=ALIGN(512);* (v21_xrom2.data)

# V21 data ROM sections end here#-----------------------------

F_Xdata_ROMtoRAM_length = 0;

F_bss_start_addr = .;_BSS_ADDR = .;

* (rtlib.bss.lo)* (.bss)

F_bss_length = . - _BSS_ADDR; # Copy DATA

} > .xExtRAM#*******************************************************************************

FArchIO = ADDR(.xPeripherals2);}

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


Linking Applications with V.21 Library

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA V.21 Applications 6-1

Chapter 6V.21 Applications

6.1 Test and Demo ApplicationsTo verify the V.21 algorithm, test and demo applications have been developed. Refer to the Targeting Motorola DSP568xx Platform manual for the DSP you are using to see if the test and demo applications are available for your target.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


V.21 Applications

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA License 7-1

Chapter 7License

7.1 Limited Use License AgreementLIMITED USE LICENSE AGREEMENT

PLEASE READ THIS AGREEMENT CAREFULLY BEFORE USING THIS SOFTWARE. BY USINGOR COPYING THE SOFTWARE, YOU AGREE TO THE TERMS OF THIS AGREEMENT.

The software in either source code form ("Source") or object code form ("Object") (cumulativelyhereinafter "Software") is provided under a license agreement ("Agreement") as described herein. Any useof the Software including copying, modifying, or installing the Software so that it is usable by oraccessible by a central processing unit constitutes acceptance of the terms of the Agreement by the personor persons making such use or, if employed, the employer thereof ("Licensee") and if employed, theperson(s) making such use hereby warrants that they have the authority of their employer to enter thislicense agreement,. If Licensee does not agree with and accept the terms of this Agreement, Licensee mustreturn or destroy any media containing the Software or materials related thereto, and destroy all copies ofthe Software.

The Software is licensed to Licensee by Motorola Incorporated ("Motorola") for use under the terms of thisAgreement. Motorola retains ownership of the Software. Motorola grants only the rights specificallygranted in this Agreement and grants no other rights. Title to the Software, all copies thereof and all rightstherein, including all rights in any intellectual property including patents, copyrights, and trade secretsapplicable thereto, shall remain vested in Motorola.

For the Source, Motorola grants Licensee a personal, non-exclusive, non-assignable, revocable,royalty-free right to use, copy, and make derivatives of the Source solely in a development systemenvironment in order to produce object code solely for operating on a Motorola semiconductor devicehaving a central processing unit ("Derivative Object").

For the Object and Derivative Object, Motorola grants Licensee a personal, non-exclusive, non-assignable,revocable, royalty-free right to copy, use, and distribute the Object and the Derivative Object solely foroperating on a Motorola semiconductor device having a central processing unit.

Licensee agrees to: (a) not use, modify, or copy the Software except as expressly provided herein, (b) notdistribute, disclose, transfer, sell, assign, rent, lease, or otherwise make available the Software, anyderivatives thereof, or this license to a third party except as expressly provided herein, (c) not removeobliterate, or otherwise defeat any copyright, trademark, patent or proprietary notices, related to theSoftware (d) not in any form export, re-export, resell, ship or divert or cause to be exported, re-exported,resold, shipped, or diverted, directly or indirectly, the Software or a direct product thereof to any countrywhich the United States government or any agency thereof at the time of export or re-export requires anexport license or other government approval without first obtaining such license or approval.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005


License

THE SOFTWARE IS PROVIDED ON AN "AS IS" BASIS AND WITHOUT WARRANTY OF ANYKIND INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF MERCHANTABILITY ORFITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MOTOROLA BE LIABLE FORANY LIABILITY OR DAMAGES OF ANY KIND INCLUDING, WITHOUT LIMITATION, DIRECTOR INDIRECT OR INCIDENTAL OR CONSEQUENTIAL OR PUNITIVE DAMAGES OR LOSTPROFITS OR LOSS OF USE ARISING FROM USE OF THE SOFTWARE OR THE PRODUCTREGARDLESS OF THE FORM OF ACTION OR THEORY OF LIABILITY (INCLUDING WITHOUTLIMITATION, ACTION IN CONTRACT, NEGLIGENCE, OR PRODUCT LIABILITY) EVEN IFMOTOROLA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THISDISCLAIMER OF WARRANTY EXTENDS TO LICENSEE OR USERS OF PRODUCTS AND IS INLIEU OF ALL WARRANTIES WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDINGIMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR PARTICULAR PURPOSE.

Motorola does not represent or warrant that the Software is free of infringement of any third party patents,copyrights, trade secrets, or other intellectual property rights or that Motorola has the right to grant thelicenses contained herein. Motorola does not represent or warrant that the Software is free of defect, orthat it meets any particular requirements or need of the Licensee, or that it conforms to any documentation,or that it meets any standards.

Motorola shall not be responsible to maintain the Software, provide upgrades to the Software, or provideany field service of the Software. Motorola reserves the right to make changes to the Software withoutfurther notice to Licensee.

The Software is not designed, intended, or authorized for use as components in systems intended forsurgical implant into the body, or other applications intended to support or sustain life, or for any otherapplication in which the failure of the Software could create a situation where personal injury or death mayoccur. Should Licensee purchase or use the Software for any such unintended or unauthorized application,Licensee shall indemnify and hold Motorola and its officers, employees, subsidiaries, affiliates, anddistributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arisingout of, directly or indirectly, any claim of personal injury or death associated with such unintended orunauthorized use, even if such claim alleges that Motorola was negligent regarding the design ormanufacture of the Software.

The term of this Agreement is for as long as Licensee uses the Software for its intended purpose and is notin default of any provisions of this Agreement. Motorola may terminate this Agreement if Licensee is indefault of any of the terms and conditions of this Agreement.

This Agreement shall be governed by and construed in accordance with the laws of the State of Arizonaand can only be modified in a writing signed by both parties. Licensee agrees to jurisdiction and venue inthe State of Arizona.

By using, modifying, installing, compiling, or copying the Software, Licensee acknowledges that thisAgreement has been read and understood and agrees to be bound by its terms and conditions. Licenseeagrees that this Agreement is the complete and exclusive statement of the agreement between Licensee andMotorola and supersedes any earlier proposal or prior arrangement, whether oral or written, and any othercommunications relative to the subject matter of this Agreement.

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA Index i

B

Background 1-2

C

Continuous Phase Frequency Shift KeyingCPFSK xi

CPFSK xi

D

Digital Signal ProcessorDSP xi

DSP xiDSP56800 Family Manual xiDSP56F80x User’s Manual xi

E

Embedded SDK Programmer’s Guide xi

F

Features and Performance 1-2

I

I/O xiInput/Output

I/O xiITU-T V.21 Recommendation xi

V.21 xi

L

Least Significant BitLSB xi

linker.cmd File 5-1LSB xi

M

Million Instructions Per SecondMIPS xi

MIPS xiMost Significant Bit

MSB xiMSB xi

O

OMR xiOnCE xiOn-Chip Emulation

OnCE xiOperating Mode Register

OMR xiOverview of VRLITE-1 1-1

R

ReceiverRx xi

Rx xi

S

SDK xiSoftware Development Kit

SDK xiSource

SRC xiSRC xi

T

TransmitterTx xi

Tx xi

V

V.21 xi

Index

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

ii V.21 Library MOTOROLA

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

MOTOROLA and the Stylized M Logo are registered in the US Patent & Trademark Office. All other product or service names are the property of their

respective owners. © Motorola, Inc. 2002.

How to reach us:USA/EUROPE/Locations Not Listed: Motorola Literature Distribution; P.O. Box 5405, Denver, Colorado 80217. 1–303–675–2140 or 1–800–441–2447

JAPAN: Motorola Japan Ltd.; SPS, Technical Information Center, 3–20–1, Minami–Azabu. Minato–ku, Tokyo 106–8573 Japan. 81–3–3440–3569

ASIA/PACIFIC: Motorola Semiconductors H.K. Ltd.; Silicon Harbour Centre, 2 Dai King Street, Tai Po Industrial Estate, Tai Po, N.T., Hong Kong. 852–26668334

Technical Information Center: 1–800–521–6274

HOME PAGE: http://www.motorola.com/semiconductors/

Motorola reserves the right to make changes without further notice to any products herein. Motorola makes no warranty, representation or guarantee regarding thesuitability of its products for any particular purpose, nor does Motorola assume any liability arising out of the application or use of any product or circuit, andspecifically disclaims any and all liability, including without limitation consequential or incidental damages. “Typical” parameters which may be provided in Motoroladata sheets and/or specifications can and do vary in different applications and actual performance may vary over time. All operating parameters, including“Typicals” must be validated for each customer application by customer’s technical experts. Motorola does not convey any license under its patent rights nor therights of others. Motorola products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or otherapplications intended to support or sustain life, or for any other application in which the failure of the Motorola product could create a situation where personal injuryor death may occur. Should Buyer purchase or use Motorola products for any such unintended or unauthorized application, Buyer shall indemnify and hold Motorolaand its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney feesarising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges thatMotorola was negligent regarding the design or manufacture of the part. Motorola and the Stylized M Logo are registered trademarks of Motorola, Inc. Motorola,Inc. is an Equal Opportunity/Affirmative Action Employer.

SDK133/D

Fre

esc

ale

Se

mic

on

du

cto

r, I



nc

...


RC

HIV

ED

BY

FR

EE

SC

AL

E S

EM

ICO

ND

UC

TOR

, IN

C. 2

005

i (software development kit) - welcome to freescale

Documents