TMS320C28x DSP/BIOS 5.x Application …

1 TMS320C28x DSP/BIOS Application Programming Interface (API). Reference Guide Literature Number: SPRU625L. August 2012. Preface SPRU625L August 2012. Read This First About This Manual DSP/BIOS gives developers of mainstream applications on Texas Instruments TMS320C28xTM DSP. devices the ability to develop embedded real-time software. DSP/BIOS provides a small firmware real- time library and easy-to-use tools for real-time tracing and analysis. You should read and become familiar 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 . section of the online help to get an overview of DSP/BIOS . This manual discusses various aspects of DSP/BIOS in depth and assumes that you have at least a basic understanding of DSP/BIOS .

2 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: Void copy(HST_Obj *input, HST_Obj *output). {. PIP_Obj *in, *out;. Uns *src, *dst;. Uns size;. }. 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. Throughout this manual, 28 represents the two-digit numeric appropriate to your specific DSP.

3 Platform. For example, DSP/BIOS assembly language API header files for the C28x platform are described as having a suffix of .h28. For the C64x or C67x DSP platform, substitute either 64 or 67. for each occurrence of 62. Related Documentation From Texas Instruments The following books describe TMS320 devices and related support tools. To obtain a copy of any of these TI documents, call the Texas Instruments Literature Response Center at (800) 477-8924. When ordering, please identify the book by its title and literature number. SPRU625L August 2012 Read This First 2. Submit Documentation Feedback Related Documentation TMS320 DSP/BIOS User's Guide (literature number SPRU423) provides an overview and description of the DSP/BIOS real-time operating system. TMS320C2000 Optimizing C/C++ Compiler User's Guide (literature number SPRU514) describes the C2000.

4 C/C++ compiler and the assembly optimizer. This C/C++ compiler accepts ANSI standard C/C++ source code and produces assembly language source code for the C2000 generation of devices. TMS320C28x Code Composer Studio Online Help introduces the Code Composer Studio integrated devel- opment environment and software tools. Of special interest to new DSP/BIOS users are the Using DSP/BI- OS tutorial lessons. 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. Ritchie, published by Prentice-Hall, 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.

5 Real-Time Systems, by Jane W. S. Liu, published by Prentice Hall; ISBN: 013099651, June 2000. 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 , American National Standards Institute (ANSI standard for C); (out of print). Trademarks 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, BIOS uite, SPOX, TMS320, TMS320C28x , TMS320C54x, TMS320C55x, TMS320C62x, TMS320C64x, TMS320C67x, TMS320C5000, and TMS320C6000.

6 All other brand or product names are trademarks or registered trademarks of their respective companies or organizations. August 29, 2012. 3 Read This First SPRU625L August 2012. Submit Documentation Feedback Contents 1 API Functional Overview .. 8. DSP/BIOS Modules .. 8. Naming Conventions .. 9. Assembly Language Interface Overview .. 9. DSP/BIOS Tconf Overview .. 10. List of Operations .. 11. 2 Application Program Interface .. 22. ATM Module .. 23. BUF Module .. 36. C28 Module .. 46. CLK Module .. 51. DEV Module .. 66. GBL Module .. 107. GIO Module .. 117. HOOK Module .. 133. HST Module .. 138. HWI Module .. 142. IDL Module .. 161. LCK Module .. 165. LOG Module .. 171. MBX Module .. 183. MEM Module.. 189. MSGQ Module .. 209. PIP Module .. 244. POOL Module .. 262. PRD Module .. 266. QUE Module .. 273. RTDX Module .. 288. SEM Module .. 304.

7 SIO Module .. 315. STS Module .. 340. SWI Module .. 349. SYS Module .. 376. TRC Module .. 392. TSK Module .. 396. and functions .. 432. A Function Callability and Error Tables .. 434. Function Callability Table .. 434. DSP/BIOS Error Codes .. 441. B C28x DSP/BIOS Register Usage .. 442. Overview .. 442. Register Conventions .. 443. SPRU625L August 2012 Contents 4. Submit Documentation Feedback Contents C C28x Real-Time Mode Emulation.. 445. Real-Time Mode Background .. 445. Related Configuration Properties .. 445. Thread Interaction Issues .. 446. 5 Contents SPRU625L August 2012. Submit Documentation Feedback Figures Figures 2-1 Writers and Reader of a Message Queue .. 212. 2-2 Components of the MSGQ Architecture .. 212. 2-3 MSGQ Function Calling Sequence .. 213. 2-4 Pipe Schematic .. 245. 2-5 Allocators and Message Pools .. 263. 2-6 Buffer Layout as Defined by STATICPOOL_Params.

8 264. 2-7 PRD Tick Cycles .. 270. 2-8 Statistics Accumulation on the Host .. 342. 6 Figures SPRU625L August 2012. Submit Documentation Feedback Tables Tables 1-2 DSP/BIOS Operations .. 11. 2-1 Timer Counter Rates, Targets, and Resets.. 52. 2-2 High-Resolution Time Determination .. 53. 2-3 HWI Interrupts for the C28x .. 147. 2-4 Conversion Characters for LOG_printf .. 179. 2-5 Typical Memory Segments for 'C28x Boards .. 197. 2-6 Statistics Units for HWI, PIP, PRD, and SWI Modules .. 341. 2-7 Conversion Characters Recognized by SYS_printf .. 383. 2-8 Conversion Characters Recognized by SYS_sprintf .. 385. 2-9 Conversion Characters Recognized by SYS_vprintf .. 387. 2-10 Conversion Characters Recognized by SYS_vsprintf .. 389. 2-11 Events and Statistics Traced by TRC .. 392. Function Callability Table .. 434. DSP/BIOS Error Codes .. 441. Overview.

9 442. Register Conventions .. 443. Real-Time Mode Background .. 445. Related Configuration Properties .. 445. Thread Interaction Issues .. 446. SPRU625L August 2012 Tables 7. Submit Documentation Feedback Chapter 1. SPRU625L August 2012. API Functional Overview This chapter provides an overview to the TMS320C28x DSP/BIOS API functions. Topic Page DSP/BIOS Modules .. 8. Naming Conventions .. 9. Assembly Language Interface Overview .. 9. DSP/BIOS Tconf Overview .. 10. List of Operations .. 11. DSP/BIOS Modules Table 1 1. DSP/BIOS Modules Module Description ATM Module Atomic functions written in assembly language BUF Module Maintains buffer pools of fixed size buffers C28 Module Target-specific functions 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 SPRU625L August 2012 API Functional Overview 8.

10 Submit Documentation Feedback Naming Conventions Module Description PIP Module Buffered pipe manager POOL Module Allocator interface module PRD Module Periodic function manager 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 and functions Standard C library I/O functions Naming Conventions The format for a DSP/BIOS operation name is a 3- or 4-letter prefix for the module that contains the operation, an underscore, and the action. 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 can call C functions.