Texas Instruments TMS320C55 Series Reference Manual

Download

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

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:

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

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

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

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

ATM_andi

Atomically AND Int memory location and return previous value

C Interface

Syntax ival = ATM_andi(idst, isrc); Parameters volatile Int *idst; /* pointer to integer */

Int isrc; /* integer mask */

Return Value Int ival; /* previous value of *idst */

Description A TM_andi atomically ANDs the mask contained in isrc with a destination

memory location and overwrites the destination value *idst with the result as follows:

`interrupt disable` ival = *idst; *idst = ival & isrc; `interrupt enable` return(ival);

A TM_andi is written in assembly language, efficiently disabling interrupts on the target processor during the call.

ATM_andu

Atomically AND Uns memory location and return previous value

C Interface

Syntax uval = ATM_andu(udst, usrc); Parameters volatile Uns *udst; /* pointer to unsigned */

Uns usrc; /* unsigned mask */

Return Value Uns uval; /* previous value of *udst */

Description ATM_andu atomically ANDs the mask contained in usrc with a

destination memory location and overwr ites the destination value *udst with the result as follows:

`interrupt disable` uval = *udst; *udst = uval & usrc; `interrupt enable` return(uval);

ATM_andu is written in assembly language, efficiently disabling interrupts on the target processor during the call.

ATM_cleari

Atomically clear Int memory loc ation and return previous value

C Interface

Syntax ival = ATM_cleari(idst); Parameters volatile Int *idst; /* pointer to integer */ Return Value Int ival; /* previous value of *idst */

Description ATM_cleari atomically clears an Int memory location and returns its

previous value as follows:

`interrupt disable` ival = *idst; *dst = 0; `interrupt enable` return (ival);

ATM_cleari is written in assembly language, efficiently disabling interrupts on the target processor during the call.

ATM_clearu

Atomically clear Uns memory location and ret urn previous value

C Interface

Syntax uval = ATM_clearu(udst); Parameters volatile Uns *udst; /* pointer to unsigned */ Return Value Uns uval; /* previous value of *udst */

Description ATM_clearu atom ically clears an Uns memory location and returns its

previous value as follows:

`interrupt disable` uval = *udst; *udst = 0; `interrupt enable` return (uval);

ATM_clearu is written in assembly language, efficiently disabling interrupts on the target processor during the call.

ATM_deci

Atomically decrement Int memory and return new va lue

C Interface

Syntax ival = ATM_deci(idst); Parameters volatile Int *idst; /* pointer to integer */ Return Value Int ival; /* new value after decrement */

Description ATM_deci atom ically decr ements an Int m emory loca tion an d returns its

new value as follows:

`interrupt disable` ival = *idst - 1; *idst = ival; `interrupt enable` return (ival);

A TM_deci is written in assembly language, efficiently disabling interrupts on the target processor during the call.

Decrementing a value equ al to the minimum signed i nteger results in a value equal to the maximum signed integer.

ATM_decu

Atomically decrement Uns memory and return new value

C Interface

Syntax uval = ATM_decu(udst); Parameters volatile Uns *udst; /* pointer to unsigned */ Return Value Uns uval; /* new value after decrement */

Description A TM_decu atomically decrements a Uns memory location and returns its

new value as follows:

`interrupt disable` uval = *udst - 1; *udst = uval; `interrupt enable` return (uval);

ATM_decu is written in assembly language, efficiently disabling interrupts on the target processor during the call.

Decrementing a value equal to the minimu m unsigne d integer res ults in a value equal to the maximum unsigned integer.

ATM_inci

Atomically increment Int memory and return new value

C Interface

Syntax ival = ATM_inci(idst); Parameters volatile Int *idst; /* pointer to integer */ Return Value Int ival; /* new value after increment */

Description ATM_inci ato mically increments an Int mem ory location and returns its

new value as follows:

`interrupt disable` ival = *idst + 1; *idst = ival; `interrupt enable` return (ival);

ATM_inci is wr itten in ass embl y languag e, efficien tly dis abling interr upts on the target processor during the call.

Incrementing a value equa l to the maximum sign ed integer results in a value equal to the minimum signed integer.

ATM_incu

Atomically increment Uns memory and return new value

C Interface

Syntax uval = ATM_incu(udst); Parameters volatile Uns *udst; /* pointer to unsigned */ Return Value Uns uval; /* new value after increment */

Description A TM_incu atomically increments an Uns memory location and returns its

new value as follows:

`interrupt disable` uval = *udst + 1; *udst = uval; `interrupt enable` return (uval);

A TM_incu is written in assembly language, efficiently disabling interrupts on the target processor during the call.

Incrementing a value equal to the maximum unsigned integer results in a value equal to the minimum unsigned integer.

ATM_ori

Atomically OR Int memory location and return previous value

C Interface

Syntax ival = ATM_ori(idst, isrc); Parameters volatile Int *idst; /* pointer to integer */

Int isrc; /* integer mask */

Return Value Int ival; /* previous value of *idst */

Description ATM_ori atomi cally ORs the mask contained in isrc with a dest ination

memory location and overwrites the destination value *idst with the result as follows:

`interrupt disable` ival = *idst; *idst = ival | isrc; `interrupt enable` return(ival);

ATM_ori is wr itten in assembly l anguage, efficiently dis abling interrupts on the target processor during the call.

ATM_oru

Atomically OR Uns memory location and return previ ous value

C Interface

Syntax uval = ATM_oru(udst, usrc); Parameters volatile Uns *udst; /* pointer to unsigned */

Uns usrc; /* unsigned mask */

Return Value Uns uva; /* previous value of *udst */

Description ATM_oru atom ically ORs the mask contained i n usrc with a de stination

memory location and overwrites the destination value *udst with the result as follows:

`interrupt disable` uval = *udst; *udst = uval | usrc; `interrupt enable` return(uval);

ATM_oru is writte n in assem bly language, effici ently dis abling in terrupts on the target processor during the call.

ATM_seti

Atomically set Int memory and return previous val ue

C Interface

Syntax iold = ATM_seti(idst, ine w) ; Parameters volatile Int *idst; /* pointer to integer */

Int inew; /* new integer value */

Return Value Int iold; /* previous value of *idst */

Description ATM_seti atomically sets an Int memory location to a new value and

returns its previous value as follows:

`interrupt disable` ival = *idst; *idst = inew; `interrupt enable` return (ival);

ATM_seti is wr itten in asse mbly language , efficiently di sabli ng interr upts on the target processor during the call.

ATM_setu

Atomically set Uns memory and return previous value

C Interface

Syntax uold = ATM_setu(udst, unew); Parameters volatile Uns *udst; /* pointer to unsigned */

Uns unew; /* new unsigned value */

Return Value Uns uold; /* previous value of *udst */

Description ATM_setu atomi cally sets an Uns m emory location to a new value and

returns its previous value as follows:

`interrupt disable` uval = *udst; *udst = unew; `interrupt enable` return (uval);

A TM_setu is written in assembly language, efficiently disabling interrupts on the target processor during the call.

2.2 BUF Module

The BUF module maintains buffer pools of fixed-size buffers.

Functions ❏ BUF_alloc. Allocate a fixed-size buffer from the buffer pool

❏ BUF_create. Dynamically create a buffer pool ❏ BUF_delete. Delete a dynamically-created buffer pool ❏ BUF_free. Free a fixed-size buffer back to the buffer pool ❏ BUF_maxbuff. Get the maximum number of buffers used in a pool ❏ BUF_stat. Get statistics for the specified buffer pool

BUF Module

Constants, Types, and Structures

typedef unsigned long MEM_sizep;

#define BUF_ALLOCSTAMP 0xcafe #define BUF_FREESTAMP 0xbeef

typedef struct BUF_Obj { Ptr startaddr; /* Start addr of buffer pool */ MEM_sizep size; /* Size before alignment */ MEM_sizep postalignsize; /* Size after align */ Ptr nextfree; /* Ptr to next free buffer */ Uns totalbuffers; /* # of buffers in pool*/ Uns freebuffers; /* # of free buffers in pool */ Int segid; /* Mem seg for buffer pool */ } BUF_Obj, *BUF_Handle;

typedef struct BUF_Attrs { Int segid; /* segment for element allocation */ } BUF_Attrs;

BUF_Attrs BUF_ATTRS = {/* default attributes */ 0, };

typedef struct BUF_Stat { MEM_sizep postalignsize; /* Size after align */ MEM_sizep size; /* Original size of buffer */ Uns totalbuffers; /* Total buffers in pool */ Uns freebuffers; /* # of free buffers in pool */ } BUF_Stat;

Configuration Properties

The following lis t sh ows th e p roper ti es th at ca n b e c on fig ur ed in a Tconf script, along with their types and default values. For details, see the BUF Manager Properties and BUF Object Properties headings. For descriptions of data type s, see Secti on 1.4, DSP/ BIOS Tconf Overview, page 1-3.

Application Program Interface 2-15

BUF Module

Module Configuration Parameters

Name Type Default (Enum Options)

OBJMEMSEG Reference prog.get("DARAM")

Instance Configuration Parameters

Name Type Default (Enum Options)

comment String "<add comments here>" bufSeg Reference prog.get("DARAM") bufCount Int32 1 size Int32 4 (’C55x) align Int32 2 (’C55x) len Int32 4 (’C55x) postalignsiz e Int32 4 (’C55x)

Description The BUF module maintains pools of fixed-size buffers. These buffer

pools can be created statically or dynamically. Dynamically-created buffer pools are allocated from a dynamic memory heap managed by the MEM module. Applicat ions ty pica lly a llocate b uffer poo ls static ally whe n size and alignment constraints are known at design time. Run-time allocation is used when these constraints vary during execution.

2-16

Within a buffer pool, all buffers have the same size and alignment. Although each frame has a fixed length, the application can put a variable amount of data in each frame, up to the length of the frame. You can create multiple buffer pools, each with a different buffer size.

Buffers can be alloca ted and freed from a pool a s needed at run-time using the BUF_alloc and BUF_free functions.

The advantages of allocating memor y from a buffer pool instea d of from the dynamic memory heaps provided by the MEM module include:

❏ Deterministic allocation times. The BUF_alloc and BUF_free

functions require a constant amount of t ime. Allocating and fr eeing memory through a heap is not deterministic.

❏ Callable from all thread types. Allocating and freeing buffers is

atomic and non-bloc king. A s a result, B UF_all oc and B UF_free ca n be called from all t ypes of DS P/BIOS thr eads: HW I, SWI, TSK , and IDL. In contrast, HWI and SWI threads cannot call MEM_alloc.

❏ Optimized for fixed-length allocation. In contrast MEM_alloc is

optimized for variable-length allocation.

BUF Module

❏ Less fragmentation. Since the buffers are of fixed-size, the pool

does not become fragmented.

BUF Manager Properties

The following global properties can be set for the BUF module in the BUF Manager Properties dia log of the DSP/BIOS Configuratio n Tool or in a Tconf script:

❏ Object Memory. The memory segment to contain all BUF objects.

(A BUF object may be st ored in a different location than the buffer pool memory itself.)

Tconf Name: OBJMEMSEG Type: Reference Example: bios.BUF.OBJMEMSEG = prog.get("myMEM");

BUF Object Properties The foll owing properties can be s et for a buffer pool object in t he BUF

Object Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf sc ript. To create an BUF object in a configuration script, use the following syntax:

var myBuf = bios.BUF.create("myBUF");

The Tco nf examples that follow as sume the ob ject has been c reated as shown.

❏ comment. Type a comment to identify this BUF object.

Tconf Name: comment Type: String Example: myBuf.comment = "my BUF";

❏ Memory segment for buffer pool. Select the memory segment in

which the buffer pool is to be created. The linker decides where in the segment the buffer pool starts.

Tconf Name: bufSeg Type: Reference Example: myBuf.bufSeg = prog.get("myMEM");

❏ Buffer count. Specify the number of fixed-length buffers to create in

this pool. Tconf Name: bufCount Type: Int32 Example: myBuf.bufCount = 128;

❏ Buffer size. Specify the size (in MA DUs ) of eac h fixe d- le ngth buffer

inside this buffer pool. The de fault size sho wn is the minimum va lid value for that platform. T his size may be ad justed to accomm odate the alignment in the "Buffer size after alignment" property.

Tconf Name: size Type: Int32 Example: myBuf.size = 4;

Application Program Interface 2-17

BUF Module

❏ Buffer alignment. Specify the alignment boundary for fixed- length

buffers in the pool. Each buffer is aligned on boundaries with a multiple of this number. The default size shown is the minimum valid value for that platform. The value must be a power of 2.

Tconf Name: align Type: Int32 Example: myBuf.align = 2;

❏ Buffer pool length. The actual length of the buffer pool (in MADUs)

is calculated by multi plying the Buffer count by the Buffer size after alignment. You cannot modify this value directly.

Tconf Name: len Type: Int32 Example: myBuf.len = 4;

❏ Buffer size after alignment. This property shows the modified

Buffer size after applyi ng the alignment. For ex ample, if the Buffer size is 9 and the align men t is 4, th e Bu ffer si ze afte r a li gnm ent i s 12 (the next whole number multiple of 4 after 9).

Tconf Name: postalignsize Type: Int32 Example: myBuf.postalignsize = 4;

2-18

BUF_alloc

Allocate a fixed-size buffer from a buffer pool

C Interface

Syntax bufaddr = BUF_alloc(buf); Parameters BUF_Handle buf; /* buffer pool object handle */ Return Value Ptr bufaddr; /* pointer to free buffer */

Reentrant yes Description BUF_alloc allocates a fixed-size buffer from the specified buffer pool and

returns a pointer to the buffer. BUF_alloc does not initialize the allocated buffer space.

The buf parameter is a handle to identify the buffer pool object, from which the fixed size buffer is to be allocated. If the buffer pool was created dynamically, the handle is the one r etu rned by t he c all t o B UF _cr eat e. If the buffer pool was c reated statically, the handle can be r eferenced as shown in the example that follows.

If buffers are available i n the specified b uffer pool, BUF_all oc returns a pointer to the buffer. If no buffers are available, BUF_alloc returns NULL.

The BUF module m ana ges s y nchr oni za tio n s o tha t multiple threads ca n share the same buffer pool for allocation and free operations.

The time required to successfully execute BUF_alloc is deterministic (constant over multiple calls).

Example extern BUF_Obj bufferPool;

BUF_Handle buffPoolHandle = &bufferPool;

Ptr buffPtr;

/* allocate a buffer */ buffPtr = BUF_alloc(buffPoolHandle); if (buffPtr == NULL ) { SYS_abort("BUF_alloc failed"); }

BUF_create

Dynamically create a buffer pool

C Interface

Syntax buf = BUF_create(numbuff, size, align, attrs); Parameters Uns numbuff; /* number of buffers in the pool */

MEM_sizep size; /* size of a single buffer in the pool */ Uns align; /* alignment for each buffer in the pool */ BUF_Attrs *attrs; /* pointer to buffer pool attributes */

Return Value BUF_Handle buf; /* buffer pool object handle */

Reentrant no Description BUF_create creates a buffer pool object dynamically. The parameters

correspond to the pr ope rties a va il able for statically-created bu ffer poo ls , which are described in the BUF Object Properties topic.

The numbuff parameter specifies how many fixed-length buffers the pool should contain. This must be a non-zero number.

The size parameter specifies how long each fixed-leng th buffer in the pool should be in MADUs. This must be a non-zero number. The size you specify is adjusted as needed to meet the alignment requirements, so the actual buffer size may be larger. The MEM_sizep type is defined as follows:

2-20

typedef unsigned long MEM_sizep;

The align parameter sp ecifies the alignment b oundary for buffers in the pool. Each buffer is aligned on a boundary with an address that is a multiple of this number. The value must be a power of 2. The size of buffers created in the p ool is automatically in creased to accommodate the alignment you specify.

BUF_create ensure s that the size and alignment are set to at least the minimum values permitted for the platform. The minimum size permitted is

4 (’C55x) MADUs. The minimum alignment permitted is 2 (’C55x).

The attrs parameter points to a structure of type BUF_Attrs, which is defined as follows:

typedef struct BUF_Attrs { Int segid; /* segment for element allocation*/ } BUF_Attrs;

BUF_create

The segid element can be used to specify the memory segment in which buffer pool should be created. If at trs is NULL, the new bu ffer pool is created the default at tributes specified in BUF_ATTRS, which uses the default memory segment.

BUF_create calls MEM_alloc to dynamically create the BUF object's data structure and the buffer pool.

BUF_create returns a handle to the bu ffer pool of type BUF_Ha ndle. If the buffer pool cannot be cr eated, BUF_crea te returns NULL. T he pool may not be created if the numbuff or size parameter is zero or if the memory available in the specified heap is insufficient.

The time required to successfully execute BUF_create is not deterministic (that is, the time varies over multiple calls).

Constraints and Calling Context

❏ BUF_create cannot be called from a SWI or HWI. ❏ The product of the size (after adjusting for the alignment) and

numbuff parameters should not exceed the maximum Uns value.

❏ The alignment should be greater th an the minim um value and must

be a power of 2. If it is not, proper creation of buffer pool is not guaranteed.

Example BUF_Handle myBufpool;

BUF_Attrs myAttrs;

myAttrs = BUF_ATTRS; myBufpool=BUF_create(5, 4, 2, &myAttrs); if( myBufpool == NULL ){ LOG_printf(&trace,"BUF_create failed!"); }

BUF_delete

C Interface

Syntax status = BUF_delete(buf); Parameters BUF_Handle buf; /* buffer pool object handle */ Return Value Uns status; /* returned status */

Reentrant no Description BUF_delete frees the buffer pool object and the buffer pool memory

Delete a dynamically-created buffe r pool

referenced by the handle provided. The buf parameter is the handle that identifies the buffer pool object. This

handle is the one returned by the call to BUF_create. BUF_delete cannot be used to delete statically created buffer pool objects.

BUF_delete returns 1 if it has successfully freed the memory for the buffer object and buffer pool. It retur ns 0 (zero) if it was unable t o de let e the buffer pool.

BUF_delete calls MEM_free to delete the BUF object and to free the buffer pool memory. MEM_free must acquire a lock to the memory before proceeding. If another task already hold s a lo ck on t he mem or y, there is a context switch.

The time required to successfully execute BUF_delete is not deterministic (that is, the time varies over multiple calls).

Constraints and Calling Context

Example BUF_Handle myBufpool;

BUF_free

Free a fixed memory buffer into the buffer pool

C Interface

Syntax status = BUF_free(buf, bufaddr); Parameters BUF_Handle buf; /* buffer pool object handle */

Ptr bufaddr; /* address of buffer to free */

Return Value Bool status; /* returned status */

Reentrant yes Description BUF_free frees the specified buffer back to the specified buffer pool. The

newly freed buffer is then available for further allocation by BUF_alloc. The buf parameter is the handle that identifies the buffer pool object. This

handle is the one returned by the call to BUF_create. The bufaddr parameter is the pointer returned by the corresponding call

to BUF_alloc. BUF_free always returns TRUE if DSP/BIOS real-time analysis is

disabled (in the GBL Module Properties). If real-time analysis is enabled, BUF_free returns TRUE if the bufaddr parameter is within the range of the specified buffer pool; otherwise it returns FALSE.

The BUF module m ana ges s y nchr oni za tio n s o tha t multiple threads ca n share the same buffer pool for allocation and free operations.

The time required to successfully execute BUF_free is deterministic (constant over multiple calls).

Example extern BUF_Obj bufferPool;

BUF_Handle buffPoolHandle = &bufferPool; Ptr buffPtr;

...

BUF_free(buffPoolHandle, buffPtr);

BUF_maxbuff

Check the maximum number of buffers from the buffer pool

C Interface

Syntax count = BUF_maxbuff(buf); Parameters BUF_Handle buf; /* buffer pool object Handle */ Return Value Uns count; /*maximum number of buffers used */

Reentrant no Description BUF_maxbuff returns the m aximum number of buffers that have been

allocated from the specified buffer pool at any time. The count measures the number of buffers in use, not the total number of times buffers have been allocated.

The buf parameter is the handle that identifies the buffer pool object. This handle is the one returned by the call to BUF_create.

BUF_maxbuff distinguishes free and allocated buffers via a stamp mechanism. Allocated buffers are marked with th e BUF_A LLOCSTAMP stamp (0xcafe). If the applicati on happens to change this stamp to the BUF_FREESTAMP stamp (0xbeef), the count may be inaccurate. Note that this is not an application error. This stamp is only used for BUF_maxbuff, and changing it does not affect program execution.

The time required to successfully execute BUF_maxbuff is not deterministic (that is, the time varies over multiple calls).

Constraints and Calling Context

❏ BUF_maxbuff cannot be called from a SWI or HWI. ❏ The application must implement synchronization to ensure that other

threads do not perform BUF_alloc during the execution of BUF_maxbuff. Otherwise, the count return ed by BUF_ma xbuff may be inaccurate.

Example extern BUF_Obj bufferPool;

BUF_Handle buffPoolHandle = &bufferPool; Int maxbuff;

maxbuff = BUF_maxbuff(buffPoolHandle); LOG_printf(&trace, "Max buffers used: %d", maxbuff);

BUF_stat

Determine the status of a buffer pool

C Interface

Syntax BUF_stat(buf,statbuf); Parameters BUF_Handle buf; /* buffer pool object handle */

BUF_Stat *statbuf; /* pointer to buffer status structure */

Return Value none

Reentrant yes Description BUF_stat returns the status of the specified buffer pool.

The buf parameter is the handle that identifies the buffer pool object. This handle is the one returned by the call to BUF_create.

The statbuf parameter must be a structure of type BUF_Stat. The BUF_stat function fills in all the fields of the structure. The BUF_Stat type has the following fields:

typedef struct BUF_Stat { MEM_sizep postalignsize; /* Size after align */ MEM_sizep size; /* Original size of buffer */ Uns totalbuffers; /* Total # of buffers in pool */ Uns freebuffers; /* # of free buffers in pool */ } BUF_Stat;

Size values are expressed in Minimum Addressable Data Units (MADUs). BUF_s tat collects statistics with interr upts disabled to e nsure the correctness of the statistics gathered.

The time required to successfully execute BUF_stat is deterministic (constant over multiple calls).

Example extern BUF_Obj bufferPool;

BUF_Handle buffPoolHandle = &bufferPool; BUF_Stat stat;

BUF_stat(buffPoolHandle, &stat); LOG_printf(&trace, "Free buffers Available: %d", stat.freebuffers);

2.3 C55 Module

The C55 module inc lude target- spec i fic fu nct ion s for the TMS 320 C500 0 family

Functions ❏ C55_disableIER0, C55_disableIER1. ASM macros to disable

selected interrupts in the IER0/IER1, respectively

❏ C55_disableInt. Disable an individual interrupt. ❏ C55_enableIER0, C55_enableIER1. ASM macros to enable

selected interrupts in the IER0/IER1, respectively

❏ C55_enableInt. Enable an individual interrupt. ❏ C55_l2AckInt. Explicitly acknowledge an L2 interrupt ❏ C55_l2DisableMIR, C55_l2DisableMIR1. Disable a set of L2

interrupts

❏ C55_l2EnableMIR, C55_l2EnableMIR1. Enable a set of L2 interrupts ❏ C55_l2SetIntPriority. Set the priority of a L2 interrupt ❏ C55_plug. Plug interrupt vector

Description The C55 module provide certain target-s pecific function s and defin itions

for the TMS320C5000 family of processors. See the c55.h file for a comp lete list of defini tions for hardw are flags for

C. The c55.h file contain C language macros, #defines for various TMS320C5000 registers, and structure definitions. The c55.h55 file also contain assembly language macros for sa ving and re storing registers in HWIs.

2-26

C55_disableIER0, C55_disableIER1

C Interface

Syntax oldmask = C55_disableIER0(mask);

Parameters Uns mask; /* disable mask */ Return Value Uns oldmask; /* actual bits cleared by disable mask */

Description C55_disableIER0 and C55_disableIER1 disable interrupts by clearing

C55_disableInt

Disable an individual interrupt

C Interface

Syntax C55_disableInt(vecid); Parameters Uns vecid; /* vector ID for interrupt */ Return Value Void

Description This function disa bles an indiv idual interrupt r eferenced by a vector ID.

The vector ID can match a level 1 interrupt (vecids 0-31) or an OMAP 2320/2420 level 2 interrupt (vecids 32-63). For OMAP 2320, the additional level 2 interrupts 32-63 can be disabled using vecids 64-95.

The c55.h header file provides some convenient interrupt ID definitions.

C55_enableIER0, C55_enableIER1

Enable certain maskable interrupts

C Interface

Syntax C55_enableIER0(oldmask);

C55_enableIER1(oldmask);

Parameters Uns oldmask; /* enable mask */ Return Value Void

Description C55_disableIER0, C55_disableIER1, C55_enableIER0, and

C55_enableIER1 disable and enable specific internal interrupts by modifying the I nterrupt Enable Re gister (IER0/IER1). C55_disableIER 0 and C55_disableIER 1 clear t he bits spe cified b y the ma sk parameter in the Interrupt Mask Register and return a mask of the bits it cleared. C55_enableIER0 and C55_enableIER1 set the bits specified by the oldmask parameter in the Interrupt Mask Register.

C55_disableIER0 and C55_disableIER1 and C55_enableIER0 and C55_enableIER1 ar e u su all y used in tandem to protect a cr it ical s ec tio n of code from interrupts. The following code examples show a region protected from all maskable interrupts:

/* C example */

Uns oldmask;

oldmask0 = c55_disableIER0(~0); `do some critical operation; ` `do not call TSK_sleep, SEM_post, etc.` c55_enableIER0(oldmask0);

Note:

DSP/BIOS kernel calls that can cause rescheduling of tasks (for example, SEM_post and TSK_sleep) should be avoided within a C55_disableIER0, C55_disableIER1, C55_enableIER0, and / C55_enableIER1 block since the interrupts can be disabled for an indeterminate amount of time if a task switch occurs.

You can use C55_disableIER0, C55_disableIER1, C55_enableIER0, and C55_enableIER1 to disable selected interrupts, while allowing other interrupts to occur. However, if another hardware interrupt occurs during

Application Program Interface 2-29

C55_enableIER0, C55_enableIER1

this region, it could cause a task switch. You can prevent this by enclosing it with TSK _disable / TSK_enable to dis able DSP/BIOS task scheduling.

Uns oldmask;

TSK_disable(); oldmask0 = C55_disableIER0(INTMASK0); oldmask1 = C55_disableIER1(INTMASK1); `do some critical operation;` `NOT OK to call TSK_sleep, SEM_post, etc.` C55_enableIER0(oldmask0); C55_enableIER0(oldmask1); TSK_enable();

Note:

If you use C55_disableIER0, C55_disableIER1, C55_enableIER0, and C55_enableIER1 to disabl e only some interrupts, you mu st surround this region with SWI_disable / SWI_enable, to prevent an intervening HWI from causing a SWI or TSK switch.

The second approach is preferable if it is important not to disable all interrupts in your system during the critical operation.

See Also C55_disableIER0, C55_disableIER1

2-30

C55_enableInt

Enable an individual interrupt

C Interface

Syntax C55_enableInt(vecid); Parameters Uns vecid; /* vector ID for interrupt */ Return Value Void

Description This function enable s an individual interru pt referenced by a vector ID.

The vector ID can match a level 1 interrupt (vecids 0-31) or an OMAP2320/2420 lev el 2 interrupt (ve cids 32-63). For O MAP 2320, the additional level 2 interrupts 32-63 can be enabled using vecids 64-95.

The c55.h header file provides some convenient interrupt ID definitions.

Example Void main ()

{ HWI_Attrs attrs = HWI_ATTRS;

// pass vector ID to myIsr attrs.arg = (Arg)C55_L2_INT1;

// Plug Level 2 Interrupt #1 Vector HWI_dispatchPlug(C55_L2_INT1, (Fxn)myIsr, &attrs);

// Enable Level 2 interrupt C55_enableInt(C55_L2_INT1); }

C55_l2AckInt

C Interface

Syntax C55_l2AckInt(); Parameters Void Return Value Void

Description This API applies to the OMAP 2320/2420 platforms only.

Explicitly acknowledge an L2 interrupt

The L2IC requires the interrupts be explicitly acknowledged prior to returning from an ISR in order to allow other L2 interrupts to be processed.

The DSP/BIOS HWI di spatcher handles this acknowle dgement for HW I functions coded in C that use the HWI dispatcher. The HWI_enter and HWI_exit macros provide this functionality for HWI functions coded in assembly.

The C55_l2AckInt function is for use only in HWI functions that are coded in C but that do not use the HWI dispatcher. Such functions are "interrupt" defined C code ISRs, which are dynam ic al ly plugged using C55_plug or statically plugged using Tconf.

The C55_l2AckInt function is #defined so that inline code is generated in order to minimize the register context saving code generated by the compiler when using the "interrupt" keyword.

Important: Recall that ISRs de fined u sing t he "int errupt " keywor d are n ot allowed to call any DSP/BIOS functions. The C55_l2AckInt function is an exception to this rule.

Constraints and Calling Context

Example interrupt void myIsr()

C55_l2DisableMIR

Disable certain level 2 interrupts

C Interface

Syntax C55_l2DisableMIR(mirmask); Parameters LgUns mirmask; /* disable mask */ Return Value Void

Description This API applies to OMAP 2320/2420 platforms only.

C55_l2DisableMIR disables level 2 interrupts by setting the bits specified by mirmask in the Interrupt Mask Register (MIR). The MIR is a register in the Level 2 Interrupt Controller (L2IC) that defines which level 2 interrupts (0-31) are enabled or disabled. (Set bits are disabled.)

This function provid es the functionality of C55 _disableIer0/1 for level 2 interrupts. The mirmask argum ent is a 32-bit bi tmask tha t defines which level 2 interrupts to disable.

C55_l2DisableMIR1

Disable certain level 2 interrupts

C Interface

Syntax C55_l2DisableMIR1(mir1mask); Parameters LgUns mir1mask;/* disable mask */ Return Value Void

Description This API applies to the OMAP 2320 platform only.

C55_l2DisableMIR1 disables level 2 interrupts by setting the bits specified by mir1mask in the Interrupt Mask Register1 (MIR1). The MIR1 is a register in t he Level 2 Interru pt Controlle r (L2IC) that defin es which level 2 interrupts (32-63) are enabled or disabled. (Set bits are disabled.)

This function provid es the functionality of C55 _disableIer0/1 for level 2 interrupts. The mir1mask argument is a 32-bit bitmask that defines which level 2 interrupts to disable.

C55_l2EnableMIR

Enable certain level 2 inter rupts

C Interface

Syntax C55_l2EnableMIR(mirmask); Parameters LgUns mirmask; /* disable mask */ Return Value Void

Description This API applies to the OMAP 2320/2420 platforms only.

C55_l2EnableMIR enables level 2 interrupts by clearing the bits specified by mirmask in the Interrupt Mask Register (MIR). The MIR is a register in the Level 2 Interrupt Controller (L2IC) that defines which level 2 interrupts (0-31) are enabled or disabled. (Cleared bits are enabled.)

This function provides the fun ctionality of C55_enableIer0/1 for le vel 2 interrupts. The mirmask argum ent is a 32-bit bi tmask tha t defines which level 2 interrupts to enable.

Example // Enables L2 interrupts 10, 11, 12, 13

// 0x3c00 = 11110000000000 binary C55_l2EnableMIR(0x00003c00);

C55_l2EnableMIR1

Enable certain level 2 interrupts

C Interface

Syntax C55_l2EnableMIR1(mir1mask); Parameters LgUns mir1mask;/* disable mask */ Return Value Void

Description This API applies to the OMAP 2320 platform only.

C55_l2EnableMIR1 enables level 2 interrupts by clearing the bits specified by mir1mask in the Interrupt Mask Register1 (MIR1). The MIR1 is a register in t he Level 2 Interru pt Controlle r (L2IC) that defin es which level 2 interrupts (32-63) are enabled or disabled. (Cleared bits are enabled.)

This function provides the fun ctionality of C55_enableIer0/1 for leve l 2 interrupts. The mir1mask argument is a 32-bit bitmask that defines which level 2 interrupts to enable.

Example // Enables L2 interrupts 42, 43, 44, 45

// 0x3c00 = 11110000000000 binary C55_l2EnableMIR1(0x00003c00);

C55_l2SetIntPriority

Set the priority of a level 2 interrupt

C Interface

Syntax C55_l2SetIntPriority(vecid, priority); Parameters Uns vecid; /* vector ID of interrupt */

Uns priority; /* new priority of interrupt */

Return Value Void

Description This API applies to the OMAP 2320/2420 platforms only.

The Level 2 Interrupt Controller (L2IC) allows you to set the relative priority of each of the level 2 interrupts.

The default interrupt prio rities match the in terrupt number. That is, level 2 interrupts 0-31 (logical interrupt IDs 32-63) have priorities 0-31 respectively. The additional OMAP 2320 L2 interrupts 32-63 (logical interrupt IDs 64-95) have priorities 32-63 respectively.

The L2 controller defines level 0 to be the highest priority and level 31 the lowest (63 for th e OMAP 2320). Therefore the de fault priority settings give highest priority to L2 interrupt 0 and lowest to interrupt 31 (63 for the OMAP 2320).

The level 2 interrupt priority setting is independent of whether the interrupt is serviced by the dispatcher or not.

Example Void main()

{ HWI_Attrs attrs; attrs = HWI_ATTRS;

attrs.arg = (Arg)C55_L2_INT10; HWI_dispatchPlug( C55_L2_INT10, (Fxn)l2FiqFunc, &attrs); C55_l2SetIntPriority( C55_L2_INT10, 0);

... }

C55_plug

C function to plug an interrupt vector

C Interface

Syntax C55_plug(vecid, fxn); Parameters Int vecid; /* interrupt id */

Fxn fxn; /* pointer to HWI function */

Return Value Void

Description C55_plug hooks up the specified function as the branch target for a

hardware interrupt (fielded by the CPU) at the vector address corresponding to vecid. C55_plug does not enable the interrupt. Use C55_enableIER0, C55_enableIER1 to enable specific interrupts.

Constraints and Calling Context

❏ vecid must be a valid interrup t I D in the range of 0-31. (The ran ge is

0-95 for OMAP 2320. The range is 0-63 for OMAP 2420.)

2.4 CLK Module

The CLK module is the clock manager.

Functions ❏ CLK_countspms. Timer counts per millisecond

❏ CLK_cpuCyclesPerHtime. Return high-res time to CPU cycles factor ❏ CLK_cpuCyclesPerLtime. Return low-res time to CPU cycles factor ❏ CLK_gethtime. Get high-resolution time ❏ CLK_getltime. Get low-resolution time ❏ CLK_getprd. Get period registe r value ❏ CLK_reconfig. Reset timer period and registers using CPU frequency ❏ CLK_start. Restart low-resolution timer ❏ CLK_stop. Stop low-resolution timer

CLK Module

Configuration Properties

The following lis t sh ows th e p roper ti es th at ca n b e c on fig ur ed in a Tconf script, along with their types and default values. For details, see the CLK Manager Properties and CLK Object Properties headings. For descriptions of data type s, see Secti on 1.4, DSP/BIO S Tconf Overview, page 1-3.

Module Configuration Parameters

C55x Name Type Default (Enum Options)

OBJMEMSEG Reference prog.get("DARAM") TIMERS_BASE Numeric 0x7000 (OMAP 2420 only) TIMERS_BASE_DATAMEM Numeric 0x7ee000 (OMAP 2420 only) TIMERSELECT String "Timer 0"

("Timer 5" for OMAP 2420) ENABLECLK Bool true HIRESTIME Bool true ENABLEHTIME Bool true (C5501, 5502,

OMAP 2320/2420 only) MICROSECONDS Int16 1000.0071 CONFIGURETIMER Bool false FIXTDDR Bool false (not for OMAP 2320/2420) LOAD_TIM Int16 2999 (1x10, 59xx only) TCRTDDR EnumInt 0 (0 to 15)

(not for OMAP 2320/2420)

Application Program Interface 2-39

CLK Module

C55x Name Type Default (Enum Options)

TCRPTV EnumInt 0 (0 to 7) (1x10, 59xx only) PRD Int16 46666, 7499, or 59999

(varies by platform)

(not used for 1x10, 59xx) INPUTCLK Numeric 0.032 MHz (OMAP 2420 only) HTIMECLK N umeric 12.0 MHz (OMAP 2420 only)

Instance Configuration Parameters

Name Type Default

comment String "<add comments here>" fxn Extern prog.extern("FXN_F_nop") order Int16 0

Description The CLK module provides method s for gathe ring timing infor mation and

for invoking functio ns periodically. The CLK module provides real- time clocks with functions to access the low-resolution and high-resolution times. These times can be used to measure the passage of time in conjunction with STS accumulator o bjects, as well as to ad d timestamp messages in event logs.

DSP/BIOS provides the following timing methods: ❏ Timer Counter. This DSP/BIOS counter changes at a relatively fast

platform-specific rate that is determined by your CLK Manager Property settings. Thi s counter is used only if the Clock Manager is enabled in the CLK Manager Properties.

❏ Low-Resolution Time. This time is incremented when the timer

counter reaches its target value. When this time is incremented, any functions defined for CLK objects are run.

❏ High-Resolution Time. For some platforms, the timer counter is

also used to determine the high-resolution time. For other platforms, a different timer is used for the high-resolution time.

❏ Periodic Rate. The PRD functions can be run at a mu ltiple of the

clock interrupt ra te (the low-resolution rate) i f you enable the "Use CLK Manager to Drive PRD" in the PRD Manager Properties.

❏ System Clock. The PRD rate, in turn, can be used to run the system

clock, which is used to meas ure TSK-related timeouts and ticks . If you set the "TSK Tick Driven By" in the T SK Manager P roperties to "PRD", the system cl ock ticks at the specifie d multiple of the clock interrupt rate (the low-resolution rate).

2-40

CLK Module

Timer Counter The timer counter changes at a relatively fast rate until it reaches a target

value. When the target val ue is reached, the timer counter is reset, a timer interrupt occu rs, the low-resolution time is incremented, and any functions defined for CLK objects are run.

Table 2 -1 shows the rate at whic h the timer co unter changes, i ts target value, and how the value is reset once the target value has been reached.

Table 2-1. Timer Counter Rates, Targets, and Resets

Target

Platform Timer Counter Rate

Value Value Reset

’C5501, ’C5502 Incremented at CLKOUT / (PLLDIV1 *

(TDDR+1)), where CLKOUT is the DSP clock speed in MHz (see GBL Module Properties), and TDDR is the value of the timer dividedown register (see CLK Manager Properties). PLLDIV1 is an additional divide-down factor; DSP/BIOS assumes its value is 4. If you change the value of PLLDIV1, timings will be incorrect.

’C5503, ’C5507, ’C5509, ’C5510, ’C5561

1x10 and 59xx Decremented at: CLKOUT * (2^

OMAP 2320 Incremented at DSP clock speed Counter

OMAP 2420 Incremented at the INPUTCLK rate, which is

Decremented at CLKOUT / (TDDR+1), where CLKOUT is the DSP clock spee d in MHz (s ee GBL Module Properties) and TDDR is the value of the timer divide-down register (see CLK Manager Properties).

(TCRPTV+1)), where CLKOUT is the DSP clock speed in MHz (see GBL Module Properties) and TCRP TV is the v alue in t he presc alar register (see CLK Manage r Properties ).

usually either 32 kHz or 12 MHz (see CLK Manager Properties).

PRD value Counter reset to 0.

0 Counter reset to PRD

Counter register rolls over.

value.

Counter reset to 0.

Counter reset to period register value of 0xFFFFFFFF minus PRD value in CLK Manager Properties.

Low-Resolution Time Wh en the value of the timer counter is reset to the value in the right-

column of Table 2-1, the following actions happen:

❏ A timer interrupt occurs ❏ As a result of the timer interrupt, the HWI object for the timer runs the

CLK_F_isr function.

Application Program Interface 2-41

CLK Module

❏ The CLK_F_isr function causes the low-resolution time to be

incremented by 1.

❏ The CLK_F_isr function causes all the CLK Functions to be

performed in sequence in the context of that HWI.

Therefore, the low-res olution clock ticks at the time r interrupt rate and returns the number of tim er interrupts that have occur red. You can use the CLK_getltime function to get the low-resolution time and the CLK_getprd function to get the value of the period register property.

You can use GBL_setFrequency, CLK_stop, CLK_reconfig, and CLK_start to change the low-resolution timer rate.

The low-resolution time is stored as a 32-bit value. Its value restarts at 0 when the maximum value is reached.

High-Resolution Time The high-resolution time is determined as follows for your platform:

Table 2-2. High-Resolution Time Determination

Platform Description

’C5501, ’C5502 A separate DSP/BIOS counter for the high-resolution time

runs at the following rate: CLKOUT / PLLDIV1. This timer counter is stored in 64 bits.

’C5503, ’C5507, ’C5509, ’C5510, ’C5561

1x10 and 59xx Numbe r of times the timer counte r ha s been decremented. OMAP 2320 Number of times the timer counter has been incremented. OMAP 2420 The value of Timer 7 running at 12 MHz. This value is

Number of times the timer counter has been decremented.

stored in 32 bits.

2-42

You can use the CLK_geth time function to get the h igh-resolution time and the CLK_countspms funct ion to get the number of hardware tim er counter register ticks per millisecond.

The high-resolution t ime is stored as a 32-bit value . For platforms that use the same timer counter as the lo w-resolution time, the 32-bit highresolution time is actually calculated by multiplying the low-resolution time by the value of the PRD property and adding number of timer counter increments or dec rements (depending on your platform) si nce the last timer counter reset.

The high-resolution value restarts at 0 when the maximum value is reached.

CLK Module

CLK Functions The CLK functions performed when a timer interrupt occurs are

performed in the context of the hardware interrupt that caused the system clock to tick. Therefore , the a mou nt of p ro cess ing per fo rmed wi thi n CLK functions should be minimized and these functions can only invoke DSP/BIOS calls that are allowable from within an HWI.

Note:

CLK functions should not cal l HWI_enter and HWI_exit as these are called internally by DSP/BIOS when it runs CLK_F_isr. Additionally, CLK functions should not use the interrupt keyword or the INTERRUPT pragma in C functions.

CLK Manager Properties

The following global properties can be set for the CLK module in the CLK Manager Properties dia log of the DSP/BIOS Configuratio n Tool or in a Tconf script:

❏ Object Memory. The memory segment that contains the CLK

objects created in the configuration. Tconf Name: OBJMEMSEG Type: Reference Example: bios.CLK.OBJMEMSEG = prog.get("myMEM");

❏ CPU Interrupt. Shows which HWI interrupt is used to drive the timer

services. The value is cha nged automaticall y when you change th e Timer Selection. This is an informational property only.

Tconf Name: N/A

❏ Timer Selection. The on-devic e timer to use. Cha nging this setting

also automatically changes the CPU Interrupt used to drive the timer services and the function property of the relevant HWI objects.

Tconf Name: TIMERSELECT Type: String Options: "Timer 0", "Timer 1" (exception: "Timer 5" and "Timer

6" for OMAP 2420)

Example: bios.CLK.TIMERSELECT = "Timer 0";

❏ Base Address of Timers in IO Space. This property points to the

address of GP timer 5 within the DSP address space. This location is set by the DSP MMU configuration shown in Section D.2.2, GEL Configuration. The locations of timers 6 and 7 are determined by adding 0x0400 and 0x0800 respectively to the base address. (OMAP 2420 only)

Tconf Name: TIMERS_BASE Type: Numeric Example: bios.CLK.TIMERS_BASE = 0x07000;

Application Program Interface 2-43

CLK Module

❏ Base Address of Timers in Data Space. This property points to the

address of the O MAP 2420 time rs as mapp ed in the Data space by the ARM. (OMAP 2420 only)

Tconf Name: TIMERS_BASE_DATAMEM Type: Numeric Example: bios.CLK.TIMERS_BASE_DATAMEM = 0x7ee000;

❏ Enable CLK Manager. If this property is set to true, the on-device

timer hardware is used to drive the hi gh- and low-resolution times and to trigger execution of CLK functio ns. On platforms where the separate ENABLEHTIME property is available, setting the ENABLECLK prope rty to true and the ENABLEHTIME property to false enables only the low-resolution timer.

Tconf Name: ENABLECLK Type: Bool Example: bios.CLK.ENABLECLK = true;

❏ Use high resolution time for internal timings. If this property is set

to true, the high-reso lution tim er is used to monit or internal periods. Otherwise the less intrusive, low-resolution timer is used.

Tconf Name: HIRESTIME Type: Bool Example: bios.CLK.HIRESTIME = true;

❏ Enable high resolution timer. If this property is set to true, this

parameter enables the high-resolution timer. This property is available only for the ’ C5501, ’C5502, and OMAP 2320/2420. For platforms that use only one timer, the high-resolution and lowresolution timers are both enabled and disabled by the "Enable CLK Manager" property.

Tconf Name: ENABLEHTIME Type: Bool Example: bios.CLK.ENABLEHTIME = true;

2-44

❏ Microseconds/Int. The number of microseconds between timer

interrupts. The period register is set to a value that achieves the desired period as closely as possible.

Tconf Name: MICROSECONDS Type: Int16 Example: bios.CLK.MICROSECONDS = 1000;

❏ Directly configure on-device timer registers. If this property is set

to true, the timer’s hardware registers, PRD and TDDR, can be directly set to the des ired valu es. In this case, the M icrosec onds/Int property is computed based on the values in PRD and TDDR and the CPU clock speed in the GBL Module Properties.

Tconf Name: CONFIGURETIMER Type: Bool Example: bios.CLK.CONFIGURETIMER = false;

CLK Module

❏ Fix TDDR. If this property is set to true, the value in the TDDR

property is not modified by changes to the Microseconds/Int property. (Not available for OMAP 2320/2420.)

Tconf Name: FIXTDDR Type: Bool Example: bios.CLK.FIXTDDR = false;

❏ TDDR register. The value of the on-device timer prescalar. (Not

available for 1x10, 59xx, and OMAP 2320/2420.)

Platform Options Size Registers

’C5503, ’C5507, ’C5509, ’C5510, ’C5561

’C5501, ’C5502 00h to 0ffffffffh 32 bits PRD3:PRD4

00h to 0fh 4 bits part of TCR

Tconf Name: TCRTDDR Type: EnumInt Example: bios.CLK.TCRTDDR = 2;

❏ PRD Register. This value specifies the i nterrupt pe riod and is u sed

to configure the PRD register. The default value varies depending on the platform. The default value for ’C5501/5502 is 74999, for ’C5503/5507/5509/5510 is 46666, for 5561 is 59999, for OMAP2320 is 12000, and for OMAP 2420 is 32. (Not available for 1x10 and 59xx.)

Tconf Name: PRD Type: Int16 Example: bios.CLK.PRD = 33250;

❏ LOAD_TIM register. This value is used to configure the PRD

Tconf Name: LOAD_TIM Type: Int16 Example: bios.CLK.LOAD_TIM = 2999;

❏ PTV register. Sets the prescalar register value of the timer. This

value is used in calculating the rate at which the timer counter is decremented. The valid values of 0 to 7 lead to prescale values from 02 hex to 100 hex. (1x10 and 59xx only.)

Tconf Name: TCRPTV Type: EnumInt Options: 0 to 7 Example: bios.CLK.TCRPTV = 0;

Application Program Interface 2-45

CLK Module

❏ Clock Rate to ltime timer. Specify the rate in MHz for the low-

resolution time. O n the OMAP 2420, this may be either t he 0.032 MHz clock, the 12 MH z clock, or the external clock. (OMA P 2420 only .)

Tconf Name: INPUTCLK Type: Numeric Example: bios.CLK.INPUTCLK = 0.032;

❏ Clock Rate to htime timer. Specify the rate in MHz for the high-

resolution time. O n the OMAP 2420, this may be either t he 0.032 MHz clock, the 12 MH z clock, or the external clock. (OMA P 2420 only .)

Tconf Name: HTIMECLK Type: Numeric Example: bios.CLK.HTIMECLK = 12.0;

❏ Instructions/Int. The number of instruct ion cycles represented by

the period specified above. This is an informational property only. Tconf Name: N/A

CLK Object Properties The Clock Manager allows you to create an arbitrary number of CLK

objects. Clock objects have f unctions, wh ich are execute d by the Clo ck Manager every time a timer interrupt occurs. These functions can invoke any DSP/BIOS operations allowable from within an HWI except HWI_enter or HWI_exit.

To create a CLK object in a configuration script, use the following syntax:

var myClk = bios.CLK.create("myClk");

The following properties can be set for a clock function object in the CLK Object Properties dialog in the DSP/BIOS Configuration Tool or in a Tconf script. The Tconf examples assu me the myClk object has been created as shown.

❏ comment. Type a comment to identify this CLK object.

Tconf Name: comment Type: String Example: myClk.comment = "Runs timeFxn";

❏ function. The function to be executed when the timer hardware

interrupt occurs. This function must be written like an HWI function; it must be written in C or assembly and must save and restore any registers this func tion modifies. However, this function can not call HWI_enter or HWI_exit because DSP/BIOS calls them internally before and after this function runs.

These functions should be very short as they are performed frequently.

2-46

CLK Module

Since all CLK functions are performed at the same periodic rate, functions that need to run at a multiple of that rate should either count the number of interrupts and perform their activities when the counter reaches the appropriate value or be configured as PRD objects.

If this function is written in C and you are using the DSP/BIOS Configuration Tool, use a leading underscore before the C function name. (The DSP/BIOS Configuration Tool generates assembly code, which must use leading underscores when referencing C functions or labels.) If you are using Tconf, do not add an underscore before the function nam e; Tconf adds the underscore needed t o call a C function from assembly internally.

Tconf Name: fxn Type: Extern Example: myClk.fxn = prog.extern("timeFxn");

❏ order. You can change the sequence in which CLK functions are

executed by specifying the order property of all the CLK functions. Tconf Name: order Type: Int16 Example: myClk.order = 2;

Application Program Interface 2-47

CLK_countspms

Number of hardware timer counts per millis econd

C Interface

Syntax ncounts = CLK_countspms(); Parameters Void

Return Value LgUns ncounts; Reentrant yes Description CLK_countspms returns the n umber of hig h-resolution ti mer counts per

millisecond. CLK_count spms can be used to compu te an abs olute leng th of tim e from

the number of low resolution ti me r inte rrup ts. For e xampl e, th e fol lo win g code computes time in milliseconds.

timeAbs = (CLK_getltime() * CLK_getprd()) / CLK_countspms();

The equation below computes time in milliseconds since the last wrap of the high-resolution timer counter.

timeAbs = CLK_gethtime() / CLK_countspms();

CLK_cpuCyclesPerHtime

Return multiplier for converting high-res time to CPU cycles

C Interface

Syntax ncycles = CLK_cpuCyclesPerHtime(Void); Parameters Void

Return Value Float ncycles; Reentrant yes Description CLK_cpuCyclesP erHtime returns th e multiplier r equired to conve rt from

high-resolution time to CPU c ycles. High-resolution time is returned by CLK_gethtime.

For example, the following code returns the numbe r of CPU cycles and the absolute time elapsed during processing.

time1 = CLK_gethtime(); ... processing ... time2 = CLK_gethtime(); CPUcycles = (time2 - time1) * CLK_cpuCyclesPerHtime(); /* calculate absolute time in milliseconds */ TimeAbsolute = CPUCycles / GBL_getFrequency();

CLK_cpuCyclesPerLtime

Return multiplier for converting low- res time to CPU cycles

C Interface

Syntax ncycles = CLK_cpuCyclesPerLtime(Void); Parameters Void

Return Value Float ncycles; Reentrant yes Description CLK_cpuCyclesP erLtime return s the multipl ier required to convert fro m

low-resolution time to CPU cycles. Low-resolution time is returned by CLK_gethtime.

For example, the following code returns the numbe r of CPU cycles and milliseconds elapsed during processing.

time1 = CLK_getltime(); ... processing ... time2 = CLK_getltime(); CPUcycles = (time2 - time1) * CLK_cpuCyclesPerLtime(); /* calculate absolute time in milliseconds */ TimeAbsolute = CPUCycles / GBL_getFrequency();

CLK_gethtime

Get high-resolution time

C Interface

Syntax currtime = CLK_gethtime(); Parameters Void

Return Value LgUns currtime /* high-resolution time */ Reentrant no Description CLK_gethtime returns the number of high-resolution clock cycles that

have occurred as a 32-bit value. When the number of cycles reaches the maximum value that can be stored in 32 bits, the value wraps back to 0.

See “High-Resolution Time” on page 2-42 for information about how this rate is set.

CLK_gethtime provides a value with greater accuracy than CLK_getltime, but which wraps back to 0 more freq uently. For example, if the timer tick rate is 200 MHz, then regardless of the period r egister value, the CLK_get htime valu e wraps back to 0 app roximat ely every 86 seconds.

CLK_gethtime can be used in conjun ction with STS_set a nd STS_ delta to benchmark code. CLK_gethtime can also be used to add a time stamp to event logs.

Constraints and

❏ CLK_gethtime cannot be called from the program’s main() function.

Calling Context Example /* ======== showTime ======== */

Void showTicks {

LOG_printf(&trace, "time = %d", CLK_gethtime());

}

CLK_getltime

Get low-resolu tio n ti m e

C Interface

Syntax currtime = CLK_getltime(); Parameters Void

Return Value LgUns currtime /* low-resolution time */ Reentrant yes Description CLK_getltime returns the num ber of timer interrupts that have oc curred

as a 32-bit time value. When the number of interrupts reaches the maximum value tha t can be stored in 32 bits, valu e wraps back to 0 o n the next interrupt.

The low-resolution time is the number of timer interrupts that have occurred. See “Low-Resolution Time” on page 2-41 for information about how this rate is set.

The default low resolution interrupt rate is 1 millisecond/interrupt. By adjusting the period register, you can set rates from less than 1 microsecond/interrupt to more than 1 second/interrupt.

CLK_gethtime provides a v alue with more ac curacy than CLK _getltime , but which wraps back to 0 more frequently. For example, if the timer tick rate is 80 MHz, and y ou use the defau lt period reg ister value of 40000, the CLK_gethtime value wraps back to 0 approximately every 107 seconds, while t he CLK_getltime value wraps back to 0 approximately every 49.7 days.

CLK_getltime is often used to add a time stamp to event log s for events that occur over a relatively long period of time.

Constraints and

❏ CLK_getltime cannot be called from the program’s main() function.

Calling Context Example /* ======== showTicks ======== */

Void showTicks {

(Int)(CLK_getltime() >> 16), (Int)CLK_getltime());

LOG_printf(&trace, "time = 0x%x %x",

}

CLK_getprd

Get period register value

C Interface

Syntax period = CLK_getprd(); Parameters Void

Return Value Uns period /* period register value */ Reentrant yes Description CLK_getprd returns the numbe r of high-resoluti on timer counts per low-

resolution interrupt. CLK_getprd can be used to compute an absolute length of time from the

number of low-resolution timer interrupts. For example, the following code computes time in milliseconds.

timeAbs = (CLK_getltime() * CLK_getprd()) / CLK_countspms();

CLK_reconfig

C Interface

Syntax status = CLK_reconfig(); Parameters Void

Return Value Bool status /* FALSE if failed */ Reentrant yes Description This function needs to be called after a call to GBL_setFrequency. It

Reset timer period and registers using current CPU frequency

computes values fo r the timer period and th e prescalar registers using the new CPU frequency. The new values for the period and pre scalar registers ensure that the CLK interrupt runs at th e statically configured interval in microseconds.

The return value is FALSE if the timer registers cannot accommodate the current frequency or if some other internal error occurs.

When calling CLK_reconfig outside of main(), you must also call CLK_stop and CLK_start to sto p a nd restart th e ti me r. Use the following call sequence:

2-54

/* disable interrupts if an interrupt could lead to another call to CLK_reconfig or if interrupt processing relies on having a running timer */ HWI_disable() or SWI_disable() GBL_setFrequency(cpuFreqInKhz); CLK_stop(); CLK_reconfig(); CLK_start(); HWI_restore() or SWI_enable()

When calling CLK_reconfig from main(), the timer has not yet been started. (The timer i s started as part of BIOS_ startup(), which is cal led internally after main.) As a result, you can use the following simplified call sequence in main():

GBL_setFrequency(cpuFreqInKhz); CLK_reconfig(Void);

Note that GBL_setFrequency does not affect the PLL, and therefore has no effect on the actual fr eq uen cy a t wh ic h t he DSP i s r unni ng . It is u sed only to make DSP/BIOS aware of the DSP frequency you are using.

CLK_reconfig

Constraints and Calling Context

❏ When calling CLK_rec onfig from anywhere other than main(), you

must also use CLK_stop and CLK_start.

❏ Call HWI_disable/HWI _restore or SWI_disa ble/SWI_enable ar ound

a block that stops, confi gures, and restarts the timer as needed t o prevent re-entrancy or other problems. That is, you must disable interrupts if an interrupt could lead to another call to CLK_reconfig or if interrupt processing relies on having a running timer to ensure that these non-reentrant functions are not interrupted.

❏ If you use the PWRM module for V/F sc aling and the "Reprogram

BIOS clock after frequency scaling" PWRM property is configured as "true", do not call CLK_reconfig. This is because the PWRM module internally calls this API.

❏ If you do not stop an d restart the timer, CLK_reconfig can only b e

called from the program’s main() function.

❏ If you use CLK_reconfig, you should also use GBL_setFrequency.

CLK_start

C Interface

Syntax CLK_start();

Parameters Void

Return Value Void Reentrant no Description This function starts the low-resolution timer if it has been halted by

Constraints and Calling Context

Restart the low-r e solution timer

CLK_stop. The period and prescalar registers are updated to reflect any changes made by a call to CLK_reconfig. This function then rese ts the timer counters and starts the timer.

CLK_start should only be used in conjunction with CLK_reconfig and CLK_stop. See the sec tion on CL K_reco nfig for details and the allowed calling sequence.

Note that all ’C55x platforms except the ’C5501, ’C5502, and OMAP 2320/2420 use the same timer to drive low-resolution and high-resolution times. On such platforms, both times are affected by this API.

❏ Call HWI_disable/HWI_ restore or SWI_disa ble/SWI_enable around

a block that stops, confi gures, and restarts the timer as needed t o prevent re-entrancy or other problems. That is, you must disable interrupts if an inter rupt could le ad to another call to CLK _start or if interrupt processi ng relies on hav ing a running timer to ensure that these non-reentrant functions are not interrupted

❏ This function cannot be called from main(). ❏ If you use the PWRM module for V/F sc aling and the "Reprogram

BIOS clock after frequency scaling" PWRM property is "true", do not call CLK_start. This is because the PWRM module in ternally calls this API.

CLK_stop

Halt the low-resolution timer

C Interface

Syntax CLK_stop(); Parameters Void

Return Value Void Reentrant no Description This function stops the low-resolution timer. It can be used in conjunction

with CLK_reconfig and CLK_start to reconfigure the timer at run-time. Note that all ’C55x platforms except the ’C5501, ’C5502, and OMAP

2320/2420 use the same timer to drive low-resolution and high-resolution times. On such platforms, both times are affected by this API.

CLK_stop should only be used in conjunction with CLK_reconfig and CLK_start, and only in the required calling sequence. See the section on CLK_reconfig for details.

Constraints and Calling Context

❏ Call HWI_disable/HWI _restore or SWI_disa ble/SWI_enable ar ound

a block that stops, confi gures, and restarts the timer as needed t o prevent re-entrancy or other problems. That is, you must disable interrupts if an int errupt co uld lead to another cal l to CLK_st op or if interrupt processi ng relies on hav ing a running ti mer to ensure that these non-reentrant functions are not interrupted

❏ This function cannot be called from main(). ❏ If you use the PWRM module for V/F sc aling and the "Reprogram

BIOS clock after frequency scaling" PWRM property is "true", do not call CLK_stop. This is because the PWRM module internally calls this API.

2.5 DEV Module

Important Note: The DEV module is being deprecated and will no

longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver D evelo per ’s Guide (SPRU61 6). The D EV modul e is still supported in DS P/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.

The DEV module provides the device interface.

Functions ❏ DEV_createDevice. Dynamically create device

❏ DEV_deleteDevice. Delete dynamically-created device ❏ DEV_match. Match device name with driver

❏ Dxx_close. Close device ❏ Dxx_ctrl. Device control ❏ Dxx_idle. Idle device ❏ Dxx_init. Initialize device ❏ Dxx_issue. Send frame to device ❏ Dxx_open. Open device ❏ Dxx_ready. Device ready ❏ Dxx_reclaim. Retrieve frame from device

Description DSP/BIOS provides two device driver models that enable applications to

communicate with DSP peripherals: IOM and SIO/DEV. The components of the IOM model are illust rated in the follow ing figu re.

It separates hardware-independent and hardware-dependent layers. Class drivers are hardware independent; they manage device instances, synchronization and serialization of I/O req uests. The lower-level minidriver is hardware-dependent. See the DSP/BIOS Driver Developer’s Guide (SPRU616) for more information on the IOM model.

2-58

Application / Framew ork

DEV Module

Device Driver

Class Driver

MiniDriver

PIP APIs

PIO Ad a p te r DIO Ad a p te r

On-Chip Peripheral Hardware

SIO APIs

GIO APIs

IOM Mini-Driver(s)

Chip Support Library (CSL)

Off-Chip Peripheral Hardware

The SIO/DEV model provides a streaming I/O interface. In this model, the application indi rectly invokes DEV function s implemented by the driver managing the physical device attached to the stream, using generic functions provided by the S I O m odule. S ee the DSP/BIOS User’s Guide (SPRU423) for more information on the SIO/DEV model.

The model used by a device is identified by its function table type. A type of IOM_Fxns is used with the IOM model. A type of DEV_Fxns is used with the DEV/SIO model.

The DEV module provides the following capabilities: ❏ Device object creation. You can create device objects through

static configuration or dynamically through the DEV_createDevice function. The DEV_deleteDevice and DEV_match functions are also provided for managing device objects.

❏ Driver function templates. The Dxx functions listed as part of the

DEV module are templates for driver functions. These are the functions you create for drivers that use the DEV/SIO model.

Application Program Interface 2-59

DEV Module

Constants, Types, and Structures

#define DEV_INPUT 0 #define DEV_OUTPUT 1

typedef struct DEV_Frame { /* frame object */ QUE_Elem link; /* queue link */ Ptr addr; /* buffer address */ size_t size; /* buffer size */ Arg misc; /* reserved for driver */ Arg arg; /* user argument */ Uns cmd; /* mini-driver command */ Int status; /* status of command */ } DEV_Frame;

typedef struct DEV_Obj { /* device object */

QUE_Handle todevice; /* downstream frames here */ QUE_Handle fromdevice; /* upstream frames here */ size_t bufsize; /* buffer size */ Uns nbufs; /* number of buffers */ Int segid; /* buffer segment ID */ Int mode; /* DEV_INPUT/DEV_OUTPUT */

#if (defined(_54_) && defined(_FAR_MODE)) || defined(_55_)

LgInt devid; /* device ID */ #else Int devid; /* device ID */ #endif Ptr params; /* device parameters */ Ptr object; /* ptr to dev instance obj */ DEV_Fxns fxns; /* driver functions */ Uns timeout; /* SIO_reclaim timeout value */ Uns align; /* buffer alignment */ DEV_Callback *callback; /* pointer to callback */ } DEV_Obj;

2-60

typedef struct DEV_Fxns { /* driver function table */

Int (*close)( DEV_Handle ); Int (*ctrl)( DEV_Handle, Uns, Arg ); Int (*idle)( DEV_Handle, Bool ); Int (*issue)( DEV_Handle ); Int (*open)( DEV_Handle, String ); Bool (*ready)( DEV_Handle, SEM_Handle ); size_t (*reclaim)( DEV_Handle );

} DEV_Fxns;

typedef struct DEV_Callback { Fxn fxn; /* function */ Arg arg0; /* argument 0 */ Arg arg1; /* argument 1 */ } DEV_Callback;

DEV Module

typedef struct DEV_Device { /* device specifier */ String name; /* device name */ Void * fxns; /* device function table*/

#if (defined(_54_) && defined(_FAR_MODE)) || defined(_55_)

LgInt devid; /* device ID */ #else Int devid; /*device ID */ #endif Ptr params; /* device parameters */ Uns type; /* type of the device */ Ptr devp; /* pointer to device handle */ } DEV_Device;

typedef struct DEV_Attrs {

#if (defined(_54_) && defined(_FAR_MODE)) || defined(_55_)

LgInt devid; /* device id */ #else Int devid; /* device id */ #endif Ptr params; /* device parameters */ Uns type; /* type of the device */ Ptr devp; /* device global data ptr */ } DEV_Attrs;

Configuration Properties

DEV Manager Properties

The following lis t sh ows th e p roper ti es th at ca n b e c on fig ur ed in a Tconf script, along with their types and default values. For details, see the DEV Manager Properties and DEV Object Properties headings. For descriptions of data type s, see Secti on 1.4, DSP/ BIOS Tconf Overview, page 1-3.

Instance Configuration Parameters

Name Type Default (Enum Options)

comment String "<add comments here>" initFxn Arg 0x00000000 fxnTable Arg 0x00000000 fxnTableType EnumString "DEV_Fxns" ("IOM_Fxns") deviceId Arg 0x00000000 params Arg 0x00000000 deviceGlobalDataPtr Arg 0x00000000

The default configuration contains managers for the following built-in device drivers:

❏ DGN Driver (software generator driver). pseudo-device that

generates one of sever al data streams, su ch as a sin/cos se ries or white noise. This driver can be useful for testing applications that require an input stream of data.

Application Program Interface 2-61

DEV Module

❏ DHL Driver (host link driver). Driver that uses the HST interface to

send data to and from the Host Channel Control Analysis Tool.

❏ DIO Adapter (class driver). Driver used with the device driver

model.

❏ DPI Driver (pipe driver). Software device used to stream data

between DSP/BIOS tasks.

To configure devices for other drivers, use T conf to create a User-defined Device (UDEV) object. There are no global properties for the userdefined device manager.

The following additional device drivers are supplied with DSP/BIOS:

❏ DGS Driver. Stackable gather/scatter driver ❏ DNL Driver. Null driver ❏ DOV Driver. Stackable overlap driver ❏ DST Driver. Stackable “split” driver ❏ DTR Driver. Stackable streaming transformer driver

DEV Object Properties The following properties can be set for a user-defined device in the UDEV

Object Properties dialog in the DSP/BIOS Configuration Tool or in a Tconf script. To create a user-defin ed device object in a configuration script, use the following syntax:

var myDev = bios.UDEV.create("myDev");

The Tconf examples assume the myDev object is created as shown. ❏ comment. Type a comment to identify this object.

Tconf Name: comment Type: String Example: myDev.comment = "My device";

❏ init function. Specify the function to run to initialize this device.

Use a leading underscore befo re the function name if the function is written in C and you a re using the DSP/ BIOS Configuration Tool. If you are using Tconf, do not add an underscore b efore the function name; Tconf adds the undersco re needed to call a C func tion from assembly internally.

Tconf Name: initFxn Type: Arg Example: myDev.initFxn = prog.extern("myInit");

❏ function table ptr . Specify the name of the device functions table for

the driver or mini-d river. This table is of t ype D EV_Fxn s or IOM_F xns depending on the setting for the function table type property.

Tconf Name: fxnTable Type: Arg Example: myDev.fxnTable =

prog.extern("mydevFxnTable");

2-62

DEV Module

❏ function table type. Choose the type of function table used by the

driver to which this device interfaces. Use the IOM_Fxns option if you are using the DIO class driver to interface to a mini-driver with an IOM_Fxns function table. Otherw ise, use the DEV_Fxns option for other drivers that use a DEV_Fxns function table and Dxx functions. Y ou can create a DIO object only if a UDEV object with the IOM_Fxns function table type exists.

Tconf Name: fxnTableType Type: EnumString Options: "DEV_Fxns", "IOM_Fxns" Example: myDev.fxnTableType = "DEV_Fxns";

❏ device id. Specify the device ID. If the value you provide is non-zero,

the value takes the plac e of a value t hat would be ap pended to the device name in a call to SIO_create. The purpose of such a value is driver-specific.

Tconf Name: deviceId Type: Arg Example: myDev.deviceId = prog.extern("devID");

❏ device params ptr. If this device uses additional parameters,

provide the name o f the parameter str ucture. This str ucture should have a name with the format DXX_Params where XX is the two-letter code for the driver used by this device.

Use a leading under scor e before the s truct ure nam e if the s truct ure is declared in C and you are using the DSP/BIOS Configuration Tool.

Tconf Name: params Type: Arg Example: myDev.params = prog.extern("myParams");

❏ device global data ptr. Provide a poin ter to any global data to be

used by this device. Th is value can be s et only if the funct ion table type is IOM_Fxns.

Tconf Name: deviceGlobalDataPtr Type: Arg Example: myDev.deviceGlobalDataPtr = 0x00000000;

Application Program Interface 2-63

DEV_createDevice

C Interface

Syntax status = DEV_createDevice(name, fxns, initFxn, attrs); Parameters String name; /* name of device to be created */

Return Value Int status; /* result of operation */ Reentrant no Description DEV_createDevice allows an application to create a user-defined device

Dynamically create device

Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API i s still supported in DSP /BIOS 5.32 and will be supported in any patch relea ses or mino r enhancements to DSP/BIOS

5.32.

Void *fxns; /* pointer to device function table */ Fxn initFxn; /* device init function */ DEV_Attrs *attrs; /* pointer to device attributes */

object at run-time. The ob ject created has parameters similar to those defined statically for the DEV Obje ct P ro perti es . After bei ng cr ea ted , the device can be used as with statically-created DEV objects.

2-64

The name parameter specifies the name of the device. The device name should begin with a slash (/) for consistency with statically-created devices and to permit stacking drivers. For example "/codec" might be the name. The name must be unique with in the application. If the specified device name already exists, this function returns failure.

The fxns parameter points to the device function table. The function table may be of type DEV_Fxns or IOM_Fxns.

The initFxn parameter specifies a device initialization function. The function passed as this parameter is run if the device is created successfully. The initialization fun ction is called with in terrupts disabled . If several devices ma y use the sa me drive r, the initialization f unction ( or a function wrapper) should ensure that one-time initialization actions are performed only once.

DEV_createDevice

The attrs parameter points to a structure of type DEV_Attrs. This structure is used to pass additional device attributes to DEV_createDevice. If at trs is NULL, the device is created with default attributes. DEV_Attrs has the following structure:

typedef struct DEV_Attrs {

#if (defined(_54_) && defined(_FAR_MODE)) || defined(_55_)

LgInt devid; /* device id */ #else Int devid; /* device id */ #endif Ptr params; /* device parameters */ Uns type; /* type of the device */ Ptr devp; /* device global data ptr */ } DEV_Attrs;

The devid item sp ecifies the de vice ID. If the v alue you pro vide is nonzero, the value takes the place of a value that would be appended to the device name in a call to SIO_create. The purpose of such a value is driver-specific. The default value is NULL.

The params item specifi es the name of a parameter structure t hat may be used to provide ad ditional parameters. T his structure sho uld have a name with the format DXX_Para ms where XX is the two-letter code for the driver used by this device. The default value is NULL.

The type item specifies the type of driver used with this device. The default value is DEV_IOMTYPE. The options are:

Type Use With

DEV_IOMTYPE DEV_SIOTYPE DIO adapter with SIO streams or

Mini-drivers used in the IOM model

other DEV/SIO drivers

The devp item specifi es the device global data pointe r, which points to any global data to be used by this device. This value can be set only if the table type is IOM_Fxns.The default value is NULL.

If an initFxn is specified, that function is called as a result of calling DEV_createDevice. In addition, if the device type is DEV_IOMTYPE, the mdBindDev function in the function table pointed to by the fxns parameter is called as a result of calling DEV_createDevice. Both of these calls are made with i nterrupts disabled.

Application Program Interface 2-65

DEV_createDevice

DEV_createDevice returns one of the following status values:

Constant Description

SYS_OK Success. SYS_EINVAL A device with the specified name already exists. SYS_EALLOC The heap is not large enough to allocate the device.

DEV_createDevice calls SYS_error if mdBindDev returns a failure condition. The device is not created if mdBindDev fails, and DEV_createDevice returns the IOM error returned by the mdBindDev failure.

Constraints and Calling Context

❏ This function cannot be called from a SWI or HWI. ❏ This function can only be used if dynamic memory allocation is

enabled.

❏ The device function table mu st be con sistent wi th the type spe cifie d

in the attrs st ructure. DSP/BI OS does not ch eck to ensure tha t the types are consistent.

Example Int status;

/* Device attributes of device "/pipe0" */ DEV_Attrs dpiAttrs = { NULL, NULL, DEV_SIOTYPE, 0 };

status = DEV_createDevice("/pipe0", &DPI_FXNS, (Fxn)DPI_init, &dpiAttrs); if (status != SYS_OK) { SYS_abort("Unable to create device"); }

DEV_deleteDevice

Delete a dynamically-created device

Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API i s still supported in DSP/BI OS 5.32 and will be supported in any patch relea ses or mino r enhancements to DSP/BIOS

5.32.

C Interface

Syntax status = DEV_deleteDevice(name); Parameters String name; /* name of device to be deleted */

Return Value Int status; /* result of operation */ Reentrant no Description DEV_deleteDevice deallocates the specified dynamically-created device

and deletes it from the list of devices in the application. The name parameter specifies the device to delete. This name must

match a name used with DEV_createDevice. Before deleting a dev ice, delete any SIO streams that use the de vice.

SIO_delete cannot be called after the device is deleted.

Constraints and Calling Context

If the device type is DEV_IO MTYPE, the mdUnBindDev function in the function table pointed to by the fx ns parameter of the device is call ed as a result of calling DEV_deleteDevice. This call is made with in terrupts disabled.

DEV_createDevice returns one of the following status values:

Constant Description

SYS_OK Success. SYS_ENODEV No device with the specified name exists.

DEV_deleteDevice calls SYS_error if mdUnBindDev returns a failure condition. The device is deleted even if mdUnBindDev fails, but DEV_deleteDevice returns the IOM error returned by mdUnBindDev.

❏ This function cannot be called from a SWI or HWI.

Application Program Interface 2-67

DEV_deleteDevice

❏ This function can be used only if dynamic memory allocation is

enabled.

❏ The device name must match a dynamically-created device.

DSP/BIOS does not check that the device was not created statically.

Example status = DEV_deleteDevice("/pipe0"); See Also SIO_delete

2-68

DEV_match

Match a device name with a driver

Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API i s still supported in DSP/BI OS 5.32 and will be supported in any patch relea ses or mino r enhancements to DSP/BIOS

5.32.

C Interface

Syntax substr = DEV_match(name, device);

Parameters String name; /* device name */

DEV_Device **device; /* pointer to device table entry */

Return Value String substr; /* remaining characters after match */ Description DEV_match searches the device table for the first device name that

matches a prefix of name. The output parameter, device, points to the appropriate entry in the device tabl e if s uccess ful and is s et to NU LL on error. The DEV_Device structure is defined in dev.h.

The substr return value contains a pointer to the characters remain ing after the match. This string is used by stacking devices to specify the name(s) of underlying de vices (for example, /s cale10/sine might matc h /scale10, a stacking de vice, which wou ld, in turn, use /sine t o open the underlying generator device).

Dxx_close

Close device

5.32.

C Interface

Syntax status = Dxx_close(device); Parameters DEV_Handle device; /* device handle */ Return Value Int status; /* result of operation */

Description Dxx_close closes the device associated with device and returns an error

code indicating success (SYS_OK) or failure. device is bound to the device through a prior call to Dxx_open.

SIO_delete fi rst calls D xx_i dle t o idle the devi ce. Th en i t call s Dx x_clos e. Once device has been closed, the underlying device is no longer

accessible via this descriptor.

Constraints and

❏ device must be bound to a device by a prior call to Dxx_open.

Calling Context See Also Dxx_idle

Dxx_open SIO_delete

2-70

Dxx_ctrl

Device control operation

Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API i s still supported in DSP/BI OS 5.32 and will be supported in any patch relea ses or mino r enhancements to DSP/BIOS

5.32.

C Interface

Syntax status = Dxx_ctrl(device, cmd, arg);

Parameters DEV_Handle device /* dev ice hand le */

Uns cmd; /* driver control code */ Arg arg; /* control operation argument */

Return Value Int status; /* result of operation */ Description Dxx_ctrl performs a control operation on the device associated with

device and returns an error code indicating success (SYS_OK) or failure. The actual control operatio n is designated through cmd and arg, which are interpreted in a driver-dependent manner.

Dxx_ctrl is called by SIO_ctrl to send control commands to a device.

Constraints and

❏ device must be bound to a device by a prior call to Dxx_open.

Calling Context See Also SIO_ctrl

Application Program Interface 2-71

Dxx_idle

C Interface

Syntax statu s = Dxx_idle(device, flush); Parameters DEV_Handle device; /* device handle */

Return Value Int status; /* result of operation */

Description Dxx_idle places the dev ice assoc iated with devic e into its idle s tate and

Idle device

5.32.

Bool flush; /* flush output flag */

returns an error code indicating success (SYS_O K) or failure. Devices are initially in this state after they are opened with Dxx_open.

Dxx_idle returns th e d ev ice to i ts in iti al s tate. Dx x_ id le sh oul d mov e any frames from the device->todevice queue to the device->fromdevice queue. In SIO_ISSUERECLAIM mode, any outstanding buffers issued to the stream must be reclaimed in order to return the device to its true initial state.

Dxx_idle is called by SIO_idle, SIO_flush, and SIO_delete to recycle frames to the appropriate queue.

flush is a bool ean parame ter that i ndica tes what to d o with any pen ding data of an output stream. If flu sh is T RUE, all pendin g data is disc arde d and Dxx_idle does not block wait ing fo r da ta to be proces sed. I f flus h is FALSE, the Dxx_idle function does not return until all pending output data has been rendered. All pending data in an input stream is always discarded, without waiting.

Constraints and Calling Context

Texas Instruments TMS320C55 Series Reference Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Read This First

Contents

Figures

Tables

API Functional Overview

1.1 DSP/BIOS Modules

1.2 Naming Conventions

1.3 Assembly Language Interface Overview

1.4 DSP/BIOS Tconf Overview

1.5 List of Operations

Application Program Interface

2.1 ATM Module

ATM_andi

ATM_andu

ATM_cleari

ATM_clearu

ATM_deci

ATM_decu

ATM_inci

ATM_incu

ATM_ori

ATM_oru

ATM_seti

ATM_setu

2.2 BUF Module

BUF_alloc

BUF_create

BUF_delete

BUF_free

BUF_maxbuff

BUF_stat

2.3 C55 Module

C55_disableIER0, C55_disableIER1

C55_disableInt

C55_enableIER0, C55_enableIER1

C55_enableInt

C55_l2AckInt

C55_l2DisableMIR

C55_l2DisableMIR1

C55_l2EnableMIR

C55_l2EnableMIR1

C55_l2SetIntPriority

C55_plug

2.4 CLK Module

CLK_countspms

CLK_cpuCyclesPerHtime

CLK_cpuCyclesPerLtime

CLK_gethtime

CLK_getltime

CLK_getprd

CLK_reconfig

CLK_start

CLK_stop

2.5 DEV Module

DEV_createDevice

DEV_deleteDevice

DEV_match

Dxx_close

Dxx_ctrl

Dxx_idle