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.
Preface Read This First About This Manual The TMS320C6000t DSK Board Support Library (BSL) is a set of application programming interfaces (APIs) used to configure and control all on-board devices. 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.
How to UseConventions This Manual/ Related Documentation From Texas Instruments Notational 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.
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.
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 1.2 1.3 2 AD535 API Module Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 AD535 API Reference . . . . . . . . . . . . . . . . . . . . . . . .
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 5.2 6 FLASH API Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tables Tables 1–1. BSL Modules and Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2. BSL Support Library Name and Symbol Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3. BSL API Module Support for 6711 DSK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1. AD535 API Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1 BSL Overview This chapter provides an overview of the board support library (BSL), describes 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BSL Introduction 1.1 BSL Introduction The BSL provides a C-language interface for configuring and controlling all onboard devices. The library consists of discrete modules that are built and archived into a library file. Each module represents an individual API and is referred 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.
BSL API Modules 1.2 BSL API Modules For each on-board device, one header file and one source file will be generated 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 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 1.2.
BSL Project Settings 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 and have to be included in your program 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 defined using the –d switch.
Chapter 2 AD535 API Module This chapter provides a description of the AD535 API module, lists the individual 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 using AD535_open(). Once opened, use the device handle to call the other API functions. The codec may be configured by passing an AD535_Config structure to AD535_config(). Table 2–1.
AD535 API Module Description Syntax Type Description Page AD535_write F Writes data to be sent 2-16 AD535_writeHwi F Writes data to be sent 2-17 AD535_writeReg F Writes to the AD535 control registers 2-17 Note: F = Function; C = Constant; S = Structure; T = Typedef AD535 API Module 2-3
AD535_Config 2.2 AD535 API Reference AD535_close Closes codec channel Function Void AD535_close( AD535_Handle hAD535 ); Arguments hAD535 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.
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.
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.
AD535_getMcbspHandle AD535_getMcbsp Handle Returns McBSP 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.
AD535_Id Description This AD535_Id structure is used to allocate a codec channel. You create and initialize this structure, then pass its address to the AD535_open() function. Also, this structure allows you to access to the McBSP handle through the AD535_getMcbspHandle() function after calling AD535_open(). If you wish to use the AD535 codec implemented on C6711DSK you can pass the predefined pointer AD535_ON_6711DSK. The predefined pointer AD535_locald associates the codec to the mcbsp0 directly.
AD535_inGain AD535_inGain Sets AD535’s input gain Function void AD535_inGain( AD535_Handle hAD535, float inGain ); Arguments hAD535 Handle to codec channel, see AD535_open() inGain ADC input gain. Return Value none Description Sets the AD535’s input gain. 6711 DSK - AD535_GAIN_MUTE - AD535_GAIN_0DB - –36 dB <= inGain <= 12 dB (in 1.5 dB steps) Example AD535_inGain (hAD535,6.
AD535_modifyReg AD535_modifyReg Modifies specified control register Function void AD535_modifyReg( AD535_Handle hAD535, AD535_Reg ad535Register, Uint32 val, Uint32 mask ); Arguments hAD535 ad535Register Handle to codec channel, see AD535_open() Control register enumeration: AD535_REG_CTRL0 AD535_REG_CTRL1 AD535_REG_CTRL2 AD535_REG_CTRL3 AD535_REG_CTRL4 AD535_REG_CTRL5 - val Value to be masked into register mask Bit-value mask.
AD535_open AD535_open Opens codec channel Function AD535_Handle AD535_open ( AD535_Id *myId ); Arguments myId Pointer to an object of type AD535_Id. This object contains the McBSP channel number and a McBSP handle. C6711 DSK If you want to use the local codec, you may pass the predefined pointer AD535_ON_6711DSK. If you want to use another codec you must create your own AD535_Id.
AD535_powerDown AD535_outGain Sets AD535’s output gain Function void AD535_outGain( AD535_Handle hAD535, float outGain ); Arguments hAD535 Handle to codec channel, see AD535_open() outGain DAC output gain. Return Value none Description Sets the AD535’s output gain. 6711 DSK - AD535_GAIN_MUTE - AD535_GAIN_0DB - –36 dB <= outGain <= 12 dB (in 1.
AD535_read AD535_read Returns value of ouput from ADC Function int AD535_read( AD535_Handle hAD535 ); Arguments hAD535 Handle to codec channel, see AD535_open() Return Value int Value returned from output of ADC. Description Returns the value of the ouput from the ADC.
AD535_readReg ad535Register Control register enumeration: - AD535_REG_CTRL0 - AD535_REG_CTRL1 - AD535_REG_CTRL2 - AD535_REG_CTRL3 - AD535_REG_CTRL4 - AD535_REG_CTRL5 Return Value Uint32 Value of specified control register. Description Returns the value of the specified control register.
AD535_reset AD535_reset Asserts software reset Function void AD535_reset( AD535_Handle hAD535 ); Arguments hAD535 Return Value none Description Asserts a software reset and sets all the registers to their power-on default values. Example AD535_reset(hAD535); Handle to codec channel, see AD535_open() AD535_SUPPORT Compile time constant Constant AD535_SUPPORT Description Compile time constant that has a value of 1 if the board supports the AD535 module and 0 otherwise.
AD535_writeReg AD535_writeHwi Writes value to input of DAC Function void AD535_writeHwi( AD535_Handle hAD535, int val ); Arguments hAD535 Handle to codec channel, see AD535_open() val Value to be written to DAC. Return Value none Description Writes value to the input of the DAC. Unlike the AD535_write API, it does not use polling to establish that the McBSP is ready to write another sample. Rather, it requires the McBSP to already be ready.
AD535_writeReg Description Writes value to the specified control register. 6711 DSK Note: Only the Voice channel is available on this board. This means the changes to control registers 0, 1, and 2 will have no effect on the operation of the codec. Example /* Set up 10.
Chapter 3 BOARD API Module This chapter 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. Topic Page 3.1 BOARD API Module Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3.2 BOARD API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BOARD API Module Description 3.1 BOARD API Module Description The BOARD module is where we put board-specific content. This module has the potential to grow in the future as more boards are placed on the market. Currently, the module has some API functions for register access such as BOARD_readReg(), and BOARD_writeReg(). A predefined symbol is associated with each EVM/DSK, for example, BOARD_6711DSK ( –d switch for compiler options setting) Table 3–1.
BOARD_SUPPORT 3.2 BOARD API Reference BOARD_readReg Returns value of specified memory-mapped register Function Uint32 BOARD_readReg( BOARD_Reg boardRegister ); Arguments boardRegister Register enumeration C6711 DSK - BOARD_REG_IOPORT Return Value Uint32 Returns specified register value Description Returns the value of the specified memory-mapped register.
BOARD_writeReg BOARD_writeReg Writes value to specified memory-mapped register Function void BOARD_writeReg( BOARD_Reg boardRegister, Uint32 val ); Arguments boardRegister Register enumeration C6711 DSK - BOARD_REG_IOPORT val Value to be written to specified register. Return Value none Description Writes the value to the specified memory-mapped register.
Chapter 4 BSL API Module This chapter provides a description of the BSL API module and includes a reference section showing the single API function within this module. Topic Page 4.1 BSL API Module Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 4.2 BSL API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BSL API Module Description 4.1 BSL API Module Description The BSL module serves to initialize the API modules supported by the board.The following unique function has to be called before using the API functions: BSL_init () Table 4–1.
BSL_init 4.2 BSL API Reference BSL_init Initializes all programmable modules on board Function void BSL_init(); Arguments none Return Value none Description This function initializes all of the programmable modules on the board.
Chapter 5 DIP API Module This chapter 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. Topic Page 5.1 DIP API Module Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 5.2 DIP API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DIP API Module Description 5.1 DIP API Module Description This module has the following single API for reading DIP switch positions: DIP_get(dip#) returns a boolean value {0,1}. Table 5–1.
DIP_SUPPORT 5.2 DIP API Reference DIP_get Returns current value of specified DIP switch Function Uint32 DIP_get( Uint32 dipNum ); Arguments dipNum Specifies which DIP switch to be read, can be one of the following: - DIP_1 - DIP_2 - DIP_3 - … Return Value Uint32 Current value of the specified DIP switch. - 0 = DIP switch position is off. - 1 = DIP switch position is on. Description Returns the current value of the specified DIP switch.
Chapter 6 FLASH API Module This chapter 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. Topic Page 6.1 FLASH API Module Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 6.2 FLASH API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FLASH API Module Description 6.1 FLASH API Module Description The FLASH module allows access to on-board flash and executes data memory manipulation by using the following three functions: FLASH_read(), FLASH_write() and FLASH_erase() For the 6711 DSK, the 128KB FLASH is split into 128 bytes per page. Table 6–1.
FLASH_checksum 6.2 FLASH API Reference FLASH_checksum Returns checksum of specified Flash data Function Uint32 FLASH_checksum( Uint32 locator, Uint32 length ); Arguments locator Addressing and page information for location in Flash memory. C6711 DSK - FLASH_START_ADDR - FLASH_PAGE_ADDR(x) :(x)– page number - 32-bit FLASH address length Length in bytes of data to be read. This is limited by the size of the Flash memory.
FLASH_erase FLASH_erase Erases specified segment of Flash memory Function void FLASH_erase( Uint32 locator, Uint32 length ); Arguments locator Addressing and page information for location in Flash memory. C6711 DSK - FLASH_START_ADDR - FLASH_PAGE_ADDR(x) :(x)– page number - 32-bit Flash address length Length in bytes of data to be erased. This is limited by the size of the Flash memory.
FLASH_read FLASH_read Reads data from FLASH address Function void FLASH_read( Uint32 locator, Uint32 dst, Uint32 length ); Arguments locator Addressing and page information for location in Flash memory. C6711 DSK - FLASH_START_ADDR - FLASH_PAGE_ADDR(x) :(x)– page number - 32-bit FLASH address dst Destination address length Length in bytes of data to be read. This is limited by the size of the Flash memory.
FLASH_SUPPORT FLASH_SUPPORT Compile time constant Constant FLASH_SUPPORT Description Compile time constant that has a value of 1 if the board supports the FLASH module and 0 otherwise. You are not required to use this constant. Currently, all devices support this module.
FLASH_write Description Writes data to the Flash address (locator) from a source address (src). This function is limited by the page length of the Flash memory. Note: This function does not affect unspecified segments of Flash. For example, altering the lower half of a page of Flash memory does not change the value of the upper half page.
Chapter 7 LED API Module This chapter 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. Topic Page 7.1 LED API Module Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 7.2 LED API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LED API Module Description 7.1 LED API Module Description This module has a simple API for configuring on-board LED outputs. Three states can be set by the following functions: - LED_on(led#) - LED_off(led#) - LED_toggle(led#) Table 7–1.
LED_on 7.2 LED API Reference LED_off Turns off specified LED Function void LED_off( Uint32 LedNum ); Arguments LedNum Return Value none Description Turns off the specified LED. C6711 DSK - LED_1 = USER_LED1 - LED_2 = USER_LED2 - LED_3 = USER_LED3 - LED_ALL = all user LEDs Example If you want to turn off LED # 1 use: LED_off(LED_1); LED_on Turns on specified LED Function void LED_on( Uint32 LedNum ); Arguments LedNum Return Value none Specifies which LED to be turned off.
LED_SUPPORT Description Turns on the specified LED. C6711 DSK - LED_1 = USER_LED1 - LED_2 = USER_LED2 - LED_3 = USER_LED3 - LED_ALL = all user LEDs Example If you want to turn on LED # 1 use: LED_on(LED_1); LED_SUPPORT Compile time constant Constant LED_SUPPORT Description Compile time constant that has a value of 1 if the board supports the LED module and 0 otherwise. You are not required to use this constant. Currently, all devices support this module.
Appendix AppendixAA Glossary A AD535: The audio codec API module. Currently supported by the 6711 DSK. address: The location of program code or data stored; an individually accessible memory location. A-law companding: See compress and expand (compand). API: See application programming interface. API module: A set of API functions designed for a specific purpose.
Glossary block: The three least significant bits of the program address. These correspond to the address within a fetch packet of the first instruction being addressed. BOARD: The BOARD-specific API Module. board support library (BSL): The BSL is a set of application programming interfaces (APIs) consisting of target side DSP code used to configure and control board level peripherals. boot: The process of loading a program into program memory.
Glossary clock cycle: A periodic or sequence of events based on the input from the external clock. clock modes: Options used by the clock generator to change the internal CPU clock frequency to a fraction or multiple of the frequency of the input clock signal. code: A set of instructions written to perform a task; a computer program or part of a program. codec: Coder-decoder, or compression/decompression. A device that codes in one direction of transmission and decodes in another direction of transmission.
Glossary device ID: Configuration register that identifies each peripheral component interconnect (PCI). digital signal processor (DSP): A semiconductor that turns analog signals—such as sound or light—into digital signals, which are discrete or discontinuous electrical impulses, so that they can be manipulated. DIP: The DIP Switches API Module.
Glossary external interrupt: A hardware interrupt triggered by a specific value on a pin. external memory interface (EMIF): Microprocessor hardware that is used to read to and write from off-chip memory. F fetch packet: A contiguous 8-word series of instructions fetched by the CPU and aligned on an 8-word boundary. flag: A binary status indicator whose state indicates whether a particular condition has occurred or is in effect. FLASH: The FLASH ROM API Module. frame: An 8-word space in the cache RAMs.
Glossary indirect addressing: An addressing mode in which an address points to another pointer rather than to the actual data; this mode is prohibited in RISC architecture. instruction fetch packet: A group of up to eight instructions held in memory for execution by the CPU. internal interrupt: A hardware interrupt caused by an on-chip peripheral. internal peripherals: Devices connected to and controlled by a host device.
Glossary little endian: An addressing protocol in which bytes are numbered from right to left within a word. More significant bytes in a word have higher-numbered addresses. Endian ordering is specific to hardware and is determined at reset. See also big endian. M µ-law companding: See compress and expand (compand). maskable interrupt: A hardware interrupt that can be enabled or disabled through software. MCBSP: See multichannel buffered serial port; see also MCBSP module.
Glossary P peripheral: A device connected to and usually controlled by a host device. program cache: A fast memory cache for storing program instructions allowing for quick execution. program memory: Memory accessed through the C6x’s program fetch interface. PWR: Power; see PWR module. PWR module: PWR is an API module that is used to configure the powerdown control registers, if applicable, and to invoke various power-down modes.
Glossary synchronous dynamic random-access memory (SDRAM): RAM whose contents is refreshed periodically so the data is not lost. Transfer of data is at a fixed rate relative to the clock speed of the device. syntax: The grammatical and structural rules of a language. All higher-level programming languages possess a formal syntax. system software: The blanketing term used to denote collectively the chip support libraries and board support libraries.
Index Index A AD535 API module, 2-1 API constant, 2-5 AD535_SUPPORT, 2-16 API functions AD535_close, 2-5 AD535_config, 2-6 AD535_getMcbspHandle, 2-8 AD535_inGain, 2-10 AD535_micGain, 2-10 AD535_modifyReg, 2-11 AD535_open, 2-12 AD535_outGain, 2-13 AD535_powerDown, 2-13 AD535_read, 2-14 AD535_readReg, 2-14 AD535_reset, 2-16 AD535_write, 2-16 AD535_writeReg, 2-17 API structures AD535_Config, 2-5 AD535_Id, 2-8 API summary table, 2-2 description, 2-2 B BOARD API module, 3-1 API constant, 3-3 BOARD_SUPPORT, 3-3
Index L LED API module, 7-1 API constant, 7-3 LED_SUPPORT, 7-4 Index-2 API functions LED_off, 7-3 LED_on, 7-3 LED_toggle, 7-4 API summary table, 7-2 description, 7-2
