Texas Instruments TMS320C67 DSP Series Programmer's Reference Manual
TMS320C67x DSP Library
Programmer’s Reference Guide
Literature Number: SPRU657
February 2003
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 that 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 dif ferent 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.
Mailing Address:
Texas Instruments
Post Office Box 655303
Dallas, Texas 75265
Copyright 2003, Texas Instruments Incorporated
About This Manual
Preface
Read This First
Welcome to the TMS320C67x digital signal processor (DSP) Library or
DSPLIB, for short. The DSPLIB is a collection of 36 high-level optimized DSP
functions for the TMS320C67x device. This source code library includes Ccallable functions (ANSI-C language compatible) for general signal processing math and vector functions.
This document contains a reference for the DSPLIB functions and is organized
as follows:
- Overview - an introduction to the TI C67x DSPLIB
- Installation - information on how to install and rebuild DSPLIB
- DSPLIB Functions - a quick reference table listing of routines in the library
- DSPLIB Reference - a description of all DSPLIB functions complete with
- Information about performance, fractional Q format and customer support
How to Use This Manual
The information in this document describes the contents of the TMS320C67x
DSPLIB in several different ways.
- Chapter 1 provides a brief introduction to the TI C67x DSPLIB, shows the
- Chapter 2 provides information on how to install, use, and rebuild the TI
- Chapter 3 provides a quick overview of all DSPLIB functions in table for-
calling convention, algorithm details, special requirements and implementation notes
organization of the routines contained in the library, and lists the features
and benefits of the DSPLIB.
C67x DSPLIB
mat for easy reference. The information shown for each function includes
the syntax, a brief description, and a page reference for obtaining more
detailed information.
iiiRead This First
Notational Conventions
-
- Appendix A describes performance considerations related to the C67x
- Appendix B provides information about software updates and customer
Notational Conventions
This document uses the following conventions:
- Program listings, program examples, and interactive displays are shown
- In syntax descriptions, the function or macro appears in a bold typeface
Chapter 4 provides a list of the routines within the DSPLIB organized into
functional categories. The functions within each category are listed in alphabetical order and include arguments, descriptions, algorithms, benchmarks, and special requirements.
DSPLIB and provides information about the Q format used by DSPLIB
functions.
support.
in a special typeface.
and the parameters appear in plainface within parentheses. Portions of a
syntax that are in bold should be entered as shown; portions of syntax that
are within parentheses describe the type of information that should be entered.
- Macro names are written in uppercase text; function names are written in
lowercase.
- The TMS320C67x is also referred to in this reference guide as the C67x.
Related Documentation From Texas Instruments
The following books describe the TMS320C6x devices and related support
tools. To obtain a copy of any of these TI documents, call the Texas Instruments Literature Response Center at (800) 477-8924. When ordering, please
identify the book by its title and literature number. Many of these documents
can be found on the Internet at http://www.ti.com.
TMS320C62x/C67x Technical Brief (literature number SPRU197) gives an
introduction to the ’C62x/C67x digital signal processors, development tools,
and third-party support.
TMS320C6000 CPU and Instruction Set Reference Guide (literature number SPRU189) describes the C6000 CPU architecture, instruction set, pipeline, and interrupts for these digital signal processors.
iv
Trademarks
TMS320C6000 Peripherals Reference Guide (literature number SPRU190)
describes common peripherals available on the TMS320C6000 digital signal
processors. This book includes information on the internal data and program
memories, the external memory interface (EMIF), the host port interface (HPI),
multichannel buffered serial ports (McBSPs), direct memory access (DMA),
enhanced DMA (EDMA), expansion bus, clocking and phase-locked loop
(PLL), and the power-down modes.
TMS320C6000 Programmer’s Guide (literature number SPRU198) describes ways to optimize C and assembly code for the TMS320C6000 DSPs
and includes application program examples.
TMS320C6000 Assembly Language Tools User’s Guide (literature number
SPRU186) describes the assembly language tools (assembler, linker, and other tools used to develop assembly language code), assembler directives,
macros, common object file format, and symbolic debugging directives for the
C6000 generation of devices.
TMS320C6000 Optimizing C Compiler User’s Guide (literature number
SPRU187) describes the C6000 C compiler and the assembly optimizer. Th is
C compiler accepts ANSI standard C source code and produces assembly language source code for the C6000 generation of devices. The assembly optimizer helps you optimize your assembly code.
Trademarks
TMS320C6000 Chip Support Library (literature number SPRU401) de-
scribes the application programming interfaces (APIs) used to configure and
control all on-chip peripherals.
TMS320C62x Image/Video Processing Library (literature number
SPRU400) describes the optimized image/video processing functions including many C-callable, assembly-optimized, general-purpose image/video
processing routines.
TMS320C6000, TMS320C62x, TMS320C67x, and Code Composer Studio
are trademarks of Texas Instruments.
Other trademarks are the property of their respective owners.
vRead This First
Contents
Contents
1 Introduction 1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a brief introduction to the TI C67x DSPLIB, shows the organization of the routines contained in the library, and lists the features and benefits of the DSPLIB.
1.1 Introduction to the TI C67x DSPLIB 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Features and Benefits 1-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Installing and Using DSPLIB 2-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides information on how to install, use, and rebuild the TI C67x DSPLIB.
2.1 DSP Library Contents 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 How to Install the DSP Library 2-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Using DSPLIB 2-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 DSPLIB Arguments and Data Types 2-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2 Calling a DSPLIB Function From C 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.3 Calling a DSP Function From Assembly 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.4 How DSPLIB is Tested - Allowable Error 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.5 How DSPLIB Deals With Overflow and Scaling Issues 2-6. . . . . . . . . . . . . . . . . . . .
2.3.6 Interrupt Behavior of DSPLIB Functions 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 How to Rebuild DSPLIB 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4 DSPLIB Reference 4-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a list of the functions within the DSPLIB organized into functional categories.
4.1 Adaptive Filtering 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_lms 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Correlation 4-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_autocor 4-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 FFT 4-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_bitrev_cplx 4-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_cfftr4_dif 4-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_cfftr2_dit 4-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_fftSPxSP 4-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_ifftSPxSP 4-24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_icfftr2_dif 4-33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vii
Contents
4.4 Filtering and Convolution 4-38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_fir_cplx 4-38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_fir_gen 4-39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_fir_r2 4-41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_fircirc 4-42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_biquad 4-44. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_iir 4-46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_iirlat 4-48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_convol 4-50. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5 Math 4-52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_dotp_sqr 4-52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_dotprod 4-53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_dotp_cplx 4-54. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_maxval 4-56. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_maxidx 4-57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_minval 4-58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_vecrecip 4-59. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_vecsum_sq 4-60. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_w_vec 4-61. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_vecmul 4-62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6 Matrix 4-64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_mat_mul 4-64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_mat_trans 4-65. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_mat_mul_cplx 4-66. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7 Miscellaneous 4-69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_blk_move 4-69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_blk_eswap16 4-70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_blk_eswap32 4-71. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_blk_eswap64 4-73. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_fltoq15 4-75. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_sp_minerr 4-76. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSPF_q15tofl 4-78. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Performance/Fractional Q Formats A-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Describes performance considerations related to the C67x 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 Q.15 Format A-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B Software Updates and Customer Support B-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides information about software updates and customer support.
B.1 DSPLIB Software Updates B-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.2 DSPLIB Customer Support B-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C Glossary C-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
viii
Tables
Tables
2-1 DSPLIB Data Types 2-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-1 Q.15 Bit Fields A-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ixContents
Chapter 1
Introduction
This chapter provides a brief introduction to the TI C67x DSP Library
(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 C67x DSPLIB 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Features and Benefits 1-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-1
Introduction to the TI C67x DSPLIB
1.1 Introduction to the TI C67x DSPLIB
The TI C67x DSPLIB is an optimized DSP Function Library for C programmers
using TMS320C67x devices. It includes 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 DSPF_sp_lms
- Correlation
J DSPF_sp_autocor
- FFT
J DSPF_sp_bitrev_cplx
J DSPF_sp_cfftr4_dif
J DSPF_sp_cfftr2_dit
J DSPF_sp_fftSPxSP
J DSPF_sp_ifftSPxSP
J DSPF_sp_icfftr2_dif
- Filtering and convolution
J DSPF_sp_fir_cplx
J DSPF_sp_fir_gen
J DSPF_sp_fir_r2
J DSPF_sp_fircirc
J DSPF_sp_biquad
J DSPF_sp_iir
J DSPF_sp_iirlat
J DSPF_sp_convol
1-2
-
Math
J DSPF_sp_dotp_sqr
J DSPF_sp_dotprod
J DSPF_sp_dotp_cplx
J DSPF_sp_maxval
J DSPF_sp_maxidx
J DSPF_sp_minval
J DSPF_sp_vecrecip
J DSPF_sp_vecsum_sq
J DSPF_sp_w_vec
J DSPF_sp_vecmul
- Matrix
J DSPF_sp_mat_mul
J DSPF_sp_mat_trans
Introduction to the TI C67x DSPLIB
J DSPF_sp_mat_mul_cplx
- Miscellaneous
J DSPF_sp_blk_move
J DSPF_sp_blk_eswap16
J DSPF_sp_blk_eswap32
J DSPF_sp_blk_eswap64
J DSPF_fltoq15
J DSPF_sp_minerr
J DSPF_q15tofl
1-3Introduction
Features and Benefits
1.2 Features 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 the C model
1-4
Chapter 2
Installing and Using DSPLIB
This chapter provides information on how to install, use, and rebuild the TI
C67x DSPLIB.
Topic Page
2.1 DSP Library Contents 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 How to Install the DSP Library 2-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Using DSPLIB 2-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 How to Rebuild DSPLIB 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-1
DSP Library Contents
2.1 DSP Library Contents
The C67xDSPLIB.exe installs the following file structure:
bin Directory containing FFT twiddle factor generators
lib
dsp67x.lib
dsp67x.src
dsp67x_c.src
dsp67x_sa.src
include
h header files
h67 header files
support Directory containing support files.
†
docs
pdf
spru657.pdf
†
This installs into the Code Composer Studio docs directory.
Dirctory containing the following library files:
Little-endian C67x library file
Assembly source archive file
C-source archive file
Linear assembly source archive file
Directory containing the following include files:
C header files
Assembly header files
Directory containing the following document files:
PDF document of API - this document
2-2
2.2 How to Install the DSP Library
To install the DSP libary, follow these steps:
Step 1: Open the file, C67xDSPLIB.exe.
Step 2: Click Yes to install the library.
Step 3: Click Next to continue with the Install Shield Wizard.
Step 4: Read the Software Licenses, and choose either “I accept” or “I don’t
accept.”
Step 5: Click Next to continue.
If you selected “I accept,” the installation will continue.
If you selected “I don’t accept,” the installation cancels.
Step 6: Choose the location where you would like to install the library. The
wizard will install the library into the c6700 sub-directory of the directory you choose.
The default location is c:\ti.
How to Install the DSP Library
Step 7: Click Next.
Step 8: If the library has already been installed, you will be prompted to de-
cide whether to replace the files or not. Click Yes to update the library .
Step 9: The Install Shield will complete the installation. When the installation
is complete, click Finish.
2-3Installing and Using DSPLIB
Using DSPLIB
2.3 Using DSPLIB
2.3.1 DSPLIB Arguments and Data Types
DSPLIB Types
Table 2-1 shows the data types handled by the DSPLIB.
Table 2-1. DSPLIB Data Types
Size
Name
short 16 Integer -32768 32767
int 32 Integer -2147483648 2147483647
long 40 Integer -549755813888 549755813887
pointer 32 Address 0000:0000h FFFF:FFFFh
(bits)
Type Minimum Maximum
Q.15 16 Fraction -1.0 0.9999694824...
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 single-precision IEEE float
data type elements.
DSPLIB Arguments
TI DSPLIB functions typically operate over vector operands for greater efficiency. Even though these routines can be used to process smaller arrays, or
even scalars (unless a minimum size requirement is noted), they will be slower
for these 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 loca-
tions with Real data followed by Imaginary data.
- In-place computation is not allowed, unless specifically noted: Source and
destination arrays should not overlap.
2-4
2.3.2 Calling a DSPLIB Function From C
In addition to correctly installing the DSPLIB software, you must follow these
steps to include a DSPLIB function in your code:
- Include the function header file corresponding to the DSPLIB function
- Link your code with dsp67x.lib
- Use a correct linker command file for the platform you use. Remember
most functions in dsp67x.lib are written assuming little-endian mode of operation.
For example, if you want to call the Autocorrelation DSPLIB function, you
would add:
#include <dspf_sp_autocor.h>
in your C file and compile and link using
cl6x main.c –z –o autocor_drv.out –lrts6700.lib ldsp67x.lib
Code Composer Studio Users
Using DSPLIB
Assuming your C_DIR environment is correctly set up (as mentioned in
section 2.2), you would have to add DSPLIB under the Code Composer Studio
environment by choosing dsp67x.lib from the menu Project → Add Files to
Project. Also, you should make sure that you link with the run-time support library, rts6700.lib.
2.3.3 Calling a DSP Function From Assembly
The C67x 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 C6x C compiler calling conventions. Here, the corresponding .h67 header files located in the ‘include’ directory must be included using the ‘.include’ directive. For more information, refer to
section 8 (Runtime Environment) of the TMS320C6000 Optimizing C Compil-
er User’s Guide (SPRU187).
2.3.4 How DSPLIB is Tested - Allowable Error
DSPLIB is tested under the Code Composer Studio environment against a reference C implementation. Because of floating point calculation order change
for these two implementations, they differ in the results with an allowable tolerance for that particular kernel. Thus every kernel’s test routine (in the driver
file) has error tolerance variable defined that gives the maximum value that is
acceptable as the error difference.
2-5Installing and Using DSPLIB
How to Rebuild DSPLIB
For example:
#define R_TOL (1e-05)
Here, the maximum difference allowed between the output reference array
from the C implementation and all other implementations (linear asm, hand
asm) is 1e-05 (0.00001).
The error tolerance is therefore different for different functions.
2.3.5 How DSPLIB Deals With Overflow and Scaling Issues
The DSPLIB functions implement the same functionality of the reference C
code. The user is expected to conform to the range requirements specified in
the API function, and in addition, take care to restrict the input range in such a
way that the outputs do not overflow.
2.3.6 Interrupt Behavior of DSPLIB Functions
Most DSPLIB functions are interrupt-tolerant but not interruptible. The cycle
count formula provided for each function can be used to estimate the number
of cycles during which interrupts cannot be taken.
2.4 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 dsp67x.src -mv6700 -l dsp67x.lib
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-1
Arguments and Conventions Used
3.1 Arguments and Conventions Used
The following convention has been followed 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)
3-2
3.2 DSPLIB Functions
The routines included in the DSP library are organized into seven functional
categories and are listed below in alphabetical order.
- Adaptive filtering
- Correlation
- FFT
- Filtering and convolution
- Math
- Matrix
- Miscellaneous
DSPLIB Functions
3-3DSPLIB Function Tables
DSPLIB Function Tables
3.3 DSPLIB Function Tables
Table 3-2. Adaptive Filtering
Functions Description Page
float DSPF_sp_lms (float *x, float *h, float *desired, float
*r, float adaptrate, float error, int nh, int nr)
LMS adaptive filter 4-2
Table 3-3. Correlation
Functions Description Page
void DSPF_sp_autocor (float *r, float*x, int nx, int nr) Autocorrelation 4-4
Table 3-4. FFT
Functions Description Page
void DSPF_sp_bitrev_cplx (double *x, short *index, int nx) Complex bit reverse 4-6
void DSPF_sp_cfftr4_dif (float *x, float *w, short n) Complex radix 4 FFT using DIF 4-9
void DSPF_sp_cfftr2_dit (float *x, float *w, short n) Complex radix 2 FFT using DIT 4-13
void DSPF_sp_fftSPxSP (int N, float *ptr_x, float *ptr_w,
float *ptr_y, unsigned char *brev, int n_min, int offset, int
n_max)
void DSPF_sp_ifftSPxSP (int N, float *ptr_x, float *ptr_w,
float *ptr_y, unsigned char *brev, int n_min, int offset, int
n_max)
Cache optimized mixed radix FFT
with digit reversal
Cache optimized mixed radix
inverse FFT with complex input
4-16
4-24
void DSPF_sp_icfftr2_dif (float *x, float *w, short n)
3-4
Complex radix 2 inverse FFT
using DIF
4-33
DSPLIB Function Tables
Table 3-5. Filtering and Convolution
Functions Description Page
void DSPF_sp_fir_cplx (float *x, float *h, float *r, int nh, int
nr)
void DSPF_sp_fir_gen (float *x, float *h, float *r, int nh, int
nr)
void DSPF_sp_fir_r2 (float *x, float *h, float *r, int nh, int
nr)
void DSPF_sp_fircirc (float x[], float h[], float r[], int index,
int csize, int nh, int nr)
void DSPF_sp_biquad (float x[], float b[], float a[], float
delay[], float r[], int nx)
void DSPF_sp_iir (float *r1, float *x, float *r2, float *h2,
float *h1, int nr)
void DSPF_sp_iirlat (float *x, int nx, float *k, int nk, float
*b, float *r)
void DSPF_sp_convol (float *x, float *h, float *r, int nh, int
nr)
Complex FIR filter (radix 2) 4-38
FIR filter (general purpose) 4-39
FIR filter (radix 2) 4-41
FIR filter with circularly addressed
input
Biquad filter (IIR of second order) 4-44
IIR filter (used in VSELP vocoder) 4-46
All-pole IIR lattice filter 4-48
Convolution 4-50
4-42
3-5DSPLIB Function Tables
DSPLIB Function Tables
Table 3-6. Math
Functions Description Page
float DSPF_sp_dotp_sqr (float G, float *x, float *y, float *r,
int nx)
float DSPF_sp_dotprod (float*x, float*y, int nx) Vector dot product 4-53
void DSPF_sp_dotp_cplx (float *x, float *y, int n, float *re,
float *im)
float DSPF_sp_maxval (float *x, int nx) Maximum value of a vector 4-56
int DSPF_sp_maxidx (float *x, int nx) Index of the maximum element of
float DSPF_sp_minval (float *x, int nx) Minimum value of a vector 4-58
void DSPF_sp_vecrecip (float *x, float *r, int n) Vector reciprocal 4-59
float DSPF_sp_vecsum_sq (float *x, int n) Sum of squares 4-60
void DSPF_sp_w_vec (float *x, float *y, float m, float *r, int
nr)
void DSPF_sp_vecmul (float *x, float *y, float *r, int n)
Vector dot product and square 4-52
Complex vector dot product 4-54
4-57
a vector
Weighted vector sum 4-61
Vector multiplication 4-62
Table 3-7. Matrix
Functions Description Page
void DSPF_sp_mat_mul (float *x, int r1, int c1, float *y, int
c2, float *r)
void DSPF_sp_mat_trans (float *x, int rows, int cols,
float *r)
void DSPF_sp_mat_mul_cplx (float *x, int r1, int c1, float
*y, int c2, float *r)
3-6
Matrix multiplication 4-64
Matrix transpose 4-65
Complex matrix multiplication 4-66
DSPLIB Function Tables
Table 3-8. Miscellaneous
Functions Description Page
void DSPF_sp_blk_move (float*x, float*r, int nx) Move a block of memory 4-69
void DSPF_blk_eswap16 (void *x, void *r, int nx) Endianswap a block of 16-bit
values
void DSPF_blk_eswap32 (void *x, void *r, int nx) Endian-swap a block of 32-bit
values
void DSPF_blk_eswap64 (void *x, void *r, int nx) Endian-swap a block of 64-bit
values
void DSPF_fltoq15 (float *x, short *r, int nx) Float to Q15 conversion 4-75
float DSPF_sp_minerr (float *GSP0_TABLE,float
*errCoefs, int *max_index)
void DSPF_q15tofl (short *x, float *r, int nx)
Minimum energy error search 4-76
Q15 to float conversion 4-78
4-70
4-71
4-73
3-7DSPLIB Function Tables
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-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Filtering and Convolution 4-38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5 Math 4-52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6 Matrix 4-64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7 Miscellaneous 4-69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-1
DSPF_sp_lms
4.1 Adaptive Filtering
DSPF_sp_lms
Single-precision floating-point LMS algorithm
Function float DSPF_sp_lms (float *x, float *h, float *desired, float *r, float adaptrate,
float error, int nh, int nr)
Arguments
x Pointer to input samples
h Pointer to the coefficient array
desired Pointer to the desired output array
r Pointer to filtered output array
adaptrate Adaptation rate
error Initial error
nh Number of coefficients
nr Number of output samples
Description The DSPF_sp_lms implements an LMS adaptive filter. Given an actual input
signal and a desired input signal, the filter produces an output signal, the final
coefficient values, and returns the final output error signal.
Algorithm This is the C equivalent of the assembly code without restrictions. Note that
the assembly code is hand optimized and restrictions may apply.
float DSPF_sp_lms(float *x,float *h,float *y,int nh,float
*d,float ar, short nr, float error)
{
int i,j;
float sum;
for (i = 0; i < nr; i++)
{
for (j = 0; j < nh; j++)
{
h[j] = h[j] + (ar*error*x[i+j-1]);
}
sum = 0.0f;
for (j = 0; j < nh; j++)
4-2
Special Requirements
Implementation Notes
DSPF_sp_lms
{
sum += h[j] * x[i+j];
}
y[i] = sum;
error = d[i] - sum;
}
return error;
}
- The inner loop counter must be a multiple of 6 and ≥6.
- Little endianness is assumed.
- Extraneous loads are allowed in the program.
- The coefficient array is assumed to be in reverse order; i.e., h(nh-1),
h(nh-2), ..., h(0) will hold coefficients h0, h1, ..., hnh-1, repectively.
- The inner loop is unrolled six times to allow update of six coefficients in the
kernel.
- The outer loop has been unrolled twice to enable use of LDDW for loading
the input coefficients.
Benchmarks
- LDDW instruction is used to load the coefficients.
- Register sharing is used to make optimal use of available registers.
- The outer loop instructions are scheduled in parallel with epilog and prolog
wherever possible.
- The error term needs to be computed in the outer loop before a new itera-
tion of the inner loop can start. As a result the prolog cannot be placed in
parallel with epilog (after the loop kernel).
- Pushing and popping variables from the stack does not really add any
overhead except increase stack size. This is because the pops and
pushes are done in the delay slots of the outer loop instructions.
- Endianess: This code is little endian.
- Interruptibility: This code is interrupt-tolerant but not interruptible.
Cycles (nh + 35) nr + 21
eg. for nh = 36 and nr = 64
cycles = 4565
Code size
1376
(in bytes)
4-3 DSPLIB Reference
DSPF_sp_autocor
4.2 Correlation
DSPF_sp_autocor
Single-precision autocorrelation
Function void DSPF_sp_autocor (float * restrict r, const float * restrict x, int nx, int nr)
Arguments
r Pointer to output array of autocorrelation of length nr
x Pointer to input array of length nx+nr. Input data must be
padded with nr consecutive zeros at the beginning.
nx Length of autocorrelation vector
nr Length of lags
Description This routine performs the autocorrelation of the input array x. It is assumed that
the length of the input array, x, is a multiple of 2 and the length of the output
array, r, is a multiple of 4. The assembly routine computes 4 output samples
at a time. It is assumed that input vector x is padded with nr no of zeros in the
beginning.
Algorithm This is the C equivalent of the assembly code. Note that the assembly code
is hand optimized and restrictions may apply.
void DSPF_sp_autocor(float * restrict r, const float *
restrict x,
int nx, int nr)
{
int i,k;
float sum;
for (i = 0; i < nr; i++)
{
sum = 0;
for (k = nr; k < nx+nr; k++)
sum += x[k] * x[k-i];
r[i] = sum ;
}
}
Special Requirements
- nx is a multiple of 2 and greater than or equal to 4.
4-4
- nr is a multiple of 4 and greater than or equal to 4.
- nx is greater than or equal to nr
- x is double-word aligned.
Implementation Notes
Benchmarks
DSPF_sp_autocor
- The inner loop is unrolled twice and the outer loop is unrolled four times.
- Endianess: This code is little endian.
- Interruptibility: This code is interrupt-tolerant but not interruptible.
Cycles (nx/2) * nr + (nr/2) * 5 + 10 - (nr * nr)/4 + nr
For nx=64 and nr=64, cycles=1258
For nx=60 and nr=32, cycles=890
Code size
(in bytes)
512
4-5 DSPLIB Reference
Loading...