Texas Instruments TMS320C64X User Manual

TMS320C64x+ DSP

Little-Endian DSP Library

Programmer’s Reference

Literature Number: SPRUEB8

February 2006

IMPORTANT NOTICE

Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All products are sold subject to TI’s terms and conditions of sale supplied at the time of order acknowledgment.

TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily performed.

TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards.

TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information published by TI regarding third-party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI.

Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation.

Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements.

Following are URLs where you can obtain information on other Texas Instruments products and application solutions:

Products		Applications
Amplifiers	amplifier.ti.com	Audio	www.ti.com/audio
Data Converters	dataconverter.ti.com	Automotive	www.ti.com/automotive
DSP	dsp.ti.com	Broadband	www.ti.com/broadband
Interface	interface.ti.com	Digital Control	www.ti.com/digitalcontrol
Logic	logic.ti.com	Military	www.ti.com/military
Power Mgmt	power.ti.com	Optical Networking	www.ti.com/opticalnetwork
Microcontrollers	microcontroller.ti.com	Security	www.ti.com/security
		Telephony	www.ti.com/telephony
		Video & Imaging	www.ti.com/video
		Wireless	www.ti.com/wireless
Mailing Address:	Texas Instruments
	Post Office Box 655303 Dallas, Texas 75265

Copyright ♥ 2006, Texas Instruments Incorporated

Preface

Read This First

About This Manual

This document describes the C64x+ digital signal processor little-endian (DSP) Library, or DSPLIB for short.

Notational Conventions

This document uses the following conventions:

-Hexadecimal numbers are shown with the suffix h. For example, the following number is 40 hexadecimal (decimal 64): 40h.

-Registers in this document are shown in figures and described in tables.

-Macro names are written in uppercase text; function names are written in lowercase.

J Each register figure shows a rectangle divded into fields that represent the fields of the register. Each field is labeled with its bit name, its beginning and ending bit numbers above, and its read/write properties below. A legend explains the notation used for the properties.

J Reserved bits in a register figure designate a bit that is used for future device expansion.

Related Documentation From Texas Instruments

The following books describe the C6000™ devices and related support tools. Copies of these documents are available on the Internet at www.ti.com. Tip: Enter the literature number in the search box provided at www.ti.com.

SPRU732 — TMS320C64x/C64x+ DSP CPU and Instruction Set Reference Guide. Describes the CPU architecture, pipeline, instruction set, and interrupts for the TMS320C64x and TMS320C64x+ digital signal processors (DSPs) of the TMS320C6000 DSP family. The C64x/C64x+ DSP generation comprises fixed-point devices in the C6000 DSP platform. The C64x+ DSP is an enhancement of the C64x DSP with added functionality and an expanded instruction set.

Read This First

i

Trademarks

SPRAA84 — TMS320C64x to TMS320C64+ CPU Migration Guide.

Describes migrating from the Texas Instruments TMS320C64x digital signal processor (DSP) to the TMS320C64x+ DSP. The objective of this document is to indicate differences between the two cores. Functionality in the devices that is identical is not included.

Trademarks

C6000, TMS320C64x+, TMS320C64x, C64x are trademarks of Texas Instruments.

ii

Contents

Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Provides a brief introduction to the TI C64x+ DSPLIBs, shows the organization of the routines contained in the libraries, and lists the features and benefits of the DSPLIBs.

1.1 Introduction to the TI C64x+ DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1.2 Features and Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

2 Installing and Using DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-1

Provides information on how to install and rebuild the TI C64x+ DSPLIB.

2.1 How to Install DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 2.2 Using DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.2.1 DSPLIB Arguments and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.2.2 Calling a DSPLIB Function From C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.2.3 Calling a DSP Function From Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.2.4 DSPLIB Testing − Allowable Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.2.5 DSPLIB Overflow and Scaling Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.2.6 Interrupt Behavior of DSPLIB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

2.3 How to Rebuild DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

3 DSPLIB Function Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-1

Provides tables containing all DSPLIB functions, a brief description of each, and a page reference for more detailed information.

3.1 Arguments and Conventions Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3.2 DSPLIB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 3.3 DSPLIB Function Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 3.4 Differences Between the C64x and C64x+ DSPLIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

4 DSPLIB Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Provides a list of the functions within the DSPLIB organized into functional categories.

4.1 Adaptive Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

4.2 Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

4.3 FFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

4.4 Filtering and Convolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38

4.5 Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-58

4.6 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-73

4.7 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-76

4.8 Obsolete Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-90

4.8.1 FFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-90

iii

Contents

A Performance/Fractional Q Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Describes performance considerations related to the C64x+ DSPLIB and provides information about the Q format used by DSPLIB functions.

A.1 Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

A.2 Fractional Q Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

A.2.1 Q3.12 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

A.2.2 Q.15 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

A.2.3 Q.31 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

B Software Updates and Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Provides information about warranty issues, software updates, and customer support.

B.1	DSPLIB Software Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	B-2
B.2	DSPLIB Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	B-2

C Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Defines terms and abbreviations used in this book.

iv

Tables

		Tables
2−1	DSPLIB Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . . 2-3
3−1	Argument Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . . 3-2
3−2	Adaptive Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-4
3−3	Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-4
3−4	FFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-4
3−5	Filtering and Convolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-5
3−6	Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-6
3−7	Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-6
3−8	Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-7
3−9	Obsolete Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-7
3−10	Functions Optimized in the C64x+ DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . 3-8
A−1	Q3.12 Bit Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . A-3
A−2	Q.15 Bit Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . A-3
A−3	Q.31 Low Memory Location Bit Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . A-4
A−4	Q.31 High Memory Location Bit Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . . . . . . . A-4

Contents v

vi

Chapter 1

Introduction

This chapter provides a brief introduction to the TI C64x+ DSP Libraries (DSPLIB), shows the organization of the routines contained in the library, and lists the features and benefits of the DSPLIB.

Topic		Page
1.1	Introduction to the TI C64x+ DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . .	. . 1-2
1.2	Features and Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . 1-4

1-1

Introduction to the TI C64x+ DSPLIB

1.1 Introduction to the TI C64x+ DSPLIB

The TI C64x+ DSPLIB is an optimized DSP Function Library for C programmers using devices that include the C64x+ megamodule. It includes many C-callable, assembly-optimized, general-purpose signal-processing routines. These routines are typically used in computationally intensive real-time applications where optimal execution speed is critical. By using these routines, you can achieve execution speeds considerably faster than equivalent code written in standard ANSI C language. In addition, by providing ready-to-use DSP functions, TI DSPLIB can significantly shorten your DSP application development time.

The TI DSPLIB includes commonly used DSP routines. Source code is provided that allows you to modify functions to match your specific needs.

The routines contained in the library are organized into the following seven different functional categories:

-Adaptive filtering

J DSP_firlms2

-Correlation

J DSP_autocor

J DSP_autocor_rA8

-FFT

J DSP_fft16x16

J DSP_fft16x16_imre J DSP_fft16x16r

J DSP_fft16x32 J DSP_fft32x32 J DSP_fft32x32s J DSP_ifft16x16

J DSP_ifft16x16_imre J DSP_ifft16x32

J DSP_ifft32x32

J DSP_fft16x16t (obolete, use DSP_fft16x16)

J DSP_bitrev_cplx (obsolete, use DSP_fft16x16) J DSP_radix 2 (obsolete, use DSP_fft16x16)

J DSP_r4fft (obsolete, use DSP_fft16x16) J DSP_fft (obsolete, use DSP_fft16x16)

1-2

Introduction to the TI C64x+ DSPLIB

-Filtering and convolution J DSP_fir_cplx

J DSP_fir_cplx_hM4X4 J DSP_fir_gen

J DSP_fir_gen_hM17_rA8X8 J DSP_fir_r4

J DSP_fir_r8

J DSP_fir_r8_hM16_rM8A8X8 J DSP_fir_sym

J DSP_iir

-Math

J DSP_dotp_sqr J DSP_dotprod J DSP_maxval J DSP_maxidx J DSP_minval J DSP_mul32 J DSP_neg32 J DSP_recip16

J DSP_vecsumsq J DSP_w_vec

-Matrix

J DSP_mat_mul J DSP_mat_trans

-Miscellaneous J DSP_bexp

J DSP_blk_eswap16 J DSP_blk_eswap32 J DSP_blk_eswap64 J DSP_blk_move

J DSP_fltoq15 J DSP_minerror J DSP_q15tofl

Introduction 1-3

Features and Benefits

1.2Features and Benefits

-Hand-coded assembly-optimized routines

-C and linear assembly source code

-C-callable routines, fully compatible with the TI C6x compiler

-Fractional Q.15-format operands supported on some benchmarks

-Benchmarks (time and code)

-Tested against C model

1-4

Chapter 2

Installing and Using DSPLIB

This chapter provides information on how to install and rebuild the TI C64x+ DSPLIB.

Topic		Page
2.1	How to Install DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . 2-2
2.2	Using DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 2-3
2.3	How to Rebuild DSPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 2-5

2-1

How to Install DSPLIB

2.1 How to Install DSPLIB

Note:

You should read the README.txt file for specific details of the release.

The DSPLIB is provided in the file dsp64plus.zip. The file must be unzipped to provide the following directory structure:

dsp

|
+−−README.txt	Top−level README file
|
+−−docs	library documentation
|
+−−examples	CCS project examples
|
|−−include	Required include files
|
|−−lib	library and source archives
|
|−−support	fft twiddle generation functions
|

Please install the contents of the lib directory in the default directory indicated by your C_DIR environment. If you choose not to install the contents in the default directory, update the C_DIR environment variable, for example, by adding the following line in autoexec.bat file:

SET C_DIR=<install_dir>/lib;<install_dir>/include;%C_DIR%

or under Unix/csh:

setenv C_DIR ”<install_dir>/lib;<install_dir>/include; $C_DIR”

or under Unix/Bourne Shell:

C_DIR=”<install_dir>/lib;<install_dir>/include;$C_DIR”; export C_DIR

2-2

Using DSPLIB

2.2 Using DSPLIB

2.2.1DSPLIB Arguments and Data Types

2.2.1.1DSPLIB Types

Table 2−1 shows the data types handled by the DSPLIB.

Table 2−1. DSPLIB Data Types

	Size
Name	(bits)	Type	Minimum	Maximum
short	16	integer	−32768	32767
int	32	integer	−2147483648	2147483647
long	40	integer	−549755813888	549755813887
pointer	32	address	0000:0000h	FFFF:FFFFh
Q.15	16	fraction	−0.9999694824...	0.9999694824...
Q.31	32	fraction	−0.99999999953...	0.99999999953...
IEEE float	32	floating point	1.17549435e−38	3.40282347e+38
IEEE double	64	floating point	2.2250738585072014e−308	1.7976931348623157e+308

Unless specifically noted, DSPLIB operates on Q.15-fractional data type elements. Appendix A presents an overview of Fractional Q formats.

2.2.1.2DSPLIB Arguments

TI DSPLIB functions typically operate over vector operands for greater efficiency. Even though these routines can be used to process short arrays, or even scalars (unless a minimum size requirement is noted), they will be slower for those cases.

-Vector stride is always equal to 1: Vector operands are composed of vector elements held in consecutive memory locations (vector stride equal to 1).

-Complex elements are assumed to be stored in consecutive memory locations with Real data followed by Imaginary data.

-In-place computation is not allowed, unless specifically noted: Source operand cannot be equal to destination operand.

Installing and Using DSPLIB

2-3

Using DSPLIB

2.2.2Calling a DSPLIB Function From C

In addition to correctly installing the DSPLIB software, follow these steps to include a DSPLIB function in the code:

-Include the function header file corresponding to the DSPLIB function

-Link the code with dsp64plus.lib

-Use a correct linker command file for the platform used.

The examples in the DSP\Examples folder show how to use the DSPLIB in a Code Composer Studio C envirionment.

2.2.3Calling a DSP Function From Assembly

The C64x+ DSPLIB functions were written to be used from C. Calling the functions from assembly language source code is possible as long as the calling function conforms to the Texas Instruments C64x+ C compiler calling conventions. For more information, see Section 8 (Runtime Environment) of

TMS320C6000 Optimizing C Compiler User’s Guide (SPRU187).

2.2.4DSPLIB Testing − Allowable Error

DSPLIB is tested under the Code Composer Studio environment against a reference C implementation. You can expect identical results between Reference C implementation and its Assembly implementation when using test routines that focus on fixed-point type results. The test routines that deal with floating points typically allow an error margin of 0.000001 when comparing the results of reference C code and DSPLIB assembly code.

2.2.5DSPLIB Overflow and Scaling Issues

The DSPLIB functions implement the same functionality of the reference C code. You must conform to the range requirements specified in the API function, and in addition, restrict the input range so that the outputs do not overflow.

In FFT functions, twiddle factors are generated with a fixed scale factor; i.e., 32767(=215−1) for all 16-bit FFT functions, 1073741823(=230−1) for DSP_fft32x32s, 2147483647(=231−1) for all other 32-bit FFT functions. Twiddle factors cannot be scaled further to not scale input data. Because DSP_fft16x16r and DSP_fft32x32s perform scaling by 2 at each radix-4 stage, the input data must be scaled by 2(log2(nx)−cei[log4(nx)−1]) to completely prevent overflow. In all other FFT functions, the input data must be scaled by 2(log2(nx)) because no scaling is done by the functions.

2-4

How to Rebuild DSPLIB

2.2.6Interrupt Behavior of DSPLIB Functions

All of the functions in this library are designed to be used in systems with interrupts. Thus, it is not necessary to disable interrupts when calling any of these functions. The functions in the library will disable interrupts as needed to protect the execution of code in tight loops and so on. Library functions have three categories:

-Fully-interruptible: These functions do not disable interrupts. Interrupts are blocked by at most 5 to 10 cycles at a time (not counting stalls) by branch delay slots.

-Partially-interruptible: These functions disable interrupts for long periods of time, with small windows of interruptibility. Examples include a function with a nested loop, where the inner loop is non-interruptible and the outer loop permits interrupts between executions of the inner loop.

-Non-interruptible: These functions disable interrupts for nearly their entire duration. Interrupts may happen for a short time during the setup and exit sequence.

Note that all three function categories tolerate interrupts. That is, an interrupt can occur at any time without affecting the function correctness. The interruptibility of the function only determines how long the kernel might delay the processing of the interrupt.

2.3 How to Rebuild DSPLIB

If you would like to rebuild DSPLIB (for example, because you modified the source file contained in the archive), you will have to use the mk6x utility as follows:

mk6x dsp64plus.src −mv64plus −l dsp64plus.lib

Installing and Using DSPLIB

2-5

2-6

Chapter 3

DSPLIB Function Tables

This chapter provides tables containing all DSPLIB functions, a brief description of each, and a page reference for more detailed information.

Topic		Page
3.1	Arguments and Conventions Used . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . 3-2
3.2	DSPLIB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . 3-3
3.3	DSPLIB Function Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 3-4
3.4	Differences Between the C64x and C64x+ DSPLIBs	3-8

3-1

Arguments and Conventions Used

3.1 Arguments and Conventions Used

The following convention has been used when describing the arguments for each individual function:

Table 3−1. Argument Conventions

Argument	Description
x,y	Argument reflecting input data vector
r	Argument reflecting output data vector
nx,ny,nr	Arguments reflecting the size of vectors x,y, and r, respectively. For
	functions in the case nx = ny = nr, only nx has been used across.
h	Argument reflecting filter coefficient vector (filter routines only)
nh	Argument reflecting the size of vector h
w	Argument reflecting FFT coefficient vector (FFT routines only)

Some C64x+ functions have additional restrictions due to optimization using new features such as higher multiply throughput. While these new functions perform better, they can also lead to problems if not carefully used. For example, DSP_autocor_rA8 is faster than DSP_autocor, but the output buffer must be aligned to an 8−byte boundary. Therefore, the new functions are named with any additional restrictions. Three types of restrictions are specified to a pointer: minimum buffer size (M), buffer alignment (A), and the number of elements in the buffer to be a multiple of an integer (X).The following convention has been used when describing the arguments for each individual function:

A kernel function foo with two parameters, m and n, with the following restrictions:

m −> Minimum buffer size = 8, buffer alignment = double word, buffer needs to be a multiple of 8 elements

n −> Minimum buffer size = 32, buffer alignment = word , buffer needs to be a multiple of 16 elements

This function would be named: foo_mM8A8X8_nM32A4X16.

3-2

DSPLIB Functions

3.2 DSPLIB Functions

The routines included in the DSP library are organized into eight functional categories and listed below in alphabetical order.

-Adaptive filtering

-Correlation

-FFT

-Filtering and convolution

-Math

-Matrix functions

-Miscellaneous

-Obsolete functions

DSPLIB Function Tables

3-3

DSPLIB Function Tables

3.3 DSPLIB Function Tables

Table 3−2. Adaptive Filtering

Functions	Description	Page
long DSP_firlms2(short *h, short *x, short b, int nh)	LMS FIR	4-2

Table 3−3. Correlation

Functions	Description	Page
void DSP_autocor(short *r,short *x, int nx, int nr)	Autocorrelation	4-4
void DSP_autocor_rA8(short *r,short *x, int nx, int nr)	Autocorrelation ( r[] must be	4-4
	double word aligned)

Table 3−4. FFT

Functions Description Page

void DSP_fft16x16(short *w, int nx, short *x, short *y)

Complex out of place, Forward

4-8

FFT mixed radix with digit reversal. Input/Output data in Re/Im order.

void DSP_fft16x16_imre(short *w, int nx, short *x, short *y)

void DSP_fft16x16r(int nx, short *x, short *w, unsigned char *brev, short *y, int radix, int offset, int n_max)

void DSP_fft16x32(short *w, int nx, int *x, int *y)

void DSP_fft32x32(int *w, int nx, int *x, int *y)

void DSP_fft32x32s(int *w, int nx, int *x, int *y)

Complex out of place, Forward	4-11
FFT mixed radix with digit
reversal. Input/Output data in
Im/Re order.
Cache-optimized mixed radix FFT	4-14
with scaling and rounding, digit
reversal, out of place. Input and
output: 16 bits, Twiddle factor: 16
bits.
Extended precision, mixed radix	4-24
FFT, rounding, digit reversal, out
of place. Input and output: 32 bits,
Twiddle factor: 16 bits.
Extended precision, mixed radix	4-26
FFT, rounding, digit reversal, out
of place. Input and output: 32 bits,
Twiddle factor: 32 bits.
Extended precision, mixed radix	4-28
FFT, digit reversal, out of place.,
with scaling and rounding. Input

and output: 32 bits, Twiddle factor: 32 bits.

3-4

DSPLIB Function Tables

Table 3−4. FFT (Continued)

Functions

Description

Page

void DSP_ifft16x16(short *w, int nx, short *x, short *y)

Complex out of place, Inverse

4-28

FFT mixed radix with digit reversal. Input/Output data in Re/Im order.

void DSP_ifft16x16_imre(short *w, int nx, short *x, short *y)

Complex out of place, Inverse

4-28

FFT mixed radix with digit reversal. Input/Output data in Re/Im order.

void DSP_ifft16x32(short *w, int nx, int *x, int *y)

void DSP_ifft32x32(int *w, int nx, int *x, int *y)

Extended precision, mixed radix	4-34
IFFT, rounding, digit reversal, out
of place. Input and output: 32 bits,
Twiddle factor: 16 bits.
Extended precision, mixed radix	4-36
IFFT, digit reversal, out of place,
with scaling and rounding. Input

and output: 32 bits, Twiddle factor: 32 bits.

Table 3−5. Filtering and Convolution

Functions

Description

Page

void DSP_fir_cplx (short *x, short *h, short *r, int nh, int nx)

void DSP_fir_cplx_hM4X4 (short *x, short *h, short *r, int nh, int nx)

void DSP_fir_gen (short *x, short *h, short *r, int nh, int nr)

void DSP_fir_gen_hM17_rA8X8 (short *x, short *h, short *r, int nh, int nr)

Complex FIR Filter (nh is a	4-38
multiple of 2)
Complex FIR Filter (nh is a	4-38
multiple of 4)
FIR Filter (any nh)	4-42
FIR Filter (r[] must be double	4-42
word aligned, nr must be multiple
of 8)

void DSP_fir_r4 (short *x, short *h, short *r, int nh, int nr)

void DSP_fir_r8 (short *x, short *h, short *r, int nh, int nr)

void DSP_fir_r8_hM16_rM8A8X8 (short *x, short *h, short *r, int nh, int nr)

void DSP_fir_sym (short *x, short *h, short *r, int nh, int nr, int s)

FIR Filter (nh is a multiple of 4)	4-46
FIR Filter (nh is a multiple of 8)	4-50
FIR Filter (r[] must be double	4-50
word aligned, nr is a multiple of 8)
Symmetric FIR Filter (nh is a	4-52
multiple of 8)

DSPLIB Function Tables

3-5

DSPLIB Function Tables

Table 3−5. Filtering and Convolution (Continued)

Functions	Description	Page
void DSP_iir(short *r1, short *x, short *r2, short *h2, short	IIR with 5 Coefficients	4-54
*h1, int nr)
void DSP_iirlat(short *x, int nx, short *k, int nk, int *b,	All−pole IIR Lattice Filter	4-56
short *r)

Table 3−6. Math

Functions	Description	Page
int DSP_dotp_sqr(int G, short *x, short *y, int *r, int nx)	Vector Dot Product and Square	4-58
int DSP_dotprod(short *x, short *y, int nx)	Vector Dot Product	4-60
short DSP_maxval (short *x, int nx)	Maximum Value of a Vector	4-62
int DSP_maxidx (short *x, int nx)	Index of the Maximum Element of	4-63
	a Vector
short DSP_minval (short *x, int nx)	Minimum Value of a Vector	4-65
void DSP_mul32(int *x, int *y, int *r, short nx)	32-bit Vector Multiply	4-66
void DSP_neg32(int *x, int *r, short nx)	32-bit Vector Negate	4-68
void DSP_recip16 (short *x, short *rfrac, short *rexp, short	16-bit Reciprocal	4-69
nx)
int DSP_vecsumsq (short *x, int nx)	Sum of Squares	4-71
void DSP_w_vec(short *x, short *y, short m, short *r, short	Weighted Vector Sum	4-72
nr)

Table 3−7. Matrix

Functions	Description	Page
void DSP_mat_mul(short *x, int r1, int c1, short *y, int c2,	Matrix Multiplication	4-73
short *r, int qs)
void DSP_mat_trans(short *x, short rows, short columns,	Matrix Transpose	4-75
short *r)

3-6

DSPLIB Function Tables

Table 3−8. Miscellaneous

Functions

Description

Page

short DSP_bexp(int *x, short nx)

void DSP_blk_eswap16(void *x, void *r, int nx)

void DSP_blk_eswap32(void *x, void *r, int nx)

void DSP_blk_eswap64(void *x, void *r, int nx)

void DSP_blk_move(short *x, short *r, int nx) void DSP_fltoq15 (float *x,short *r, short nx)

int DSP_minerror (short *GSP0_TABLE,short *errCoefs, int *savePtr_ret)

void DSP_q15tofl (short *x, float *r, short nx)

Max Exponent of a Vector (for	4-76
scaling)
Endian-swap a block of 16-bit	4-78
values
Endian-swap a block of 32-bit	4-80
values
Endian-swap a block of 64-bit	4-82
values
Move a Block of Memory	4-84
Float to Q15 Conversion	4-85
Minimum Energy Error Search	4-87
Q15 to Float Conversion	4-89

Table 3−9. Obsolete Functions

Functions

Description

Page

void DSP_bitrev_cplx (int *x, short *index, int nx) void DSP_radix2 (int nx, short *x, short *w)

void DSP_r4fft (int nx, short *x, short *w)

void DSP_fft(short *w, int nx, short *x, short *y)

void DSP_fft16x16t(short *w, int nx, short *x, short *y)

Use DSP_fft16x16() instead	4-88
Use DSP_fft16x16() instead	4-91
Use DSP_fft16x16() instead	4-93
Use DSP_fft16x16() instead	4-96
Use DSP_fft16x16() instead	4-107

DSPLIB Function Tables

3-7

Differences Between the C64x and C64x+ DSPLIBs

3.4 Differences Between the C64x and C64x+ DSPLIBs

The C64x+ DSPLIB was developed by optimizing some of the functions of the C64x DSPLIB to take advantage of the C64x+ architecture.

Table 3−10 shows the optimized functions for the C64x+ DSPLIB.

There are two optimization types:

-SPLOOP conversion: Optimized code uses SPLOOP to provide interruptibility and decrease power consumption. The new C64x+ instructions do not increase algorithm performance, and thus, are not used.

-Kernel redesign, SPLOOP: Kernel of algorithm rewritten to take advantage of the new C64x+ instructions and of the SPLOOP feature.

Table 3−10. Functions Optimized in the C64x+ DSPLIB

Function	C64x+ Optimized	Optimization Type
DSP_firlms2	No
DSP_autocor	No
DSP_autocor_rA8	Yes	Kernel re−design, SPLOOP
		Optimization resulted in new
		requirements. New name is used.
DSP_fft16x16	Yes	New Function Optimized C64x+
DSP_fft16x16_imre	Yes	New Function Optimized C64x+
DSP_fft16x16r	Yes	Kernel re−design, SPLOOP
DSP_fft16x32	Yes	Kernel re−design, SPLOOP
DSP_fft32x32	Yes	Kernel re−design, SPLOOP
DSP_fft32x32s	Yes	Kernel re−design, SPLOOP
DSP_ifft16x16	Yes	New Function Optimized C64x+
DSP_ifft16x16_imre	Yes	New Function Optimized C64x+
DSP_ifft16x32	Yes	Kernel re−design, SPLOOP
DSP_ifft32x32	Yes	Kernel re−design, SPLOOP
DSP_fir_cplx	No

3-8

Differences Between the C64x and C64x+ DSPLIBs

Table 3−10. Functions Optimized in the C64x+ DSPLIB (Continued)

Function	C64x+ Optimized	Optimization Type
DSP_fir_cplx_hM4X4	Yes	Kernel re−design, SPLOOP
		Optimization resulted in new
		requirements. New name is used.
DSP_fir_gen	No
DSP_fir_gen_hM17_rA8X8	Yes	Kernel re−design, SPLOOP
		Optimization resulted in new
		requirements. New name is used.
DSP_fir_r4	No
DSP_fir_r8	No
DSP_fir_r8_hM16_rM8A8X8	Yes	Kernel re−design, SPLOOP
		Optimization resulted in new
		requirements. New name is used.
DSP_fir_sym	No
DSP_iir	No
DSP_iirlat	No
DSP_dotp_sqr	No
DSP_dotprod	Yes	SPLOOP conversion
DSP_maxval	No
DSP_maxidx	No
DSP_minval	No
DSP_mul32	No
DSP_neg32	No
DSP_recip16	No
DSP_vecsumsq	No
DSP_w_vec	No
DSP_mat_mu	No
DSP_mat_trans	No
DSP_bexp	No

DSPLIB Function Tables

3-9

Differences Between the C64x and C64x+ DSPLIBs

Table 3−10. Functions Optimized in the C64x+ DSPLIB (Continued)

Function	C64x+ Optimized	Optimization Type
DSP_blk_eswap16	No
DSP_blk_eswap32	No
DSP_blk_move	Yes	SPLOOP conversion
DSP_fltoq15	No
DSP_minerror	No
DSP_q15tofl	No
DSP_bitrev_cplx	No	Obsolete
DSP_radix2	No	Obsolete
DSP_r4fft	No	Obsolete
DSP_fft	No	Obsolete
DSP_fft16x16t	No	Obsolete

Any functions which were not optimized for the C64x+ have the same performance as on the C64x.

3-10

Chapter 4

DSPLIB Reference

This chapter provides a list of the functions within the DSP library (DSPLIB) organized into functional categories. The functions within each category are listed in alphabetical order and include arguments, descriptions, algorithms, benchmarks, and special requirements.

Topic		Page
4.1	Adaptive Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. . 4-2
4.2	Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 4-4
4.3	FFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 4-8
4.4	Filtering and Convolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	4-38
4.5	Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	4-58
4.6	Matirx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	4-73
4.7	Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	4-76
4.8	Obsolete Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	4-90

4-1

DSP_firlms2

4.1 Adaptive Filtering

DSP_firlms2	LMS FIR
Function		long DSP_firlms2(short * restrict h, const short * restrict x, short b, int nh)
Arguments		h[nh]	Coefficient Array
		x[nh+1]	Input Array
		b	Error from previous FIR
		nh	Number of coefficients. Must be multiple of 4.
		return long	Return value
Description		The Least Mean Square Adaptive Filter computes an update of all nh
		coefficients by adding the weighted error times the inputs to the original
		coefficients. The input array includes the last nh inputs followed by a new
		single sample input. The coefficient array includes nh coefficients.
Algorithm		This is the C equivalent of the assembly code without restrictions. Note that
		the assembly code is hand optimized and restrictions may apply.
		long DSP_firlms2(short h[ ],short x[ ], short b,
		int nh)
	{
		int	i;
		long	r = 0;

for (i = 0; i < nh; i++) { h[i] += (x[i] * b) >> 15; r += x[i + 1] * h[i];

}

return r;

}

Special Requirements

-This routine assumes 16-bit input and output.

-The number of coefficients nh must be a multiple of 4.

4-2