Texas Instruments TMS320C55 Series Reference Manual
TMS320C55x DSP/BIOS 5.32
Application Programming Interface
(API) Reference Guide
Literature Number: SPRU404N
September 2007
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 com plete. 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 qualit y 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 licens e, either ex press or implied, is granted under any TI patent right, copyright, mask work
right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used.
Information published by TI regarding third-party products or services does not constitute a license from TI to use such products or services
or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual
property of the third party, or a license from TI under the patents or other intellectual property of TI.
Reproduction of TI 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. Information of third parties may be subject to additional
restrictions.
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.
TI products are not authorized for use in safety-critical applications (such as life support) where a failure of the TI product would reasonably
be expected to cause severe personal injury or death, unless officers of the parties have executed an agreement specifically governin g
such use. Buyers represent that they have all necessary expertise in the safety and regulatory r amifications of their applications, and
acknowledge and agree that they are solely responsible for all legal, regulatory and safety-related requirements concerning their products
and any use of TI products in such safety-critical applications, notwithstanding any applications-related information or support that may
be provided by TI. Further, Buyers must fully indemnify TI and its representatives against any damages arising out of the use of TI products
in such safety-critical applications.
TI products are neither designed nor intended for use in military/aerospace applications or environments unless the TI products are
specifically designated by TI as military-grade or "enhanced plastic." Only products designated by TI as military-grade meet military
specifications. Buyers acknowledge and agree that any such use of TI products which TI has not designated as military-grade is solely
at the Buyer's risk, and that they are solely responsible for compliance with all legal and regulatory requirements in connection with such use.
TI products are neither designed nor intended for use in automotive applications or environments unless the specific TI products are
designated by TI as compliant with ISO/TS 16949 requirements. Buyers acknowledge and agree that, if they u se any non-designated
products in automotive applications, TI will not be responsible for any failure to meet such requirements.
Following are URLs where you can obtain information on other Texas Instruments products and application solutions:
Products Applications
Amplifiers amplifier.ti.com Audio www.ti.com/audio
Data Converters dataconverter.ti.com Automotive www.ti.com/automotive
DSP dsp.ti.com Broadband www.ti.com/broadband
Interface interface.ti.com Digital Control www.ti.com/digitalcontrol
Logic logic.ti.com Military www.ti.com/military
Power Mgmt power.ti.com Optical Networking www.ti.com/opticalnetwork
Microcontrollers microcontroller.ti.com Security www.ti.com/security
RFID www.ti-rfid.com Telephony www.ti.com/telephony
Low Power Wireless www.ti.com/lpw Video & Imaging www.ti.com/video
Wireless www.ti.com/wireless
Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265
Copyright © 2007, T exas Instruments Incorporated
About This Manual
Preface
Read This First
DSP/BIOS gives developers of mainstream applications on Texas
Instruments TMS320C5000
real-time s oftw are. DS P/BIOS provid es a sma ll fir mware real- time li brar y and
easy-to-use tools for real-time tracing and analysis.
You should read and become fam iliar with the TMS320 DSP/BIOS User ’s
Guide, a companion volume to this API reference guide.
Before you read this manual, you may use the Code Composer Studio online
tutorial and the DSP/BIOS sec tion of the online help to get an overview of
DSP/BIOS. This man ual discusses various aspects of DSP/ BIOS in depth
and assumes that you have at least a basic understanding of DSP/BIOS.
Notational Conventions
This document uses the following conventions:
❏ Program listings, program examples, and interactive displays are shown
in a special typeface. Examples use a bold version of the
special typeface for emphasis; interactive displays use a bold version
of the special typeface to distinguish commands that you enter from items
that the system displays (such as prompts, command output, error
messages, etc.).
Here is a sample program listing:
TM
DSP devices the ability to develop embedded
Void copy(HST_Obj *input, HST_Obj *output)
{
PIP_Obj *in, *out;
Uns *src, *dst;
Uns size;
}
iii
Related Documentation From Texas Instruments
❏ Square brackets ( [ and ] ) identify an optional parameter. If you use an
optional parameter, you specify the information within the brackets.
Unless the square brackets are in a bold typeface, do not enter the
brackets themselves.
Related Documentation From Texas Instruments
The following books des c ribe T M S3 20 de vi c es and re late d s upp or t too ls. 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.
TMS320 DSP/BIOS User's Guide (literature number SPRU423) provides an over-
view and description of the DSP/BIOS real-time operating system.
TMS320C55x Optimizing C Compiler User’s Guide (literature number
SPRU281) describes the C55x C compiler. This C compiler accepts ANSI
standard C source code and produc es TMS3 20 as s embl y langu age s ourc e
code for the C55x generation of devices.
TMS320C55x Programmer's Guide (literature number SPRU376) describes
ways to optimize C and assembly code for the TMS320C55x DSPs and
includes application program examples.
TMS320C55x Code Composer Studio Tutorial Online Help (literature number
Related Documentation
You can use the following books to supplement this reference guide:
The C Programming Language (second edition), by Brian W. Kernighan
and Dennis M. Ritc hie, published by Prentice-Ha ll, Englewood Cliffs, New
Jersey, 1988
Programming in C, Kochan, Steve G., Hayden Book Company
Programming Embedded Systems in C and C++, by Michael Barr, Andy
Oram (Editor), published by O'Reilly & Associates; ISBN: 1565923545,
February 1999
Real-Time Systems, by Jane W. S. Liu, published by Pre ntice Hall; ISBN:
013099651, June 2000
SPRH097) introduces the Code Composer Studio integrated developme nt
environment and software tools. Of special interest to DSP/BIOS us ers are
the Using DSP/BIOS lessons.
iv
Trademarks
Trademarks
Principles of Concurrent and Distributed Programming (Prentice Hall
International Series in Computer Science), by M. Ben-Ari, published by
Prentice Hall; ISBN: 013711821X, May 1990
American National Standard for Information Systems-Programming
Language C X3.159-1989, American National Standards Institute (ANSI
standard for C); (out of print)
MS-DOS, Windows, and Windows NT are trademarks of Microsoft
Corporation.
The Texas Instruments logo and Texas Instruments are registered
trademarks of Texas Instruments. Trademarks of Texas Instruments include:
TI, XDS, Code Composer, Code Composer Studio, Probe Point, Code
Explorer, DSP/BIOS, RTDX, Online DSP Lab, BIOSuite, SPOX, TMS320,
TMS320C28x, TMS320C54x, TMS320C55x, TMS320C62x, TMS320C64x,
TMS320C67x, TMS320C5000, and TMS320C6000.
All other brand or product names are trademarks or registered trademarks of
their respective companies or organizations.
Read This First v
vi
Contents
1 API Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1
This chapter provides an overview to the TMS320C55x DSP/BIOS API functions.
1.1 DSP/BIOS Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2
1.2 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
1.3 Assembly Language Interface Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
1.4 DSP/BIOS Tconf Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
1.5 List of Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5
2 Application Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
This chapter describes the DSP/BIOS API modules and functions.
2.1 ATM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
2.2 BUF Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
2.3 C55 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26
2.4 CLK Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-39
2.5 DEV Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-58
2.6 GBL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-108
2.7 GIO Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-118
2.8 HOOK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-137
2.9 HST Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-143
2.10 HWI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-148
2.11 IDL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-172
2.12 LCK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-176
2.13 LOG Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-183
2.14 MBX Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-195
2.15 MEM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-201
2.16 MSGQ Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-229
2.17 PIP Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-265
2.18 POOL Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-285
2.19 PRD Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-290
2.20 PWRM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-298
2.21 QUE Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-336
2.22 RTDX Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-353
2.23 SEM Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-369
2.24 SIO Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-382
2.25 STS Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-412
2.26 SWI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-422
vii
Contents
2.27 SYS Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-451
2.28 TRC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-467
2.29 TSK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-472
2.30 std.h and stdlib.h functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-511
A Function Callability and Error Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
This appendix provides tables describing TMS320C55x errors and function callability.
A.1 Function Callability Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
A.2 DSP/BIOS Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
B C55x DSP/BIOS Register Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
This appendix provides tables describing the TMS320C55x register conventions in terms of preservation across multi-threaded context switching and preconditions.
B.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
B.2 Register Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
B.3 Status Register Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
C DSP/BIOS for OMAP 2320 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
This appendix describes things you need to know about DSP/BIOS in order to use it with the
OMAP 2320 platform.
C.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2
C.2 OMAP 2320 and the CLK Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2
C.3 OMAP 2320 and the HWI Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
C.4 OMAP 2320 and the C55 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8
C.5 Building DSP/BIOS Applications for OMAP 2320 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8
C.6 Usage Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-9
D DSP/BIOS for OMAP 2420 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1
This appendix describes things you need to know about DSP/BIOS in order to use it with the
OMAP 2420 platform.
D.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2
D.2 OMAP 2420 and the CLK Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2
D.3 OMAP 2420 and the HWI Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
D.4 OMAP 2420 and the C55 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-9
D.5 Building DSP/BIOS Applications for OMAP 2420 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-9
D.6 Usage Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-10
viii
Figures
2-1 MYSEG Heap Initial Memory Map.............................................................................. 2-215
2-2 MYSEG Memory Map After Allocation........................................................................ 2-216
2-3 MYSEG Memory Map After Modified Allocation ......................................................... 2-217
2-4 Writers and Reader of a Message Queue .................................................................. 2-232
2-5 Components of the MSGQ Architecture ................. ...... ....... ...... ....... .......................... 2-233
2-6 MSGQ Function Calling Sequence............................................................................. 2-233
2-7 Pipe Schematic................................................. ...... ...... ....... ...... ....... ...... ....... ...... ....... 2-267
2-8 Allocators and Message Pools.................................................................................... 2-286
2-9 Buffer Layout as Defined by STATICPOOL_Params.................................................. 2-288
2-10 PRD Tick Cycles......................................................................................................... 2-295
2-11 Statistics Accumulation on the Host............................................................................ 2-415
ix
Tables
1-1 DSP/BIOS Modules ........................................................................................................ 1-2
1-2 DSP/BIOS Operations .................................................................................................... 1-5
2-1 Timer Counter Rates, Targets, and Resets................................................................... 2-41
2-2 High-Resolution Time Determination ............................................................................ 2-42
2-3 HWI interrupts for the ‘C55x........................................................................................ 2-158
2-4 Conversion Characters for LOG_printf ....................................................................... 2-191
2-5 Typical Memory Segments for C5000 Boards ........................................................... 2-213
2-6 Statistics Units for HWI, PIP, PRD, and SWI Modules................................................ 2-413
2-7 Conversion Characters Recognized by SY S_ print f ..... ....... ...... ....... ...... ....... ...... ....... 2-458
2-8 Conversion Characters Recognized by SYS_ spri ntf ................ ....... ...... ....... ............. 2-460
2-9 Conversion Characters Recognized by SYS_ vpri ntf ................ ....... ...... ....... ............. 2-462
2-10 Conversion Characters Recognized by SYS_vsprintf .. ....... ...... ....... .......................... 2-464
2-11 Events and Statistics Traced by TRC.......................................................................... 2-467
A-1 Function Callability..........................................................................................................A-2
A-2 RTS Function Calls.........................................................................................................A-9
A-3 Error Codes...................................................................................................................A-11
x
API Functional Overview
This chapter provides an overview to the TMS320C55x DSP/BIOS API functions.
Chapter 1
Topic Page
1.1 DSP/BIOS Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2
1.2 Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
1.3 Assembly Language Interface Overview. . . . . . . . . . . . . . . . . . . . . . 1–3
1.4 DSP/BIOS Tconf Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
1.5 List of Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–5
1-1
DSP/BIOS Modules
1.1 DSP/BIOS Modules
Table 1-1. DSP/BIOS Modules
Module Description
ATM Module Atomic functions written in assembly language
BUF Module Maintains buf fer poo ls of fixed size buffers
C55 Module Target-specific functi ons
CLK Module System clock manager
DEV Module Device driver interface
GBL Module Global setting manager
GIO Module I/O module used with IOM mini-drivers
HOOK Module Hook function manager
HST Module Host channel manager
HWI Module Hardware interrupt manager
IDL Module Idle function and processing loop manager
LCK Module Resource lock manager
LOG Module Event Log manager
MBX Module Mailboxes manager
MEM Module Memory manager
MSGQ Module Variable-length message manager
PIP Module Buffered pipe manager
POOL Module Allocator interface module
PRD Module Periodic function manager
PWRM Module Reduce a pplication’s power consumption
QUE Module Queue manager
RTDX Module Real-time data exchange manager
SEM Module Semaphores manager
SIO Module Stream I/O manager
STS Module Statistics object manager
SWI Module Software interrupt manager
SYS Module System services manager
TRC Module Trace manager
TSK Module Multitasking manager
std.h and stdlib.h functions Standard C library I/O functions
1-2
1.2 Naming Conventions
The format for a DSP/BIO S operation name is a 3- or 4-letter prefix for
the module that contains the operation, an underscore, and the action.
1.3 Assembly Language Interface Overview
The assembly interface that was provided for some of the DSP/BIOS
APIs has been deprecated. They are no longer documented.
Assembly functions ca n c all C fun ctions . Re mem ber that the C compiler
adds an underscore prefix to function names, so when calling a C
function from assembly, add an underscore to the begin ning of the C
function name. For example, call _myfunction instead of myfunction. See
the TMS320C55x Optimizing Compiler User’s Guide for more details.
When you are using the DSP/BIOS Configuration Tool, use a leading
underscore before the name of any C function you configure. (The
DSP/BIOS Configuration Tool generates assembly code, but does no t
add the underscore automatically.) If you are using Tconf, do not add an
underscore before the function name; Tconf internally adds the
underscore needed to call a C function from assembly.
Naming Conventions
All DSP/BIOS APIs follow standard C calling conventions as documented
in the C programmer’s guide for the device you are using.
DSP/BIOS APIs save and restore context for each thread during a
context switch. Your code should simply follow standard C register usage
conventions. Code written in assembly language should be written to
conform to the regis ter usage model speci fied in th e C comp iler ma nual
for your device . When writing assem bly language, take spe cial care to
make sure the C context is pre served. For example, if you chan ge the
AMR register on the ‘C6000, you should be sure to change it back before
returning from your assembly language routine. See the Register Usage
appendix in this book to see how DSP/BIOS uses specific registers.
1.4 DSP/BIOS Tconf Overview
The section descr ibing eac h modul es in th is man ual li sts proper ties tha t
can be configured in Tconf scripts, along with their types and default
values. The sections on manager properties and instance properties also
provide Tconf examples that set each property.
For details on Tconf scripts, see the DSP/BIOS Tconf User’s Guide
(SPRU007). The language used is JavaScript with an object model
specific to the needs of DSP/BIOS configuration.
API Functional Overview 1-3
DSP/BIOS Tconf Overview
In general, property names of Module objects are in all uppercase letters.
For example, "STACKSIZE". Prope rty names of Instan ce objects begin
with a lowercase word. Subsequent words have their first letter
capitalized. For exampl e, "s tackS ize" .
Default values for many properties are dependent on the values of other
properties. The defau lts shown are those that apply if related proper ty
values have not been modi fied. De fault val ues fo r many H WI pr operties
are different for each instance.
The data types shown for th e pr o per ties ar e n ot u sed as syn tax in Tconf
scripts. However, they do indicate the type of valu es that are valid for
each property. The types used are as follows:
❏ Arg. Arg properties hold ar guments to pass to program functions.
They may be strings, integers, labels, or other types as neede d by
the program function.
❏ Bool. You may assign a valu e of either true or 1 to set a Boolea n
property to true. You may assign a value of either false or 0 (zero) to
set a Boolean property to false. Do not set a Boolean property to the
quoted string "true" or "false".
❏ EnumInt. Enumerated integer properties accept a set of valid integer
values. These values are displayed in a drop-down list in the
DSP/BIOS Configuration Tool.
❏ EnumString. Enumerated string properties accept certain string
values. These values are displayed in a drop-down list in the
DSP/BIOS Configuration Tool.
❏ Extern. Properti es that hol d function name s use the Ext ern type. I n
order to specify a fu nction Extern, u se the prog.extern( ) method as
shown in the examples to refer to objects defined as asm, C, or C++
language symbols. The default language is C.
❏ Int16. Integer properties hold 16-bit unsigned integer values. The
value range accepted for a property may have additional limits.
❏ Int32. Long integ er properties hold 32-bit unsigned integer values.
The value range accepted for a property may have additional limits.
❏ Numeric. Numeric properties hold either 32-bit si gned or unsigned
values or decimal values, as appropriate for the property.
❏ Reference. Properties that reference other configures objects
contain an object reference. Use the prog .get() method to specify a
reference to another object.
❏ String. S tring properties hold text strings.
1-4
List of Operations
1.5 List of Operations
Table 1-2. DSP/BIOS Operations
ATM module operations
Function Operation
ATM_andi, ATM_andu Atomically AND memory location with mask and return previous value
ATM_cleari, ATM_clearu Atomically clear memory location and return previous value
ATM_deci, ATM_decu Atomically decrement memory and return new value
ATM_inci, ATM_incu Atomically increment memory and return new value
ATM_ori, ATM_oru Atomically OR memory location with mask and return previous value
ATM_seti, ATM_setu Atomically set memory and return previous value
BUF module operations
Function Operation
BUF_alloc Allocate a fixed memory buffer out of the buffer pool
BUF_create Dynamically create a buffer pool
BUF_delete Delete a dynamically created buffer pool
BUF_free Free a fixed memory buffer into the buffer pool
BUF_maxbuff Check the maximum number of buffers used from the buffer pool
BUF_stat Determine the status of a buffer pool (buffer size, number of free buffe rs, total
number of buffers in the pool)
C55 operations
Function Operation
C55_disableIER0,
C55_disableIER1,
C55_disableInt
C55_enableIER0,
C55_enableIER1,
C55_enableInt
C55_l2AckInt Acknowledge an L2 interrupt (OMAP 2320/2420 only)
Disable certain maskable interrupts
Enable certain maskable interrupts
API Functional Overview 1-5
List of Operations
Function Operation
C55_l2DisableMIR,
C55_l2DisableMIR1
C55_l2EnableMIR,
C55_l2EnableMIR1
C55_l2SetIntPriority Set the priority of an L2 interrupt (OMAP 2320/2420 only)
C55_plug C function to plug an interrupt vector
Disable certain level 2 interrupts (OMAP 2320/2420 only)
Enable certain level 2 interrupts (OMAP 2320/2420 only)
CLK module operations
Function Operation
CLK_countspms Number of hardware timer counts per millisecond
CLK_cpuCyclesPerHtime Return multiplier for converting high-res time to CPU cycles
CLK_cpuCyclesPerLtime Return multiplier for converting low-res time to CPU cycles
CLK_gethtime Get high-resolution time
CLK_getltime Get low-resolution time
CLK_getprd Get period register value
CLK_reconfig Reset timer period and registers
CLK_start Restart the low-resolution timer
CLK_stop Halt the low-resolution timer
DEV module operations
Function Operation
DEV_createDevice Dynamically creates device with user-defined parameters
DEV_deleteDevice Deletes the dynamically created device
DEV_match Match a device name with a driver
Dxx_close Close device
Dxx_ctrl Device control operation
Dxx_idle Idle device
Dxx_init Initialize device
1-6
Function Operation
Dxx_issue Send a buffer to the device
Dxx_open Open device
Dxx_ready Check if device is ready for I/O
Dxx_reclaim Retrieve a buffer from a device
DGN Driver Software generator driver
DGS Driver Stackable gather/scatter driver
DHL Driver Host link driver
DIO Driver Class driver
DNL Driver Null driver
DOV Driver Stackable overlap driver
DPI Driver Pipe driver
DST Driver Stackable split driver
List of Operations
DTR Driver Stackable streaming transformer driver
GBL module operations
Function Operation
GBL_getClkin Get configured value of board input clock in KHz
GBL_getFrequency Get current frequency of the CPU in KHz
GBL_getProcId Get configured processor ID used by MSGQ
GBL_getVersion Get DSP/BIOS version information
GBL_setFrequency Set frequency of CPU in KHz for DSP/BIOS
GBL_setProcId Set configured value of processor ID used by MSGQ
API Functional Overview 1-7
List of Operations
GIO module operations
Function Operation
GIO_abort Abort all pending input and output
GIO_control Device-specific control call
GIO_create Allocate and initialize a GIO object
GIO_delete Delete underlying IOM mini-drivers and free GIO object and its structure
GIO_flush Drain output buffers and discard any pending input
GIO_new Initialize a pre-allocated GIO object
GIO_read Synchronous read command
GIO_submit Submit a GIO packet to the mini-driver
GIO_write Synchronous write comm and
HOOK module operations
Function Operation
HOOK_getenv Get environment pointer for a given HOOK and TSK combination
HOOK_setenv Set envir onment pointer for a given HOOK and TSK combination
HST module operations
Function Operation
HST_getpipe Get corresponding pipe object
HWI module operations
Function Operation
HWI_disable Globally disable hardware interrupts
HWI_dispatchPlug Plug the HWI dispatcher
HWI_enable Globally enable hardware interrupts
HWI_enter Hardware interrupt service routine prolog
1-8
Function Operation
HWI_exit Hardware interrupt service routine epilog
HWI_isHWI Check to see if called in the context of an HWI
HWI_restore Restore global interrupt enable state
IDL module operations
Function Operation
IDL_run Make one pass through idle functions
LCK module operations
Function Operation
LCK_create Create a resource lock
LCK_delete Delete a resource lock
LCK_pend Acquire ownership of a resource lock
List of Operations
LCK_post Relinquish ownership of a resource lock
LOG module operations
Function Operation
LOG_disable Disable a log
LOG_enable Enable a log
LOG_error/LOG_message Write a message to the system log
LOG_event Append an unformatted message to a log
LOG_printf Append a formatted message to a message log
LOG_reset Reset a log
API Functional Overview 1-9
List of Operations
MBX module operations
Function Operation
MBX_create Create a mailbox
MBX_delete Delete a mailbox
MBX_pend Wait for a message from mailbox
MBX_post Post a message to mailbox
MEM module operations
Function Operation
MEM_alloc, MEM_valloc,
MEM_calloc
MEM_define Define a new memory heap
MEM_free Free a block of memory
MEM_getBaseAddress Get base address of a memory heap
MEM_increaseTableSize Increase the internal MEM table size
MEM_redefine Redefine an existing memory heap
MEM_stat Return the status of a memory heap
MEM_undefine Undefine an existing memory segment
Allocate from a memory heap
MSGQ module operations
Function Operation
MSGQ_alloc Allocate a message. Performed by writer.
MSGQ_close Closes a message queue. Performed by reader.
MSGQ_count Return the number of messages in a message queue
MSGQ_free Free a message. Performed by reader.
MSGQ_get Receive a message from the message queue. Performed by reader.
MSGQ_getAttrs Get attributes of a message queue.
MSGQ_getDstQueue Get destination message queue field in a message.
1-10
Function Operation
MSGQ_getMsgId Return the message ID from a message.
MSGQ_getMsgSize Return the message size from a message.
MSGQ_getSrcQueue Extract the reply destination from a message.
MSGQ_isLocalQu eue Return whether queue is local.
MSGQ_locate Synchronously find a message queue. Performed by writer.
MSGQ_locateAsync Asynchronously find a message queue. Performed by writer.
MSGQ_open Opens a message queue. Performed by reader.
MSGQ_put Place a message on a message queue. Performed by writer.
MSGQ_release Release a located message queue. Performed by writer.
MSGQ_setErrorHandler Set up handling of internal MSGQ errors.
MSGQ_setMsgId Sets the message ID in a message.
MSGQ_setSrcQueue Sets the reply destination in a message.
List of Operations
PIP module operations
Function Operation
PIP_alloc Get an empty frame from a pipe
PIP_free Recycle a frame that has been read back into a pipe
PIP_get Get a full frame from a pipe
PIP_getReaderAddr
PIP_getReaderNumFrames Get the number of pipe frames available for reading
PIP_getReaderSize Get the number of words of data in a pipe frame
PIP_getWriterAddr
PIP_getWriterNumFrames Get the number of pipe frames available to be written to
PIP_getWriterSize Get the number of words that can be written to a pipe frame
PIP_peek Get the pipe frame size and address without actually claiming the pipe frame
PIP_put Put a full fram e into a pipe
PIP_reset Reset all fields of a pipe object to their original values
PIP_setWriterSize Set the number of valid words written to a pipe frame
Get the value of the
Get the value of the writerAddr pointer of the pipe
readerAddr pointer of the pipe
API Functional Overview 1-11
List of Operations
PRD module operations
Function Operation
PRD_getticks Get the current tick counter
PRD_start Arm a peri odic function for one-time execution
PRD_stop Stop a periodic function from exec uti on
PRD_tick Advance tick counter, dispatch periodic functions
PWRM module operations
Function Operation
PWRM_changeSetpoint Initiate a change to the V/F setpoint
PWRM_configure Set new configuration parameters for PWRM
PWRM_getCapabilities Get information on PWRM’s capabilities on the current platform
PWRM_getCurrentSetpoin t Get the current setpoint in effect
PWRM_getDependencyCount Get count of dependencies currently declared on a resource
PWRM_getNumSetpoints Get the number of setpoints supported for the current platform
PWRM_getSetpointInfo Get the corresponding frequency and CPU core voltage for a setpoint
PWRM_getTransitionLatency G et the latenc y to sca le bet ween setpoints
PWRM_idleClocks Immediately idle the clock domains
PWRM_registerNotify Register a function to be called on a specific power event
PWRM_releaseDepe nd enc y Release a dependency that has been prev io us ly dec la red
PWRM_setDependency Declare a dependency upon a resource
PWRM_sleepDSP Transition the DSP to a new sleep state
PWRM_unregisterNotify Unregister for an event notification from PWRM
1-12
QUE module operations
Function Operation
QUE_create Create an empty queue
QUE_delete Delete an empty queue
QUE_dequeue Remove from front of queue (non-atomically)
QUE_empty Test for an empty queue
QUE_enqueue Insert at end of queue (non-atomically)
QUE_get Get element from front of queue (atomically)
QUE_head Return element at front of queue
QUE_insert Insert in middle of queue (non-atomically)
QUE_new Set a queue to be empty
QUE_next Return next element in queue (non-atomically)
QUE_prev Return previous element in queue (non-atomically)
List of Operations
QUE_put Put element at end of queue (atomically)
QUE_remove Remove from middle of queue (non-atomically)
RTDX module operations
Function Operation
RTDX_channelBusy Return status indicating whether a channel is busy
RTDX_CreateInputChannel Declare input channel structure
RTDX_CreateOutputChannel Declare output channel structure
RTDX_disableInput Disable an input channel
RTDX_disableOutput Disable an output channel
RTDX_enableInput Enable an input channel
RTDX_enableOutput Enable an output channel
RTDX_isInputEnabled Return status of the input data channel
RTDX_isOutputEn abled Return status of the output dat a chan nel
RTDX_read Read from an input channel
API Functional Overview 1-13
List of Operations
Function Operation
RTDX_readNB Read from an input channel without blocking
RTDX_sizeofInput Return the number of bytes read from an input channel
RTDX_write Write to an output channel
SEM module operations
Function Operation
SEM_count Get current semaphore count
SEM_create Create a semaphore
SEM_delete Delete a semaphore
SEM_new Initialize a semaphore
SEM_pend Wait for a counting semaphore
SEM_pendBinary Wait for a binary semaphore
SEM_post Signal a counting semaphore
SEM_postBinary Signal a binary semaphore
SEM_reset Reset semaphore
SIO module operations
Function Operation
SIO_bufsize Size of the buffers used by a stream
SIO_create Create stream
SIO_ctrl Perform a device-dependent control operation
SIO_delete Delete stream
SIO_flush Idle a stream by flushing buffers
SIO_get Get buffer from stream
SIO_idle Idle a stream
SIO_issue Send a buffer to a stream
SIO_put Put buffer to a stream
1-14
Function Operation
SIO_ready Determine if device for stream is ready
SIO_reclaim Request a buffer back from a stream
SIO_reclaimx Request a buffer and frame status back from a stream
SIO_segid Memory section used by a stream
SIO_select Select a ready device
SIO_staticbuf Acquire s tatic buffer from stream
STS module operations
Function Operation
STS_add Add a value to a statistics object
STS_delta Add computed value of an interval to object
STS_reset Reset the values stored in an STS object
STS_set Store initial value of an interval to object
List of Operations
SWI module operations
Function Operation
SWI_andn Clear bits from SWI’s mailbox and post if becomes 0
SWI_andnHook Specialized version of SWI_andn
SWI_create Create a software interrupt
SWI_dec Decrement SWI’s mailbox and post if becomes 0
SWI_delete Delete a software interrupt
SWI_disable Disable software interrupts
SWI_enable Enable software interrupts
SWI_getattrs Get attributes of a software interrupt
SWI_getmbox Return SWI’s mailbox value
SWI_getpri Return an SWI’s priority mask
SWI_inc Increment SWI’s ma ilb ox and post
SWI_isSWI Check to see if called in the context of a SWI
API Functional Overview 1-15
List of Operations
Function Operation
SWI_or Set or mask in an SWI’s mailbox and post
SWI_orHook Specialized version of SWI_or
SWI_post Post a software interrupt
SWI_raisepri
SWI_restorepri
SWI_self Return address of currently executing SWI object
SWI_setattrs Set attributes of a software interrupt
Raise an SWI’s priority
Restore an SWI’s priority
SYS module operations
Function Operation
SYS_abort Abort program execution
SYS_atexit Stack an exit handler
SYS_error Flag error condition
SYS_exit Terminate program execution
SYS_printf, SYS_sprintf,
SYS_vprintf, SYS_vsprintf
SYS_putchar Output a single character
Formatted output
TRC module operations
Function Operation
TRC_disable Disable a set of trace controls
TRC_enable Enable a set of trace controls
TRC_query Test whether a set of trace controls is enabled
TSK module operations
Function Operation
TSK_checkstacks Check for stack overflow
TSK_create Create a task ready for execution
TSK_dele te Delete a task
TSK_deltatime Update task STS with time difference
1-16
Function Operation
TSK_disable Disable DSP/BIOS task scheduler
TSK_enable Enable DSP/BIOS task scheduler
TSK_exit Terminate execution of the current task
TSK_getenv Get task environment
TSK_geterr Get task error number
TSK_getname Get task name
TSK_getpri Get task priority
TSK_getsts Get task STS object
TSK_isTSK Check to see if called in the context of a TSK
TSK_itick Advance system alarm clock (interrupt only)
TSK_self Returns a handle to the current task
TSK_setenv Set task environment
TSK_seterr Set task error number
TSK_setpri Set a task execution priority
TSK_settime Set task STS previous time
TSK_sleep Delay execution of the current task
TSK_stat Retrieve the status of a task
TSK_tick Advance system alarm clock
TSK_time Return current value of system clock
TSK_yield Yield processor to equal priority task
List of Operations
C library stdlib.h
Function Operation
atexit Registers one or more exit functions used by exit
calloc Allocates memory block initialized with zeros
exit Calls the exit functions registered in atexit
free Frees memory block
getenv Searches for a matching environment string
malloc Allocates memory block
realloc Resizes previous ly allocated memory block
API Functional Overview 1-17
List of Operations
DSP/BIOS std.h special utility C macros
Function Operation
ArgToInt(arg) Casting to treat Arg type parameter as integer (Int) type on the given target
ArgToPtr(arg) Casting to treat Arg type parameter as pointer (Ptr) type on the given target
1-18
Chapter 2
Application Program Interface
This chapte r describes the DSP/BIOS API modules and functions.
Topic Page
2.1 ATM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2
2.2 BUF Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–15
2.3 C55 Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–26
2.4 CLK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–39
2.5 DEV Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–58
2.6 GBL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–108
2.7 GIO Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–118
2.8 HOOK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–137
2.9 HST Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–143
2.10 HWI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–148
2.11 IDL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–172
2.12 LCK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–176
2.13 LOG Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–183
2.14 MBX Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–195
2.15 MEM Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2– 201
2.16 MSGQ Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–229
2.17 PIP Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–265
2.18 POOL Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–285
2.19 PRD Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–290
2.20 PWRM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–298
2.21 QUE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–336
2.22 RTDX Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–353
2.23 SEM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–369
2.24 SIO Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–382
2.25 STS Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–412
2.26 SWI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–422
2.27 SYS Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–451
2.28 TRC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–467
2.29 TSK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–472
2.30 std.h and stdlib.h functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–511
2-1
ATM Module
2.1 ATM Module
The ATM module includes assembly language functions.
Functions ❏ ATM_andi, ATM_andu. AND memory and return previous value
❏ ATM_cleari, ATM_clearu. Clea r mem ory and retur n previ ous val ue
❏ ATM_deci, ATM_decu. Decrement memory and return new value
❏ ATM_inci, ATM_incu. Increment memory and return new value
❏ ATM_ori, ATM_oru. OR memory and return previous value
❏ ATM_seti, ATM_setu. Set memory and return previous value
Description ATM provides a set of assembly language functions that are used to
manipulate variables with interrupts disabled. These functions can
therefore be used on data shared between tasks, and on da ta shared
between tasks and interrupt routines.
2-2
Loading...