Texas Instruments TMS320C6000 DSP User manual

TMS320C6000 DSK
Board Support Library
API User’s Guide
Literature Number: SPRU432A
October 2001
Printed on Recycled Paper

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 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.
Mailing Address:
Texas Instruments
Post Office Box 655303
Dallas, Texas 75265
Copyright 2001, Texas Instruments Incorporated

iii
Read This First
Preface
Read This First
About This Manual
The TMS320C6000tDSK Board Support Library (BSL) is a set of application
programming interfaces (APIs) used to configure and control all on-board de-
vices. It is intended to make it easier for developers by eliminating much of the
tedious grunt-work usually needed to get algorithms up and running in a real
system.
Some of the advantages offered by the BSL include: device ease of use, a level
of compatibility between devices, shortened development time, portability,
some standardization, and hardware abstraction. A version of the BSL is avail-
able for the TMS320C6711tDevelopers Starter Kit (DSK).
This document is organized as follows:
-Introduction – a high level overview of the BSL
-Six BSL API module chapters
-Glossary
How to Use This Manual
The information in this document describes the contents of the
TMS320C6000tboard support library (BSL) as follows:
-Chapter 1 provides an overview of the BSL, includes a table showing BSL
API module support for various C6000 devices, and lists the API modules.
-Each additional chapter discusses an individual BSL API module and pro-
vides:
JA description of the API module
JA table showing the APIs within the module and a page reference for
more specific information
JA module API Reference section in alphabetical order listing the BSL
API functions, enumerations, type definitions, structures, constants,
and global variables. Examples are given to show how these elements
are used.

How to Use This Manual
iv
Notational Conventions
This document uses the following conventions:
-Program listings, program examples, and interactive displays are shown
in a special typeface.
-In syntax descriptions, the function or macro appears in a bold typeface
and the parameters appear in plainface within parentheses. Portions of a
syntax that are in bold should be entered as shown; portions of a 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.
-TMS320C6000 devices are referred to throughout this reference guide as
C6201, C6202, etc.
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 Instru-
ments 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 Chip Support Library API User’s Guide (literature number
SPRU401) describes the chip support library (CSL), a library dedicated
for initialization and control of the on-chip peripherals.
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.
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, clock-
ing and phase-locked loop (PLL), and the power-down modes.
Notational Conventions / Related Documentation From Texas Instruments

How to Use This Manual
v
Read This First
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.
This C compiler accepts ANSI standard C source code and produces as-
sembly language source code for the ’C6000 generation of devices. The
assembly optimizer helps you optimize your assembly code.
TMS320C62x DSP Library (literature number SPRU402) describes the 32
high-level, C-callable, optimized DSP functions for general signal proc-
essing, math, and vector operations.
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.

Contents
vii
Contents
1 BSL Overview 1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides an overview of the board support library (BSL), describes its beneficial features, and
lists each of its API modules.
1.1 BSL Introduction 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 BSL API Modules 1-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 BSL API Module Support 1-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 Using BSL Handles 1-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 BSL Project Settings 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 User’s Program Setting 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Compiler Options 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3 Linker Options 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 AD535 API Module 2-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a description of the AD535 API module, lists the individual APIs within the module,
and includes a reference section with the API functions, structures, and constants that are ap-
plicable to this module.
2.1 AD535 API Module Description 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 AD535 API Reference 2-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3 BOARD API Module 3-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a description of the BOARD API module, lists the individual APIs within the module,
and includes a reference section showing the API functions and constants that are applicable
to this module.
3.1 BOARD API Module Description 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 BOARD API Reference 3-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4 BSL API Module 4-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a description of the BSL API module and includes a reference section showing the
single API function within this module.
4.1 BSL API Module Description 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 BSL API Reference 4-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents
viii
5 DIP API Module 5-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a description of the DIP API module, lists the individual APIs within the module, and
includes a reference section showing the single API function and constant within this module.
5.1 DIP API Module Description 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 DIP API Reference 5-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6 FLASH API Module 6-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a description of the FLASH API module, lists the individual APIs within the module,
and includes a reference section showing the API functions and constants that are applicable
to this module.
6.1 FLASH API Module Description 6-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 FLASH API Reference 6-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7 LED API Module 7-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides a description of the LED API module, lists the individual APIs within the module, and
includes a reference section showing the API functions and constants that are applicable to this
module.
7.1 LED API Module Description 7-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 LED API Reference 7-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Glossary A-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Tables
ix
Contents
Tables
1–1. BSL Modules and Include Files 1-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1–2. BSL Support Library Name and Symbol Conventions 1-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1–3. BSL API Module Support for 6711 DSK 1-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2–1. AD535 API Summary 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3–1. BOARD API Summary 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4–1. BSL API Function 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–1. DIP API Summary 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6–1. FLASH API Summary 6-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7–1. LED API Summary 7-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1
BSL Overview
This chapter provides an overview of the board support library (BSL), de-
scribes its beneficial features, and lists each of its API modules.
Topic Page
1.1 BSL Introduction 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 BSL API Modules 1-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 BSL Project Settings 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1

BSL Introduction
1-2
1.1 BSL Introduction
The BSL provides a C-language interface for configuring and controlling all on-
board devices. The library consists of discrete modules that are built and ar-
chived into a library file. Each module represents an individual API and is re-
ferred to simply as an API module. The module granularity is architected such
that each device is covered by a single API module except the I/O Port Module,
which is divided into two API modules: LED and DIP.
How The BSL Benefits You
The BSL’s beneficial features include device ease of use, shortened develop-
ment time, portability, hardware abstraction, and a level of standardization and
compatibility among devices. In general, the BSL makes it easier for you to get
your algorithms up and running in the shortest length of time.

BSL API Modules
1-3
BSL Overview
1.2 BSL API Modules
For each on-board device, one header file and one source file will be gener-
ated with the following names: bsl_device.h and bsl_device.c.
Also, a library will be built for a given board:
i.e: bsl6711dsk.lib
Note : The soource files.c are archived into a single source file bsl.src.
Table 1–1 provides a current list of BSL API Modules.
Table 1–1. BSL Modules and Include Files
Board
Module Description Include File Module Support Symbol
BSL Top-level module: Initialization of the BSL bsl_bsl.h BSL_init
BOARD Board-specific module –can call CSL at run-
time bsl_board.h BOARD_SUPPORT
AD535 Audio codec module (C6711 DSK) bsl_ad535.h AD535_SUPPORT
DIP Dip switches module bsl_dip.h DIP_SUPPORT
FLASH Flash ROM module bsl_flash.h FLASH_SUPPORT
LED LED module bsl_led.h LED_SUPPORT
Interdependencies
Although each API module is unique, there exists some interdependency be-
tween the CSL (Chip Support Library) and BSL modules. For example, the
AD535 module depends on the MCBSP module because MCBSP0 is dedi-
cated to serial communication.
1.2.1 BSL API Module Support
Not all API modules are supported on all boards. For example, the AIC10 mod-
ule is not supported on the C6711 DSK because the board does not have an
AIC10 codec. When an API module is not supported, all of its header file infor-
mation is conditionally compiled out, meaning the declarations will not exist.
Because of this, calling an AIC10 API function on a board that does not support
AIC10 results in a compiler and/or linker error.
Note: AIC10 codec is implemented on C5510evm.

BSL API Modules
1-4
6711 DSK Module Support
Table 1–3 shows which board each API module is supported on. Currently, all
modules described in the following chapters are supported by the C6711 DSK.
In the future, more APIs supported by other platforms will be added to the BSL.
Table 1–2. BSL Support Library Name and Symbol Conventions
Board BSL library BSL Symbol CSL library CSL symbol
6711DSK bsl6711.lib BOARD_6711DSK csl6711.lib CHIP_6711
Table 1–3. BSL API Module Support for 6711 DSK
Module 6711 DSK
AD535 X
BOARD X
DIP X
FLASH X
LED X
1.2.2 Using BSL Handles
Handles are required for devices present more than once. For example, only
one AD535 codec is implemented on-board and associated with mcbsp0;
however, you can use a second AD535 implemented on a daughter board and
make data transfers through mcbsp1.

BSL Project Settings
1-5
BSL Overview
1.3 BSL Project Settings
1.3.1 User’s Program Setting
Due to the interdependancies between CSL and BSL, the CSL is initialized by
calling the CSL_init() function followed by the BSL initialization function,
BSL_init().
Also, the two header files <csl.h> and <bsl.h> have to be included in your pro-
gram in order for you to have access to the BSL APIs.
1.3.2 Compiler Options
In the Compiler Option window, the Chip and Board symbols have to be de-
fined using the –d switch. For example,
–dCHIP_6711 –dBOARD_6711DSK
Also, the paths of the “Include”folder containing the BSL and CSL header files
have to be set with the –i switch.
1.3.3 Linker Options
The paths of the CSL and BSL libraries have to be defined. The two libraries
are named, respectively, csl6711.lib and bsl6711dsk.lib.
Note: Device Identification Symbol
When using the BSL, it is up to the user to define a project-wide symbol from
a predetermined set to identify which device is being used. This board identi-
fication symbol is then used in the BSL header files to conditionally define
the support symbols. (See Section 3.2, API Reference, for more information.

2-1
AD535 API Module
This chapter provides a description of the AD535 API module, lists the individ-
ual APIs within the module, and includes a reference section showing the API
functions, structures, and constants that are applicable to this module.
Topic Page
2.1 AD535 API Module Description 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 AD535 API Reference 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 2

AD535 API Module Description
2-2
2.1 AD535 API Module Description
The AD535 module (audio codec supported by the C6711 DSK) serves as a
level of abstraction such that it works the same for all AD535s supported on
TI EVM/DSKs.
To use an AD535 device, you must first open it and obtain a device handle us-
ingAD535_open(). Once opened, use the device handle to call the other API
functions. The codec may be configured by passing an AD535_Config struc-
ture to AD535_config().
Table 2–1. AD535 API Summary
Syntax Type Description Page
AD535_close F Closes the AD535 module 2-5
AD535_Config S The AD535 configuration structure used to set up an
AD535 codec 2-5
AD535_config F Sets up the AD535 codec using the register value
passed in 2-6
AD535_freeMcbsp F Sets the FREE bit of an McBSP serial port to 1. 2-6
AD535_getMcbspHandle F Returns the Handle of the McBSP associated with the
codec previously opened 2-8
AD535_Id S The AD535 Identity Structure used to allocate the
Codec device and the associated McBSP 2-8
AD535_inGain F Sets the AD535’s input gain 2-10
AD535_micGain F Sets the microphone preamplifier gain 2-10
AD535_modifyReg F Modifies the AD535 control registers 2-11
AD535_open F Opens an AD535 codec for use 2-12
AD535_outGain F Sets the AD535’s output gain 2-13
AD535_powerDown F Puts the AD535 in power-down mode 2-13
AD535_read F Reads received data (voice channel) 2-14
AD535_readHwi F Reads received data (voice channel) 2-14
AD535_readReg F Reads the contents of AD535 control registers 2-14
AD535_reset F Resets the AD535 2-16
AD535_SUPPORT CA compile time constant whose value is 1 if the board
supports the AD535 module 2-16

AD535 API Module Description
2-3
AD535 API Module
PageDescriptionTypeSyntax
AD535_write F Writes data to be sent 2-16
AD535_writeHwi F Writes data to be sent 2-17
AD535_writeReg FWrites to the AD535 control registers 2-17
Note: F = Function; C = Constant; S = Structure; T = Typedef

AD535_Config
2-5
AD535 API Module
2.2 AD535 API Reference
Closes codec channel
AD535_close
Function Void AD535_close(
AD535_Handle hAD535
);
Arguments hAD535 Handle to codec channel, see AD535_open()
Return Value none
Description This function closes a codec channel previously opened via
AD535_open(). The registers for the codec are set to their power-on
defaults.
Example AD535_close(hAD535);
Configuration structure used to set up codec channel
AD535_Config
Structure AD535_Config
Members AD535_Loopback lb_mode Loopback mode:
-AD535_LOOPBACK_DISABLE
-AD535_LOOPBACK_ANALOG
-AD535_LOOPBACK_DIGITAL
AD535_MicGain mic_gain Microphone preamp gain:
-AD535_MICGAIN_OFF
-AD535_MICGAIN_ON
Float in_gain ADC input gain:
-AD535_GAIN_MUTE
-AD535_GAIN_0DB
-–36 dB <= gain <= 12 dB
(in 1.5 dB steps)
Float out_gain DAC output gain:
-AD535_GAIN_MUTE
-AD535_GAIN_0DB
-–36 dB <= gain <= 12 dB
(in 1.5 dB steps)

AD535_config
2-6
Description This is the AD535 configuration structure used to set up a codec channel.
You create and initialize this structure and then pass its address to the
AD535_config() function.
Example AD535_Config myConfig = {
AD535_LOOPBACK_DISABLE,
AD535_MICGAIN_OFF,
AD535_GAIN_0DB,
AD535_GAIN_0DB
};
AD535_config(hAD535,&myConfig);
Sets up AD535 using configuration structure
AD535_config
Function Void AD535_config(
AD535_Handle hAD535,
AD535_Config *config
);
Arguments hAD535 Handle to codec channel, see AD535_open()
Config Pointer to an initialized configuration structure, see
AD535_Config
Return Value none
Description Sets up the AD535 using the configuration structure. The values of the
structure are written to the AD535 control registers.
Example AD535_Config myConfig = {
AD535_LOOPBACK_DISABLE,
AD535_MICGAIN_OFF,
AD535_GAIN_0DB,
AD535_GAIN_0DB
};
AD535_config(hAD535,&myConfig);
Sets the FREE bit of an McBSP serial port to 1
AD553_freeMcbsp
Function Void AD535_freeMcbsp(
int port
)
Arguments port McBSP port: MCBSP_DEV0, MCBSP_DEV1
Return Value none

AD553_freeMcbsp
2-7
AD535 API Module
Description Sets 1 to the FREE field of the SPCR register of the given McBSP port.
When FREE is set to 1, the serial clocks continue to run during an
emulation halt.
Example /* Set the FREE bit of Mcbsp serial port 0 */
AD535_freeMcbsp (MCBSP_DEV0);

AD535_getMcbspHandle
2-8
Returns McBSP Handle
AD535_getMcbsp
Handle
Function Mcbsp_Handle AD535_getMcbspHandle(
AD535_Handle hAD535,
);
Arguments hAD535 Handle to codec channel, see AD535_open()
Return Value Mcbsp_handle Handle to the opened McBSP associated to the
number of McBSP.
Description Returns the McBSP Handle associated with the McBSP used for AD535
communication.
Note: The Mcbsp_Handle type is defined in the Chip Suppport Library
(CSL) and created by the internal call of the MCBSP_open() function.
Example Mcbsp_Handle hMcbsp;
hMcbsp = AD535_getHandleMcbsp(hAD535);
Allocates codec channel
AD535_Id
Structure AD535_Id
Members Typedef Struct {
Struct {
int mcbsp_no;
The typedef structure AD535_Id includes 2
substructures such as Id and Obj
structures
} Id;
Struct {
Boolean allocated;
MCBSP_Handle
The internal structure Id contains the field
mcbsp_no. The member mcbsp_no
contains the number of the serial port you
wish to use.
hMcbsp;
} Obj;
} AD535_Id
The internal structure Obj contains the
boolean field to allocate the codec and the
McBSP handle associated with the number
of the McBSP which will be open
“mcbsp_no”.