Texas Instruments TMS320C6000 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 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  2001, Texas Instruments Incorporated

About This Manual

Preface

Read This First

The TMS320C6000t DSK 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 TMS320C6711t Developers 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
TMS320C6000t board support library (BSL) as follows:

- Chapter 1 provides an overview of the BSL, includes a table showing BSL

- Each additional chapter discusses an individual BSL API module and pro-

API module support for various C6000 devices, and lists the API modules.

vides:

J A description of the API module
J A table showing the APIs within the module and a page reference for

more specific information

J A 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.

Read This First

iii

How to Use This Manual

Notational Conventions / Related Documentation From Texas Instruments

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.

iv

How to Use This Manual

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.

Read This First

v

Contents

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vii

Contents

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

viii

Tables

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

ix

Chapter 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1

BSL Introduction

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.

1-2

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

BSL API Modules

Board
Module

BSL Top-level module: Initialization of the BSL bsl_bsl.h BSL_init
BOARD Board-specific module – can call CSL at run-

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

Description Include File

bsl_board.h BOARD_SUPPORT

time

LED module bsl_led.h LED_SUPPORT

Module Support
Symbol

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 Overview

1-3

BSL API Modules

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.

1-4

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.

BSL Project Settings

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.

BSL Overview

1-5

Chapter 2

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-1

AD535 API Module Description

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­ing AD535_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

AD535_config F Sets up the AD535 codec using the register value

passed in
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
AD535_Id S The AD535 Identity Structure used to allocate the

Codec device and the associated McBSP
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

2-5

2-6

2-8

2-8

AD535_readReg F Reads the contents of AD535 control registers 2-14
AD535_reset F Resets the AD535 2-16
AD535_SUPPORT

2-2

C A compile time constant whose value is 1 if the board

supports the AD535 module

2-16

AD535 API Module Description

PageDescriptionTypeSyntax

AD535_write F Writes data to be sent 2-16
AD535_writeHwi F Writes data to be sent 2-17
AD535_writeReg

Note: F = Function; C = Constant; S = Structure; T = Typedef

F Writes to the AD535 control registers 2-17

AD535 API Module

2-3

2.2 AD535 API Reference

AD535_Config

AD535_close

Closes codec channel

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);

AD535_Config

Configuration structure used to set up codec channel

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 API Module

2-5

AD535_config

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);

AD535_config

Function Void AD535_config(

Arguments hAD535 Handle to codec channel, see AD535_open()

Return Value none
Description Sets up the AD535 using the configuration structure. The values of the

Example AD535_Config myConfig = {

Sets up AD535 using configuration structure

AD535_Handle hAD535,
AD535_Config *config
);

Config Pointer to an initialized configuration structure, see

AD535_Config

structure are written to the AD535 control registers.

AD535_LOOPBACK_DISABLE,
AD535_MICGAIN_OFF,
AD535_GAIN_0DB,
AD535_GAIN_0DB
};
AD535_config(hAD535,&myConfig);

AD553_freeMcbsp

Function Void AD535_freeMcbsp(

Arguments port McBSP port: MCBSP_DEV0, MCBSP_DEV1
Return Value none

2-6

Sets the FREE bit of an McBSP serial port to 1

int port
)

AD553_freeMcbsp

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 API Module

2-7