Texas Instruments TMS320C55 Series Reference Manual Download Page 29

Page: 29 / 599

2-1

Chapter 2

Application Program Interface

This chapter describes the DSP/BIOS API modules and functions.

2.1

ATM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2

2.2

BUF Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–15

2.3

C55 Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–26

2.4

CLK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–39

2.5

DEV Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–58

2.6

GBL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–108

2.7

GIO Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–118

2.8

HOOK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–137

2.9

HST Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–143

2.10 HWI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–148

2.11 IDL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–172

2.12 LCK Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–176

2.13 LOG Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–183

2.14 MBX Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–195

2.15 MEM Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–201

2.16 MSGQ Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–229

2.17 PIP Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–265

2.18 POOL Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–285

2.19 PRD Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–290

2.20 PWRM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–298

2.21 QUE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–336

2.22 RTDX Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–353

2.23 SEM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–369

2.24 SIO Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–382

2.25 STS Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–412

2.26 SWI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–422

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

Topic

Page

Summary of Contents for TMS320C55 Series

Page 1: ...TMS320C55x DSP BIOS 5 32 Application Programming Interface API Reference Guide Literature Number SPRU404N September 2007 ...

Page 2: ...vice 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 governing such use Buye...

Page 3: ...er Studio online tutorial and the DSP BIOS section of the online help to get an overview of DSP BIOS This manual discusses various aspects of DSP BIOS in depth and assumes that you have at least a basic understanding of DSP BIOS Notational Conventions This document uses the following conventions Program listings program examples and interactive displays are shown in a special typeface Examples use...

Page 4: ... ANSI standard C source code and produces TMS320 assembly language source 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 SPRH097 introduces the Code Composer Studio in...

Page 5: ...print Trademarks MS DOS Windows and Windows NT are trademarks of Microsoft Corporation The Texas Instruments logo and Texas Instruments are registered trademarks of Texas Instruments Trademarks of Texas Instruments include TI XDS Code Composer Code Composer Studio Probe Point Code Explorer DSP BIOS RTDX Online DSP Lab BIOSuite SPOX TMS320 TMS320C28x TMS320C54x TMS320C55x TMS320C62x TMS320C64x TMS3...

Page 6: ...vi ...

Page 7: ...the DSP BIOS API modules and functions 2 1 ATM Module 2 2 2 2 BUF Module 2 15 2 3 C55 Module 2 26 2 4 CLK Module 2 39 2 5 DEV Module 2 58 2 6 GBL Module 2 108 2 7 GIO Module 2 118 2 8 HOOK Module 2 137 2 9 HST Module 2 143 2 10 HWI Module 2 148 2 11 IDL Module 2 172 2 12 LCK Module 2 176 2 13 LOG Module 2 183 2 14 MBX Module 2 195 2 15 MEM Module 2 201 2 16 MSGQ Module 2 229 2 17 PIP Module 2 265 ...

Page 8: ... Conventions B 2 B 3 Status Register Conventions B 4 C DSP BIOS for OMAP 2320 C 1 This appendix describes things you need to know about DSP BIOS in order to use it with the OMAP 2320 platform C 1 Overview C 2 C 2 OMAP 2320 and the CLK Module C 2 C 3 OMAP 2320 and the HWI Module C 4 C 4 OMAP 2320 and the C55 Module C 8 C 5 Building DSP BIOS Applications for OMAP 2320 C 8 C 6 Usage Examples C 9 D DS...

Page 9: ... 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 ...

Page 10: ...or 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 SYS_printf 2 458 2 8 Conversion Characters Recognized by SYS_sprintf 2 460 2 9 Conversion Characters Recognized by SYS_vprintf 2 462 2 10 Conversion Characters Recognized by SYS_vsprintf 2 464 2 11 Events and Statistics Traced by ...

Page 11: ...his chapter provides an overview to the TMS320C55x DSP BIOS API functions 1 1 DSP BIOS Modules 1 2 1 2 Naming Conventions 1 3 1 3 Assembly Language Interface Overview 1 3 1 4 DSP BIOS Tconf Overview 1 3 1 5 List of Operations 1 5 Topic Page ...

Page 12: ...ction 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 application s power consumption QUE Module Queue manager RTDX Module Real tim...

Page 13: ...eeded to call a C function from assembly 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 register usage...

Page 14: ...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 Properties ...

Page 15: ...evious value ATM_seti ATM_setu Atomically set memory and return previous value 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 De...

Page 16: ...plier 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 Function Operation DEV_create...

Page 17: ... DNL Driver Null driver DOV Driver Stackable overlap driver DPI Driver Pipe driver DST Driver Stackable split driver DTR Driver Stackable streaming transformer driver 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 info...

Page 18: ...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 command Function Operation HOOK_getenv Get environment pointer for a given HOOK and TSK combination HOOK_setenv Set environment pointer for a given HOOK and TSK combination Function Operation HST_getpipe Get corresponding pipe object Fu...

Page 19: ...L_run Make one pass through idle functions Function Operation LCK_create Create a resource lock LCK_delete Delete a resource lock LCK_pend Acquire ownership of a resource lock LCK_post Relinquish ownership of a resource lock 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 L...

Page 20: ...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 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 MS...

Page 21: ...cQueue Sets the reply destination in a message 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 Get the value of the readerAddr pointer of the pipe PIP_getReaderNumFrames Get the number of pipe frames available for reading PIP_getReaderSize Get the number of words of data ...

Page 22: ...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 Get the latency to scale between setpoints PWRM_idleClocks Immediately idle the clock d...

Page 23: ...ment in queue non atomically QUE_prev Return previous element in queue non atomically QUE_put Put element at end of queue atomically QUE_remove Remove from middle of queue non atomically 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_disable...

Page 24: ...itialize 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 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 stre...

Page 25: ...ject STS_reset Reset the values stored in an STS object STS_set Store initial value of an interval to object 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 inter...

Page 26: ... 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 Formatted output SYS_putchar Output a single character 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...

Page 27: ...K_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 Function Operation atexit Registers one o...

Page 28: ...IOS 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 ...

Page 29: ... 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...

Page 30: ...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 data share...

Page 31: ...omically 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 ATM_andi is written in assembly language efficiently disabling interrupts on the target processor during the call See Also ATM_andu ATM_ori ATM_andi Atomically AND Int memory location...

Page 32: ...the mask contained in usrc with a destination 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_andu is written in assembly language efficiently disabling interrupts on the target processor during the call See Also ATM_andi ATM_oru ATM_andu Atomically AND Uns memory location and return pr...

Page 33: ...ription 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 See Also ATM_clearu ATM_seti ATM_cleari Atomically clear Int memory location and return previous value ...

Page 34: ...aru atomically 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 See Also ATM_cleari ATM_setu ATM_clearu Atomically clear Uns memory location and return previous value ...

Page 35: ...ry location and returns its new value as follows interrupt disable ival idst 1 idst ival interrupt enable return ival ATM_deci is written in assembly language efficiently disabling interrupts on the target processor during the call Decrementing a value equal to the minimum signed integer results in a value equal to the maximum signed integer See Also ATM_decu ATM_inci ATM_deci Atomically decrement...

Page 36: ...eturns 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 minimum unsigned integer results in a value equal to the maximum unsigned integer See Also ATM_deci ATM_incu ATM_decu Atomically decrement Uns memory a...

Page 37: ...ry location and returns its new value as follows interrupt disable ival idst 1 idst ival interrupt enable return ival ATM_inci is written in assembly language efficiently disabling interrupts on the target processor during the call Incrementing a value equal to the maximum signed integer results in a value equal to the minimum signed integer See Also ATM_deci ATM_incu ATM_inci Atomically increment...

Page 38: ...returns its new value as follows interrupt disable uval udst 1 udst uval interrupt enable return uval ATM_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 See Also ATM_decu ATM_inci ATM_incu Atomically increment Uns memory ...

Page 39: ...tomically ORs 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 ATM_ori is written in assembly language efficiently disabling interrupts on the target processor during the call See Also ATM_andi ATM_oru ATM_ori Atomically OR Int memory location an...

Page 40: ...he mask contained in usrc with a destination 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 written in assembly language efficiently disabling interrupts on the target processor during the call See Also ATM_andu ATM_ori ATM_oru Atomically OR Uns memory location and return previo...

Page 41: ...ue 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 written in assembly language efficiently disabling interrupts on the target processor during the call See Also ATM_setu ATM_cleari ATM_seti Atomically set Int memory and return previous value ...

Page 42: ...cription ATM_setu atomically sets an Uns memory location to a new value and returns its previous value as follows interrupt disable uval udst udst unew interrupt enable return uval ATM_setu is written in assembly language efficiently disabling interrupts on the target processor during the call See Also ATM_clearu ATM_seti ATM_setu Atomically set Uns memory and return previous value ...

Page 43: ...ep 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 postalignsiz...

Page 44: ...nd freed from a pool as needed at run time using the BUF_alloc and BUF_free functions The advantages of allocating memory from a buffer pool instead 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 time Allocating and freeing memory through a heap is not deterministic Callable from a...

Page 45: ...n a configuration script use the following syntax var myBuf bios BUF create myBUF The Tconf examples that follow assume the object has been created 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 s...

Page 46: ...ol length The actual length of the buffer pool in MADUs is calculated by multiplying 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 applying the alignment For example if the Buffer size is 9 and the alignment is 4 the Buffer size af...

Page 47: ...y the call to BUF_create If the buffer pool was created statically the handle can be referenced as shown in the example that follows If buffers are available in the specified buffer pool BUF_alloc returns a pointer to the buffer If no buffers are available BUF_alloc returns NULL The BUF module manages synchronization so that multiple threads can share the same buffer pool for allocation and free o...

Page 48: ...hould 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 typedef unsigned long MEM_sizep The align parameter specifies the alignment boundary for buffers in the pool Each buffer is aligned on a boundary with an address that is a multiple of this num...

Page 49: ...f 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 ...

Page 50: ...UF_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 holds a lock on the memory 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 BUF_delete cannot be called...

Page 51: ... 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 manages synchronization so that multiple threads can share the s...

Page 52: ...fe If the application 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...

Page 53: ...e 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_stat collects statistics with interrupts disabled to ensure the correctness of the statistics ...

Page 54: ...dge 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 specific functions and definitions for the TMS320C5000 family of processors See the c55 h file for a complete list...

Page 55: ...rrupts by clearing the bits specified by mask in the Interrupt Enable Register IER0 IER1 C55_disableIER0 and C55_disableIER1 return a mask of bits actually cleared This return value should be passed to C55_enableIER0 or C55_enableIER1 to re enable interrupts See C55_enableIER0 C55_enableIER1 for a description and code examples for safely protecting a critical section of code from interrupts See Al...

Page 56: ...interrupt referenced 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 See Also C55_enableInt C55_disableInt Disable an individual interrupt ...

Page 57: ...IER0 and C55_enableIER1 are usually used in tandem to protect a critical section 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...

Page 58: ...OT 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 disable only some interrupts you must 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 a...

Page 59: ...n OMAP2320 2420 level 2 interrupt vecids 32 63 For OMAP 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 interru...

Page 60: ... dynamically 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 defined using the interrupt keyword are not allowed to call any DSP BIOS functions The C55_l2AckInt function is an excep...

Page 61: ...g 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 provides the functionality of C55_disableIer0 1 for level 2 interrupts The mirmask argument is a 32 bit bitmask that defines which level 2 interrupts to disable See Al...

Page 62: ...ed by mir1mask in the Interrupt Mask Register1 MIR1 The MIR1 is a register in the Level 2 Interrupt Controller L2IC that defines which level 2 interrupts 32 63 are enabled or disabled Set bits are disabled This function provides 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 See Also C55_l2Ena...

Page 63: ...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 functionality of C55_enableIer0 1 for level 2 interrupts The mirmask argument is a 32 bit bitmask that defines which level 2 interrupts to enable Example Enables L2 interrupts 10 11 12 13 0x3c00 11110...

Page 64: ... The MIR1 is a register in the Level 2 Interrupt Controller L2IC that defines which level 2 interrupts 32 63 are enabled or disabled Cleared bits are enabled This function provides the functionality of C55_enableIer0 1 for level 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 bina...

Page 65: ...es 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 the OMAP 2320 Therefore the default priority settings give highest priority to L2 interrupt 0 and lowest to interrupt 31 63 for the OMAP 2320 The level 2 interrupt priority settin...

Page 66: ...dware 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 interrupt ID in the range of 0 31 The range is 0 95 for OMAP 2320 The range is 0 63 for OMAP 2420 See Also C55_enableIER0 C55_enableIER1 C55_plug C function to plu...

Page 67: ...ws the properties that can be configured 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 types see Section 1 4 DSP BIOS 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 o...

Page 68: ...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 multiple of the clock interrupt rate the low resolution rate if you enable the Use CLK Manager to Drive PRD in the PRD Manager...

Page 69: ...the DSP clock speed in MHz see GBL Module Properties and TDDR is the value of the timer divide down 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 PRD value Counter reset to 0 C5503 C5507 C5509 C5510 C5561 Decremented at CLKOUT TDDR 1 where CLKOUT is the DSP clock speed in ...

Page 70: ...LK_countspms function to get the number of hardware timer counter register ticks per millisecond The high resolution time is stored as a 32 bit value For platforms that use the same timer counter as the low resolution time the 32 bit high resolution 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 d...

Page 71: ...ects 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 changed automatically when you change the Timer Selection This is an informational property only Tconf Name N A Timer Selection The on device timer to use Changing this setting also automatically cha...

Page 72: ...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 low resolution timers are both enabled and disabled by the Enable CLK Manager property Tconf N...

Page 73: ... 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 register This is supported only for the 1x10 1510 1610 and 1710 and 59xx 5905 5910 and 5912 Tconf Name LOAD_TIM Type Int16 Example bios CLK LOAD_TIM 2999 PTV register S...

Page 74: ...nager 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 ...

Page 75: ...uration 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 name Tconf adds the underscore needed to call a C function from assembly internally Tconf Name fxn Type Extern Example myClk fxn prog ext...

Page 76: ...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 The equation below computes time in milliseconds since the last wrap of the high resolution timer counter timeAbs CLK_gethtime CLK_countspms See Also CLK_gethtime CLK_getprd CLK_cpuCyclesPerHtime CLK_cpuCyclesPerLtime GBL_getClkin STS...

Page 77: ... CPU cycles High resolution time is returned by CLK_gethtime For example the following code returns the number 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 See Also CLK_gethtime CLK_getprd GBL_getClkin CLK_cpuC...

Page 78: ...Low resolution time is returned by CLK_gethtime For example the following code returns the number 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 See Also CLK_getltime CLK_getprd GBL_getClkin CLK_cpuCyclesPerLtime Retu...

Page 79: ... CLK_gethtime provides a value with greater accuracy than CLK_getltime but which wraps back to 0 more frequently For example if the timer tick rate is 200 MHz then regardless of the period register value the CLK_gethtime value wraps back to 0 approximately every 86 seconds CLK_gethtime can be used in conjunction with STS_set and STS_delta to benchmark code CLK_gethtime can also be used to add a ti...

Page 80: ... can set rates from less than 1 microsecond interrupt to more than 1 second interrupt CLK_gethtime provides a value with more accuracy than CLK_getltime but which wraps back to 0 more frequently For example if the timer tick rate is 80 MHz and you use the default period register value of 40000 the CLK_gethtime value wraps back to 0 approximately every 107 seconds while the CLK_getltime value wraps...

Page 81: ...resolution 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 See Also CLK_countspms CLK_gethtime CLK_cpuCyclesPerHtime CLK_cpuCyclesPerLtime GBL_getClkin STS_delta CLK_getprd Get period reg...

Page 82: ...stop and restart the timer Use the following call sequence 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 is star...

Page 83: ...ead 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 scaling 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 and r...

Page 84: ... high resolution times On such platforms both times are affected by this API Constraints and Calling Context Call HWI_disable HWI_restore or SWI_disable SWI_enable around a block that stops configures and restarts the timer as needed to prevent re entrancy or other problems That is you must disable interrupts if an interrupt could lead to another call to CLK_start or if interrupt processing relies...

Page 85: ...ce See the section on CLK_reconfig for details Constraints and Calling Context Call HWI_disable HWI_restore or SWI_disable SWI_enable around a block that stops configures and restarts the timer as needed to prevent re entrancy or other problems That is you must disable interrupts if an interrupt could lead to another call to CLK_stop or if interrupt processing relies on having a running timer to e...

Page 86: ...h 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 a...

Page 87: ...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 f...

Page 88: ... 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 typedef struct DEV_Fxns driver func...

Page 89: ...hat can be configured 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 types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Instance Configuration Parameters DEV Manager Properties The default configuration contains managers for the following built in device drivers DGN Driver softwa...

Page 90: ...IOS Configuration Tool or in a Tconf script To create a user defined 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...

Page 91: ...ace 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 Tconf Name deviceId Type Arg Example myDev deviceId prog extern devID device params ptr If this device uses additional parameters provide the name of the parameter structure This structure should have a name with the format DXX_Params where XX is the two letter code for t...

Page 92: ...ose defined statically for the DEV Object Properties After being created the device can be used as with statically created DEV objects 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 within the application If the sp...

Page 93: ...s the name of a parameter structure that may be used to provide additional parameters This structure should have a name with the format DXX_Params 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 The devp item specifies the device global data...

Page 94: ...used if dynamic memory allocation is enabled The device function table must be consistent with the type specified in the attrs structure DSP BIOS does not check to ensure that 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 creat...

Page 95: ...cifies the device to delete This name must match a name used with DEV_createDevice Before deleting a device delete any SIO streams that use the device SIO_delete cannot be called after the device is deleted If the device type is DEV_IOMTYPE the mdUnBindDev function in the function table pointed to by the fxns parameter of the device is called as a result of calling DEV_deleteDevice This call is ma...

Page 96: ...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 ...

Page 97: ...try 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 table if successful and is set to NULL on error The DEV_Device structure is defined in dev h The substr return value contains a pointer to the characters rema...

Page 98: ...ters 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 first calls Dxx_idle to idle the device Then it calls Dxx_close Once device has been closed the underlying device is no...

Page 99: ...rameters DEV_Handle device device handle 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 operation is designated through cmd and arg which are interpreted in a driver depen...

Page 100: ...n Dxx_idle returns the device to its initial state Dxx_idle should move 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 b...

Page 101: ... supported in DSP BIOS 5 32 and will be supported in any patch releases or minor enhancements to DSP BIOS 5 32 C Interface Syntax Dxx_init Parameters Void Return Value Void Description Dxx_init is used to initialize the device driver module for a particular device This initialization often includes resetting the actual device to its initial state Dxx_init is called at system startup before the app...

Page 102: ... output mode it processes the buffer and places it in a queue to be rendered In input mode it places a buffer in a queue to be filled with data then returns Dxx_issue is used in conjunction with Dxx_reclaim to operate a stream The Dxx_issue call sends a buffer to a stream and the Dxx_reclaim retrieves a buffer from a stream Dxx_issue performs processing for output streams and provides empty frames...

Page 103: ...V_Frame objects themselves do not need to be preserved only the information they contain Dxx_issue must preserve and maintain buffers sent to the device so they can be returned in the order they were received by a call to Dxx_reclaim Constraints and Calling Context device must be bound to a device by a prior call to Dxx_open See Also Dxx_reclaim SIO_issue ...

Page 104: ...peration Description Dxx_open is called by SIO_create to open a device Dxx_open opens a device and returns an error code indicating success SYS_OK or failure The device parameter points to a DEV_Obj whose fields have been initialized by the calling function that is SIO_create These fields can be referenced by Dxx_open to initialize various device parameters Dxx_open is often used to attach a devic...

Page 105: ... cause the calling task to block If there are no frames available Dxx_ready returns FALSE This informs the calling task that a call to SIO_get SIO_put or SIO_reclaim for that device would result in blocking Dxx_ready registers the device s ready semaphore with the SIO_select semaphore sem In cases where SIO_select calls Dxx_ready for each of several devices each device registers its own ready sema...

Page 106: ...ice fromdevice queue If the device was opened in DEV_OUTPUT mode Dxx_reclaim blocks until an output frame has been emptied then place the frame on the device fromdevice queue In either mode Dxx_reclaim blocks until it has a frame to place on the device fromdevice queue or until the stream s timeout expires and it returns an error code indicating success SYS_OK or failure If device timeout is not e...

Page 107: ...cept link and misc On a device opened for DEV_INPUT Dxx_reclaim should preserve the buffer data transformed as necessary the size adjusted as appropriate by the transform and the arg field On a device opened for DEV_OUTPUT Dxx_reclaim should preserve the size and the arg field The DEV_Frame objects themselves do not need to be preserved only the information they contain Dxx_reclaim must preserve b...

Page 108: ...stem is limited only by the availability of memory Configuring a DGN Device To create a DGN device object in a configuration script use the following syntax var myDgn bios DGN create myDgn See the DGN Object Properties for the device you created Configuration Properties The following list shows the properties that can be configured in a Tconf script along with their types and default values For de...

Page 109: ... on the DGN Object Properties dialog in the DSP BIOS Configuration Tool or in a Tconf script To create a DGN device object in a script use the following syntax var myDgn bios DGN create myDgn The Tconf examples assume the myDgn object is created as shown comment Type a comment to identify this object Tconf Name comment Type String Example myDgn comment DGN device Device category The device categor...

Page 110: ...ant 1 Seed value The initial seed value used by an internal pseudo random number generator if the Device category is random Used to produce a uniformly distributed sequence of numbers ranging between Lower limit and Upper limit Tconf Name seedValue Type Int32 Example myDgn seedValue 1 Lower limit The lowest value to be generated if the Device category is random Tconf Name lowerLimit Type Numeric E...

Page 111: ...ave in sample points per second if the Device category is sine Tconf Name rate Type Int32 Example myDgn rate 256 User function If the Device category is user specifies the function to be used to compute the successive values of the data sequence in an input device or to be used to process the data stream in an output device If this function is written in C and you are using the DSP BIOS Configurat...

Page 112: ...on frame boundaries as this driver for efficiency does not maintain remainders across I O operations On opening a DGS device by name DGS uses the unmatched portion of the string to recursively open an underlying device This driver requires a transform function and a packing unpacking ratio which are used when packing unpacking buffers to from the underlying device Configuring a DGS Device To creat...

Page 113: ...d after calling the underlying device s input function in input mode Your transform function should have the following interface dstsize myTrans Arg arg Void src Void dst Int srcsize where arg is an optional argument either argument or created by the create function and src and dst specify the source and destination buffers respectively srcsize specifies the size of the source buffer and dstsize s...

Page 114: ...ocalcopy This function simply passes the data to the underlying device without packing or compressing it Data Streaming DGS devices can be opened for input or output DGS_open allocates buffers for use by the underlying device For input devices the size of these buffers is bufsize numerator denominator For output devices the size of these buffers is bufsize denominator numerator Data is transformed...

Page 115: ...cture include dgs h DGS_Params DGS_PRMS NULL optional create function NULL optional delete function u32tou8 required transform function 0 optional argument 4 numerator 1 denominator By typing _DGS_PRMS for the Parameters property of a device the values above are used as the parameters for this device See Also DTR Driver ...

Page 116: ...os HST create myHst myHst availableForDHL true Also be sure to set the mode property to output or input as needed by the DHL device For example myHst mode output Once there are HST channels available for DHL you can create a DHL device object in a configuration script using the following syntax var myDhl bios DHL create myDhl Then you can set this object s properties to select which HST channel of...

Page 117: ...stream SIO_create dhl0 SIO_INPUT 128 NULL To enable data streaming between the target and the host through streams that use DHL devices you must bind and start the underlying HST channels of the DHL devices from the Host Channels Control in Code Composer Studio just as you would with other HST objects DHL devices copy the data between the frames in the HST channel s pipe and the stream s buffers I...

Page 118: ... DHL device a SYS_EBUSY error is reported in the system LOG during startup when the BIOS_start routing calls the DHL_open function for the device DHL Driver Properties The following global property can be set for the DHL Host Link Driver on the DHL Properties dialog in the DSP BIOS Configuration Tool or in a Tconf script Object memory Enter the memory segment from which to allocate DHL objects Not...

Page 119: ...roperty in the HST Object Properties must be set to true for that HST object to be known here Tconf Name hstChannel Type Reference Example myDhl hstChannel prog get myHST Mode This informational property shows the mode input or output of the underlying HST channel This becomes the mode of the DHL device Tconf Name mode Type EnumString Options input output Example myDhl mode output ...

Page 120: ...s function table type in the configuration you can create a DIO object with the following syntax and then set properties for the object var myDio bios Dio create myDio DIO Configuration Properties The following list shows the properties that can be configured in a Tconf script along with their types and default values For details see the DIO Driver Properties and DIO Object Properties headings For...

Page 121: ...dialog in the DSP BIOS Configuration Tool or in a Tconf script Object memory Enter the memory segment from which to allocate DIO objects Tconf Name OBJMEMSEG Type Reference Example bios DIO OBJMEMSEG prog get myMEM Create All DIO Objects Statically Set this property to true if you want DIO objects to be created completely statically If this property is false the default MEM_calloc is used internal...

Page 122: ...IO with a callback function Typically the callback function is SWI_andnHook or a similar function that posts a SWI Do not set this property to true if you want to use DIO with a TSK thread Tconf Name useCallBackFxn Type Bool Example myDio useCallBackFxn false fxnsTable This informational property shows the DIO function table used as a result of the settings in the use callback version of DIO funct...

Page 123: ...e The driver also ignores any unmatched portion of the name declared in the system configuration file when opening a device Configuring a DNL Device To create a DNL device object in a configuration script use the following syntax var myDnl bios UDEV create myDnl Set DEV Object Properties for the device you created as follows init function Type 0 zero function table ptr Type _DNL_FXNS function tabl...

Page 124: ...forms Configuring a DOV Device To create a DOV device object in a configuration script use the following syntax var myDov bios UDEV create myDov Set the DEV Object Properties for the device you created as follows init function Type 0 zero function table ptr Type _DOV_FXNS function table type DEV_Fxns device id Type 0 zero device params ptr Type 0 zero or the length of the overlap as described afte...

Page 125: ... and enter 16 as the Device ID property leave the Device Control String blank In addition to the configuration properties you need to specify the value that DOV uses for the first overlap as in the example include dov h static DOV_Config DOV_CONFIG Char 0 DOV_Config DOV DOV_CONFIG If floating point 0 0 is required the initial value should be set to Char 0 0 Data Streaming DOV devices can only be o...

Page 126: ..._create add SIO objects with Tconf Enter the string that identifies the terminating device preceded by forward slash in the SIO object s Device Control Strings for example codec port Then select the stacking device overlap overlapio from the Device property See Also DTR Driver DGS Driver ...

Page 127: ...writer task It is possible to delete one end of a pipe with SIO_delete and recreate that end with SIO_create without deleting the other end Configuring a DPI Device To add a DPI device right click on the DPI Pipe Driver folder and select Insert DPI From the Object menu choose Rename and type a new name for the DPI device Configuration Properties The following list shows the properties that can be ...

Page 128: ...nctions do not block SIO_select can be called simultaneously by both the input and the output sides DPI and the SIO_ISSUERECLAIM Streaming Model In the SIO_ISSUERECLAIM streaming model an application reclaims buffers from a stream in the same order as they were previously issued To preserve this mechanism of exchanging buffers with the stream the default implementation of the DPI driver for ISSUER...

Page 129: ...pipe0 there would be no source change at all If the streams were created statically with Tconf instead you would need to change the Device property for the stream in the configuration template save and rebuild your application for the new configuration No source change would be necessary Constraints Only one reader and one writer can open the same pipe DPI Driver Properties There are no global pro...

Page 130: ...s property is set to false when you use SIO_create the name of the SIO object must exactly match the name of the DPI object As a result only one open stream can use the DPI object For example if the DPI object is named pipe an attempt to use SIO_create to create pipe0 fails Tconf Name allowVirtual Type Bool Example myDpi allowVirtual false ...

Page 131: ...reate myDst Set the DEV Object Properties for the device you created as follows init function Type 0 zero function table ptr Type _DST_FXNS function table type DEV_Fxns device id Type 0 zero or the number of small buffers corresponding to a large buffer as described after this list device params ptr Type 0 zero If you enter 0 for the Device ID you need to specify the number of small buffers corres...

Page 132: ...d a device called split and enter 4 as its Device ID you need to open the stream with stream SIO_create split codec SIO_INPUT 1024 NULL This causes SIO to open a stack of two devices split designates the device called split which you have configured to read four buffers from the codec device and copy the data into a larger buffer for your application As in the previous example codec specifies the ...

Page 133: ... buffer Configuring a DTR Device To create a DTR device object in a configuration script use the following syntax var myDtr bios UDEV create myDtr Set the DEV Object Properties for the device you created as follows init function Type 0 zero function table ptr Type _DTR_FXNS function table type DEV_Fxns device id Type 0 zero _DTR_multiply or _DTR_multiplyInt16 If you type 0 you need to supply a use...

Page 134: ...rs property of a DTR device the values above are used as the parameters for this device You can also use the default values that the driver assigns to these parameters by entering _DTR_PARAMS for this property The default values are DTR_Params DTR_PARAMS 1 scale value Arg NULL user arg Fxn NULL user fxn scale value is a floating point quantity multiplied with each data point in the input or output...

Page 135: ...g device and then transforms this data in place If the transformer is used as a data sink it outputs a given buffer to the underlying device after transforming this data in place The DTR driver places no inherent restrictions on the size or memory segment of the data buffers used when streaming to or from a transformer device such restrictions if any would be imposed by the underlying streaming de...

Page 136: ...ult values For details see the GBL Module Properties heading For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Description This module does not manage any individual objects but rather allows you to control global or system wide settings used by other modules C55x Name Type Default Enum Options BOARDNAME String c55xx PROCID Int16 0 CLKI...

Page 137: ... obtained at run time using the GBL_getClkin API This property is used on the C5503 to compute the USB PLL settings The default value is 20000 KHz Tconf Name CLKIN Type Uint32 Example bios GBL CLKIN 20000 DSP Speed In MHz CLKOUT This number times 1000000 is the number of instructions the processor can execute in 1 second You should set this property to match the actual rate This property does not ...

Page 138: ... addressing always uses the full 24 bit range Both the large and huge models support the same addressing range The difference is that the huge model allows buffers to cross 64K page boundaries For the large model size_t is 16 bits 64K For the huge model size_t is 23 bits which requires 32 bits of storage since the minimum storage unit is 16 bits Tconf Name MEMORYMODEL Type EnumString Options LARGE...

Page 139: ... the DSP BIOS library The non instrumented versions are somewhat smaller but do not provide support for LOG STS and TRC instrumentation The libraries are located in BIOS_INSTALL_DIR packages ti bios lib By default the instrumented version of the library for your platform is used Tconf Name INSTRUMENTED Type Bool Example bios GBL INSTRUMENTED true Enable All TRC Trace Event Classes Set this propert...

Page 140: ... clkin CLKIN frequency Reentrant yes Description Returns the configured value of the board input clock CLKIN frequency in KHz For example on the C5509 CLKIN is used to compute the settings of the USB PLL See Also CLK_countspms CLK_getprd GBL_getClkin Get configured value of board input clock in KHz ...

Page 141: ...trant yes Description Returns the current frequency of the DSP CPU in an integer number of KHz This is the frequency set by GBL_setFrequency which must also be an integer The default value is the value of the CLKOUT property which is configured as one of the GBL Module Properties See Also GBL_getClkin GBL_setFrequency GBL_getFrequency Get current frequency of the CPU in KHz ...

Page 142: ... The procId is also defined in the MSGQ_TransportObj array that is part of the MSGQ_Config structure The same processor ID should be defined for this processor in both locations During the User Init Function the application may modify the statically configured processor ID by calling GBL_setProcId In this case the User Init Function may need to call GBL_getProcId first to get the statically config...

Page 143: ...ws GBL_getVersion returns 0x5001 The last item uses two digits in the returned hex number DSP BIOS_Kernel 5 0 1 05 30 2004 cuda l06 GBL_getVersion Get DSP BIOS version information Bits Compatibility with Older DSP BIOS Versions 12 15 first hex digit Not compatible Changes to application C assembly or configuration Tconf code may be required For example moving from 0x5100 to 0x6100 may require code...

Page 144: ...to DSP BIOS you should follow the sequence shown in the CLK_reconfig topic to reconfigure the timer The frequency must be an integer number of KHz If you enable the PWRM module do not call GBL_setFrequency When you use frequency scaling the PWRM module internally calls this API to update the value known to DSP BIOS Constraints and Calling Context If you change the frequency known to DSP BIOS you s...

Page 145: ...ly be called at the beginning of DSP BIOS initialization The application may determine the true processor ID for the device during the User Init Function and call GBL_setProcId with the correct processor ID This is useful in applications that run a single binary image on multiple DSP processors How the application determines the correct processor ID is application or board specific For example you...

Page 146: ... Constants Types and Structures Modes for GIO_create define IOM_INPUT 0x0001 define IOM_OUTPUT 0x0002 define IOM_INOUT IOM_INPUT IOM_OUTPUT IOM Status and Error Codes define IOM_COMPLETED SYS_OK I O successful define IOM_PENDING 1 I O queued and pending define IOM_FLUSHED 2 I O request flushed define IOM_ABORTED 3 I O aborted define IOM_EBADIO 1 generic failure define IOM_ETIMEOUT 2 timeout occurr...

Page 147: ...ets number of asynch I O packets Uns timeout for blocking SYS_FOREVER GIO_Attrs Struct passed to GIO_submit for synchronous use typedef struct GIO_AppCallback GIO_TappCallback fxn Ptr arg GIO_AppCallback typedef struct GIO_Obj IOM_Fxns fxns ptr to function table Uns mode create mode Uns timeout timeout for blocking IOM_Packet syncPacket for synchronous use QUE_Obj freeList frames for asynch I O Pt...

Page 148: ... Configuration Parameters Description The GIO module provides a standard interface to mini drivers for devices such as UARTs codecs and video capture display devices The creation of such mini drivers is not covered in this manual it is described in DSP BIOS Device Driver Developer s Guide SPRU616 The GIO module is independent of the actual mini driver being used It allows the application to use a ...

Page 149: ... Enable General Input Output Manager Set this property to true to enable use of the GIO module If your application does not use GIO you should leave it disabled to prevent additional modules such as SEM from being linked into your application Tconf Name ENABLEGIO Type Bool Example bios GIO ENABLEGIO false Create Function The function the GIO module should use to create a synchronization object Thi...

Page 150: ...d If you use another function that function should have a prototype that matches that of SEM_pend Bool PENDFXN Ptr semHandle Uns timeout Tconf Name PENDFXN Type Extern Example bios GIO PENDFXN prog extern SEM_pend Post Function The function the GIO module should use to post a synchronization object This function is typically SEM_post If you use another function that function should have a prototyp...

Page 151: ...urns a negative value For a list of error values see Constants Types and Structures on page 2 118 A call to GIO_abort results in a call to the mdSubmit function of the associated mini driver The IOM_ABORT command is passed to the mdSubmit function The mdSubmit call is typically a blocking call so calling GIO_abort can result in the thread blocking Constraints and Calling Context This function can ...

Page 152: ...el of indirection if the mini driver expects a data structure to package many components of data required for the control operation In the simple case where no data is required this parameter may just be a predefined command value GIO_control returns IOM_COMPLETED upon success If an error occurs the device returns a negative value For a list of error values see Constants Types and Structures on pa...

Page 153: ...ion or at runtime The mode argument specifies the mode in which the device is to be opened This may be IOM_INPUT IOM_OUTPUT or IOM_INOUT If the status returned by the device is non NULL a status value is placed at the address specified by the status parameter The chanParams parameter is a pointer that may be used to pass device or domain specific arguments to the mini driver The contents at the sp...

Page 154: ...eate results in a call to the mdCreateChan function of the associated mini driver Constraints and Calling Context A GIO stream can only be used by one task simultaneously Catastrophic failure can result if more than one task calls GIO_read on the same input stream or more than one task calls GIO_write on the same output stream GIO_create cannot be called from the context of a SWI or HWI thread Thi...

Page 155: ...e disabled The gioChan parameter is the handle returned by GIO_create or GIO_new This function returns IOM_COMPLETED if the channel is successfully closed If an error occurs the device returns a negative value For a list of error values see Constants Types and Structures on page 2 118 A call to GIO_delete results in a call to the mdDelete function of the associated mini driver Constraints and Call...

Page 156: ...lue For a list of error values see Constants Types and Structures on page 2 118 A call to GIO_flush results in a call to the mdSubmit function of the associated mini driver The IOM_FLUSH command is passed to the mdSubmit function The mdSubmit call is typically a blocking call so calling GIO_flush can result in the thread blocking while waiting for output calls to be completed Constraints and Calli...

Page 157: ...el device driver channel The GIO_new call does not allocate any memory It requires pre allocated memory The gioChan parameter is a handle to a structure of type GIO_Obj that your program has declared GIO_new initializes this structure typedef struct GIO_Obj IOM_Fxns fxns ptr to function table Uns mode create mode Uns timeout timeout for blocking IOM_Packet syncPacket for synchronous use QUE_Obj fr...

Page 158: ...set of attributes is used The default for nPackets is 2 The default for timeout is SYS_FOREVER GIO_new initializes the packets but does not allocate them GIO_new returns the non NULL handle to the GIO_Obj when initialization is successful The handle returned by this call should be used by the application in subsequent calls to GIO functions Usually this is the same handle passed to GIO_new However...

Page 159: ...evices this structure may contain pointers to RGB buffers their sizes video format and a host of data required for reading a frame from a video capture device Upon a successful read this argument points to the returned data The pSize parameter points to the size of the buffer or data structure pointed to by the bufp parameter When the function returns this parameter points to the number of MADUs r...

Page 160: ...should have been obtained with a prior call to GIO_create or GIO_new GIO_read cannot be called from a SWI HWI or main unless the underlying mini driver is a non blocking driver and the GIO Manager properties are set to use non blocking synchronization methods Example Read from the device size sizeof readStruct status GIO_read gioChan readStruct size ...

Page 161: ...parameter is the handle returned by GIO_create or GIO_new The cmd parameter is one of the command code constants listed in Constants Types and Structures on page 2 118 A mini driver may add command codes for additional functionality The bufp parameter points to a device defined data structure for passing buffer data between the device and the application This structure may be generic across a doma...

Page 162: ...nstants Types and Structures on page 2 118 A call to GIO_submit results in a call to the mdSubmit function of the associated mini driver The specified command is passed to the mdSubmit function Constraints and Calling Context This function can be called only after the device has been loaded and initialized The handle supplied should have been obtained with a prior call to GIO_create or GIO_new Thi...

Page 163: ...is structure may contain pointers to RGB buffers their sizes video format and a host of data required for reading a frame from a video capture device Upon a successful read this argument points to the returned data The pSize parameter points to the size of the buffer or data structure pointed to by the bufp parameter When the function returns this parameter points to the number of MADUs written to...

Page 164: ...O_new This function can be called within the program s main function only if the GIO channel is asynchronous non blocking GIO_write cannot be called from a SWI or HWI unless the underlying mini driver is a non blocking driver and the GIO Manager properties are set to use non blocking synchronization methods Example write synchronously to the device size sizeof writeStruct status GIO_write gioChan ...

Page 165: ...with their types and default values For details see the HOOK Object Properties heading For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Instance Configuration Parameters Description The HOOK module is an extension to the TSK function hooks defined in the TSK Manager Properties It allows multiple sets of hook functions to be performed at key execution points For examp...

Page 166: ...any data structure with a particular HOOK object and TSK object combination There is no limit to the number of HOOK objects that can be created However each object requires a small amount of memory in the bss section to contain the object A HOOK object initially has all of its functions set to FXN_F_nop You can set some hook functions and use this no op function for the remaining events Since the ...

Page 167: ...tialized after initialization functions run In addition to code specific to the module hook this function should be used to record the object s ID if it is needed in a subsequent hook function This initialization function is intended for use in setting up data structures used by other functions of the same HOOK object In contrast the User Init Function property of the GBL Module Properties runs ea...

Page 168: ...call when any task switch occurs This function can give the application access to both the current and next task handles The TSK Module topic describes the Switch function Tconf Name switchFxn Type Extern Example myHook switchFxn prog extern mySwitch Call ready function Set this property to true if you want a function to be called when any task becomes ready to run Tconf Name callReadyFxn Type Boo...

Page 169: ...urn Value Ptr environ environment pointer Reentrant yes Description HOOK_getenv returns the environment pointer associated with the specified HOOK and TSK objects The environment pointer environ references the data structure specified in a previous call to HOOK_setenv See Also HOOK_setenv TSK_getenv HOOK_getenv Get environment pointer for a given HOOK and TSK combination ...

Page 170: ...on The environment pointer environ should reference an data structure to be used by the hook functions for a task or tasks Each HOOK object may have a separate environment pointer for each task A HOOK object may also point to the same data structure for all tasks depending on its data sharing needs The HOOK_getenv function can be used to get the environ pointer for a particular HOOK and TSK object...

Page 171: ...ager Properties and HST Object Properties headings For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Description The HST module manages host channel objects which allow an application to stream data between the target and the host Host channels are statically configured for input or output Input channel...

Page 172: ...these pipes you can selectively capture the I O channels in real time for off line and field testing analysis The notify function is called in the context of the code that calls PIP_free or PIP_put This function can be written in C or assembly The code that calls PIP_free or PIP_put should preserve any necessary registers The other end of the host channel is managed by the LNK_dataPump IDL object ...

Page 173: ...HST object in a configuration script use the following syntax var myHst bios HST create myHst The Tconf examples that follow assume the object has been created as shown comment A comment to identify this HST object Tconf Name comment Type String Example myHst comment my HST mode The type of channel input or output Input channels are used by the target to read data from the host output channels are...

Page 174: ... property to true if you want to use this HST object with a DHL device DHL devices allow you to manage data I O between the host and target using the SIO module rather than the PIP module See the DHL Driver topic for more details Tconf Name availableForDHL Type Bool Example myHst availableForDHL false notify The function to execute when a frame of data for an input channel or free space for an out...

Page 175: ...trant yes Description HST_getpipe gets the address of the pipe object for the specified host channel object Example Void copy HST_Obj input HST_Obj output PIP_Obj in out Uns src dst Uns size in HST_getpipe input out HST_getpipe output if PIP_getReaderNumFrames 0 PIP_getWriterNumFrames 0 error get input data and allocate output frame PIP_get in PIP_alloc out copy input data to output frame src PIP_...

Page 176: ...ult 0 LgUns mirmask OMAP 2320 2420 only LgUns mir1mask OMAP 2320 only HWI_Attrs HWI_Attrs HWI_ATTRS 1 IER0 mask 1 self 1 IER1 mask 1 self 0 argument to ISR If ier0mask and ier1mask are both 1 mask to disable self is created Configuration Properties The following list shows the properties that can be configured in a Tconf script along with their types and default values For details see the HWI Mana...

Page 177: ...ng the HWI_dispatchPlug function or the C55_plug function C55x Name Type Default Enum Options comment String add comments here fxn Extern prog extern HWI_unused asm monitor EnumString Nothing Data Value xsp ac0g ac0h ac0l ac1g ac1h ac1l ac2g ac2h ac2l ac3g ac3h ac3l xar0 xar1 xar2 xar3 xar4 xar5 xar6 xar7 t0 t1 t2 t3 xssp tim st0_55 st1_55 st2_55 st3_55 trn0 bk03 brc0 xdp xcdp dph mdp05 mdp67 pdp ...

Page 178: ...f a SWI or HWI thread HWI Dispatcher vs HWI_enter exit The HWI dispatcher is the preferred method for handling an interrupt When an HWI object does not use the dispatcher the HWI_enter assembly macro must be called prior to any DSP BIOS API calls that affect other DSP BIOS objects such as posting a SWI or a semaphore and the HWI_exit assembly macro must be called at the very end of the function s ...

Page 179: ...her The DSP BIOS API calls that require an HWI function to use HWI_enter and HWI_exit are SWI_andn SWI_andnHook SWI_dec SWI_inc SWI_or SWI_orHook SWI_post PIP_alloc PIP_free PIP_get PIP_put PRD_tick SEM_post MBX_post TSK_yield TSK_tick Any PIP API call can cause the pipe s notifyReader or notifyWriter function to run If an HWI function calls a PIP function the notification functions run as part of...

Page 180: ...stack is also used by all SWI routines The register mask argument to HWI_enter and HWI_exit allows you to save and restore registers used within the function Other arguments for example allow the HWI to control the settings of the IMR or in the case of the C55x device the IER0 IER1 Note By using HWI_enter and HWI_exit as an HWI function s prolog and epilog an HWI function can be interrupted that i...

Page 181: ...ta memory address 0x7e4800 This coincides with the reset IOMA value of 0x3f For OMAP 2320 the default base address is 0x7c4800 which coincides with the reset IOMA value of 0x3e The IO MAP IOMA base address is the page index used to access DSP I O space addresses from DSP memory space If you modify IOMA for any reason you need to use this property to tell DSP BIOS the new base address for the L2IC ...

Page 182: ...he overhead for monitoring is 20 to 30 instructions per interrupt per HWI object monitored Leaving this instrumentation turned on after debugging is not recommended since HWI processing is the most time critical part of the system Options Nothing Data Value xsp ac0g ac0h ac0l ac1g ac1h ac1l ac2g ac2h ac2l ac3g ac3h ac3l xar0 xar1 xar2 xar3 xar4 xar5 xar6 xar7 t0 t1 t2 t3 xssp tim st0_55 st1_55 st2...

Page 183: ...nterrupt Mask Specifies which interrupts the dispatcher should disable before calling the function This property is available only when using the HWI dispatcher The self option causes the dispatcher to disable only the current interrupt and causes the appropriate interruptBitMask0 interruptBitMask1 and mirmask mir1mask values to be generated for the interrupt being configured When using self set b...

Page 184: ...sk values to be generated for the interrupt being configured When using self set all of interruptMask0 interruptMask1 and iMirMask to self The all option disables all level 2 interrupts The none option disables no level 2 interrupts The bitmask option causes the mirmask and mir1mask for OMAP 2320 property to be used to specify which level 2 interrupts to disable This property is similar to interru...

Page 185: ...igured for level 1 interrupts You can change the priority at run time using the C55_l2SetIntPriority API OMAP 2320 2420 only Tconf Name priority Type Numeric Example bios HWI_INT2 priority 0 Although it is not possible to create new HWI objects most interrupts supported by the device architecture have a precreated HWI object Your application can require that you select interrupt sources other than...

Page 186: ...t5 hardware interrupt through Maskable IER0 bit15 hardware interrupt HWI_INT16 through HWI_INT23 Maskable IER1 bit0 hardware interrupt though Maskable IER1 bit7 hardware interrupt HWI_BERR Maskable IER1 bit8 bus error interrupt HWI_DLOG Maskable IER1 bit9 data log interrupt HWI_RTOS Maskable IER1 bit10 RTOS interrupt HWI_SINT27 through HWI_SINT31 Non maskable software interrupt HWI_L2_INT0 through...

Page 187: ...while interrupts are disabled are postponed until interrupts are reenabled However if the same type of interrupt occurs several times while interrupts are disabled the interrupt s function is executed only once when interrupts are reenabled A context switch can occur when calling HWI_enable or HWI_restore if an enabled interrupt occurred while interrupts are disabled HWI_disable may be called from...

Page 188: ...leIMR or C55_enableIER0 C55_enableIER1 to enable specific interrupts If attrs is NULL the HWI s dispatcher properties are assigned a default set of attributes Otherwise the HWI s dispatcher properties are specified by a structure of type HWI_Attrs defined as follows typedef struct HWI_Attrs Uns ier0mask IER0 bitmask Uns ier1mask IER1 bitmask Arg arg fxn arg default 0 LgUns mirmask OMAP 2320 2420 o...

Page 189: ...xecuting the HWI This field contains a 32 bit mask in which each bit corresponds to level 2 interrupts 32 63 The default value for each interrupt is to mask only the current level 2 interrupt OMAP 2320 only The default values are defined as follows HWI_Attrs HWI_ATTRS 1 IER0 mask 1 self 1 IER1 mask 1 self 0 argument to ISR The arg element is a generic argument that is passed to the plugged functio...

Page 190: ...ts are disabled are postponed until interrupts are reenabled However if the same type of interrupt occurs several times while interrupts are disabled the interrupt s function is executed only once when interrupts are reenabled A context switch can occur when calling HWI_enable HWI_restore if an enabled interrupt occurs while interrupts are disabled Any call to HWI_enable enables interrupts even if...

Page 191: ...ER0DISABLEMASK IER1DISABLEMASK MIRDISABLEMASK Preconditions intm 1 Postconditions intm 0 braf 0 cpl 1 m40 0 satd 0 sxmd 0 c16 0 frct 0 c54cm 0 arms 1 rdm 0 cdplc 0 ar 0 7 lc 0 sata 0 smul 0 sst 0 Both the user stack pointer XSP and the system stack pointer XSSP are left aligned to even address boundaries in compliance with standard C conventions Modifies xar0 xar1 ac0g ac0h ier0 ier1 ac1 ac2 Reent...

Page 192: ... c55 h55 file for a complete list of masks and the example later in this section for a clearer understanding Typically SAVE_BY_CALLER is used for ISRs written in C C55_AR_DR_X_MASK Mask of registers belonging to ar0 7 t0 3 sp ssp C55_ACC_X_MASK Mask of registers belonging to ac0 3 C55_MISC1_X_MASK Mask of registers ier0 ifr0 dbier0 ier1 ifr dbier1 st0 st1 st2 st3 trn0 bk03 brc0 C55_MISC2_X_MASK Ma...

Page 193: ...function except NMI s HWI function before the first operation in an HWI that uses any DSP BIOS API calls that might post or affect a SWI or semaphore Such functions must be written in assembly language Alternatively the HWI dispatcher can be used instead of this API allowing the function to be written completely in C and allowing you to reduce code size If an interrupt function calls HWI_enter it ...

Page 194: ...s enables interrupts The user s C function must have a leading underscore as in this example call _myCfunction When exiting the hardware interrupt you need to call HWI_exit with the following macro HWI_exit C55_AR_DR_SAVE_BY_CALLER_MASK C55_ACC_SAVE_BY_CALLER_MASK C55_MISC1_SAVE_BY_CALLER_MASK C55_MISC2_SAVE_BY_CALLER_MASK C55_MISC3_SAVE_BY_CALLER_MASK user_ier0_mask user_ier1_mask The HWI_exit ma...

Page 195: ...SK IER0RESTOREMASK IER1RESTOREMASK MIRRESTOREMASK Preconditions none Postconditions intm 0 Modifies Restores all registers saved with the HWI_enter mask Reentrant yes Description HWI_exit is an API assembly macro which is used to restore the context that existed before a DSP BIOS hardware interrupt HWI was invoked HWI_exit is used by HWIs that are user dispatched as opposed to HWIs that are handle...

Page 196: ...I_exit If upon exiting an HWI you do want to enable an interrupt that was disabled upon entering the HWI set the corresponding bit in IER0 IER1 RESTOREMASK before calling HWI_exit Setting bits in IER0 IER1 RESTOREMASK passed to HWI_exit does not enable the corresponding interrupts if they were not originally disabled by the HWI_enter macro This same logic applies to the OMAP 2320 2420 MIRRESTOREMA...

Page 197: ...t of registers that are being declared as trashable by the called function places the processor status register bit settings as required by C compiler conventions aligns stack pointers to even address boundaries as well as remembering any such adjustments made to SP and SSP registers The user s C function must have a leading underscore as in this example call _myCfunction When exiting the hardware...

Page 198: ...hen it is called within the context of an HWI or CLK function It also returns TRUE when called from main This macro returns FALSE in all other contexts In previous versions of DSP BIOS calling HWI_isHWI from main resulted in TRUE This is no longer the case main is identified as part of the TSK context See Also SWI_isSWI TSK_isTSK HWI_isHWI Check to see if called in the context of an HWI ...

Page 199: ...calling HWI_restore if HWI_restore reenables interrupts and if a higher priority HWI occurred while interrupts were disabled HWI_restore may be called from main However since HWI_enable cannot be called from main interrupts are always disabled in main and a call to HWI_restore has no effect Constraints and Calling Context HWI_restore must be called with interrupts disabled The parameter passed to ...

Page 200: ...ads that can be executed by DSP BIOS programs hardware interrupts HWI Module software interrupts SWI Module tasks TSK Module and background threads IDL module Background threads have the lowest priority and execute only if no hardware interrupts software interrupts or tasks need to run An application s main function must return before any DSP BIOS threads can run After the return DSP BIOS runs the...

Page 201: ...mple bios IDL OBJMEMSEG prog get myMEM Auto calculate idle loop instruction count When this property is set to true the program runs the IDL functions one or more times at system startup to get an approximate value for the idle loop instruction count This value saved in the global variable CLK_D_idletime is read by the host and used in the CPU load calculation By default the instruction count incl...

Page 202: ...IDL function function The function to execute If this function is written in C and you use 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 use Tconf do not add an underscore before the function name Tconf adds the underscore to...

Page 203: ...s features of DSP BIOS for example LOG and STS into existing applications IDL_run must be called to transfer the real time analysis data to and from the host computer Though not required this is usually done during idle time when no HWI or SWI threads are running Note BIOS_init and BIOS_start must be called before IDL_run to ensure that DSP BIOS has been initialized For example the DSP BIOS boot f...

Page 204: ... 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameter Description The lock module makes available a set of functions that manipulate lock objects accessed through handles of type LCK_Handle Each lock implicitly corresponds to a shared global resource and is used to arbitrate access to this resource among several competing tasks The LCK module contains a pair of functions for acquiring...

Page 205: ...object in a configuration script use the following syntax The Tconf examples that follow assume the object has been created as shown here var myLck bios LCK create myLck The following property can be set for a LCK object in the LCK Object Properties dialog of the DSP BIOS Configuration Tool or in a Tconf script comment Type a comment to identify this LCK object Tconf Name comment Type String Examp...

Page 206: ...default attribute values are contained in the constant LCK_ATTRS which can be assigned to a variable of type LCK_Attrs prior to calling LCK_create LCK_create calls MEM_alloc to dynamically create the object s data structure MEM_alloc must acquire a lock to the memory before proceeding If another thread already holds a lock to the memory then there is a context switch The segment from which the obj...

Page 207: ... the memory before proceeding If another task already holds a lock to the memory then there is a context switch Constraints and Calling Context LCK_delete cannot be called from a SWI or HWI No task should be awaiting ownership of the lock No check is performed to prevent LCK_delete from being used on a statically created object If a program attempts to delete a lock object that was created using T...

Page 208: ...returns TRUE if it successfully acquires ownership of lock returns FALSE if a timeout occurs before it can acquire ownership LCK_pend returns FALSE if it is called from the context of a SWI or HWI even if the timeout is zero Note RTS Functions Callable from TSK Threads Only Many run time support RTS functions use lock and unlock functions to prevent reentrancy However DSP BIOS SWI and HWI threads ...

Page 209: ...w operator cannot be used in the context of a SWI or HWI thread Constraints and Calling Context The lock must be a handle for a resource lock object created through a prior call to LCK_create LCK_pend should not be called from a SWI or HWI thread LCK_pend should not be called from main See Also LCK_create LCK_delete LCK_post ...

Page 210: ...e with lock ownership remains with the current task until LCK_post is called an equal number of times LCK_post results in a context switch if a higher priority thread is currently pending on the lock Constraints and Calling Context lock must be a handle for a resource lock object created through a prior call to LCK_create LCK_post should not be called from a SWI or HWI thread LCK_post should not b...

Page 211: ...ion 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Description The Event Log is used to capture events in real time while the target program executes You can use the system log or create user defined logs If the logtype is circular the log buffer of size buflen contains the last buflen elements If the logtype is fixed the log buffer contains ...

Page 212: ...s two words per element in the log s buffer The first element holds a sequence number that allows the Event Log to display logs in the correct order The remaining three elements contain data specified by the call that wrote the message to the log See the Code Composer Studio online tutorialfor examples of how to use the LOG Manager LOG Manager Properties The following global property can be set fo...

Page 213: ...ogType Type EnumString Options circular fixed Example myLog logType circular datatype Choose printf if you use LOG_printf to write to this log and provide a format string Choose raw data if you want to use LOG_event to write to this log and have the Event Log apply a printf style format string to all records in the log Tconf Name dataType Type EnumString Options printf raw data Example myLog dataT...

Page 214: ...ters LOG_Handle log log object handle Return Value Void Reentrant no Description LOG_disable disables the logging mechanism and prevents the log buffer from being modified Example LOG_disable trace See Also LOG_enable LOG_reset LOG_disable Disable a message log ...

Page 215: ...G_enable log Parameters LOG_Handle log log object handle Return Value Void Reentrant no Description LOG_enable enables the logging mechanism and allows the log buffer to be modified Example LOG_enable trace See Also LOG_disable LOG_reset LOG_enable Enable a message log ...

Page 216: ...lt configuration by the LOG_system object LOG_error is not affected by any TRC bits an error event is always written to the system log The format argument can contain any of the conversion characters supported for LOG_printf See LOG_printf for details Example Void UTL_doError String s Int errno LOG_error SYS_error called error id 0x x errno LOG_error SYS_error called string s s See Also LOG_event ...

Page 217: ...nt If you want the Event Log to apply the same printf style format string to all records in the log use Tconf to choose raw data for the datatype property and type a format string for the format property see LOG Object Properties on page 2 184 If the logtype is circular the log buffer of size buflen contains the last buflen elements If the logtype is fixed the log buffer contains the first buflen ...

Page 218: ...ovided that both the host and target trace bits are enabled The format argument passed to LOG_message can contain any of the conversion characters supported for LOG_printf See LOG_printf page 2 191 for details Example Void UTL_doMessage String s Int errno LOG_message SYS_error called error id 0x x errno LOG_message SYS_error called string s s See Also LOG_error LOG_event LOG_printf TRC_disable TRC...

Page 219: ...fer To reduce execution time log data is always formatted on the host The format string is stored on the host and accessed by the Event Log The arguments passed to LOG_printf must be integers strings or a pointer if the special r or p conversion character is used Casting arg0 and arg1 using the Arg type causes an erroneous value to be printed To print the value correctly do not cast these paramete...

Page 220: ...orld LOG_printf trace s msg However the following example is not supported char msg 100 strcpy msg Hello world LOG_printf trace s msg If the string appears in the COFF file and a pointer to the string is passed to LOG_printf then the string in the COFF file is used by the Event Log to generate the output If the string can not be found in the COFF file the format string is replaced with ERROR 0x x ...

Page 221: ...G_printf are shown here You configure the characteristics of a log in Tconf If the logtype is circular the log buffer of size buflen contains the last buflen elements If the logtype is fixed the log buffer contains the first buflen elements Any combination of threads can write to the same log Internally hardware interrupts are temporarily disabled during a call to LOG_printf Log messages are never...

Page 222: ...starting from the beginning of the buffer with sequence number starting from 0 LOG_reset does not disable interrupts or otherwise protect the log from being modified by an HWI or other thread It is therefore possible for the log to contain inconsistent data if LOG_reset is preempted by an HWI or other thread that uses the same log Example LOG_reset trace See Also LOG_disable LOG_enable LOG_reset R...

Page 223: ...configured in a Tconf script along with their types and default values For details see the MBX Manager Properties and MBX Object Properties headings For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Description The MBX module makes available a set of functions that manipulate mailbox objects accessed th...

Page 224: ...guration Tool or in a Tconf script Object Memory The memory segment that contains the MBX objects created with Tconf Tconf Name OBJMEMSEG Type Reference Example bios MBX OBJMEMSEG prog get myMEM MBX Object Properties To create an MBX object in a configuration script use the following syntax The Tconf examples that follow assume the object has been created as shown here var myMbx bios MBX create my...

Page 225: ...ault set of attributes Otherwise the mailbox s attributes are specified through a structure of type MBX_Attrs All default attribute values are contained in the constant MBX_ATTRS which can be assigned to a variable of type MBX_Attrs prior to calling MBX_create MBX_create calls MEM_alloc to dynamically create the object s data structure MEM_alloc must acquire a lock to the memory before proceeding ...

Page 226: ...y before proceeding If another task already holds a lock to the memory then there is a context switch Constraints and Calling Context No tasks should be pending on mbx when MBX_delete is called MBX_delete cannot be called from a SWI or HWI No check is performed to prevent MBX_delete from being used on a statically created object If a program attempts to delete a mailbox object that was created usi...

Page 227: ...anularity in system timekeeping If timeout is SYS_FOREVER the task remains suspended until MBX_post is called on this mailbox If timeout is 0 MBX_pend returns immediately If timeout expires or timeout is 0 before the mailbox is available MBX_pend returns FALSE Otherwise MBX_pend returns TRUE A task switch occurs when calling MBX_pend if the mailbox is empty and timeout is not 0 or if a higher prio...

Page 228: ...f task suspension can be up to 1 system clock tick less than timeout due to granularity in system timekeeping If timeout expires or timeout is 0 before the mailbox is available MBX_post returns FALSE Otherwise MBX_post returns TRUE A task switch occurs when calling MBX_post if a higher priority task is made ready to run or if there are no free message slots and timeout is not 0 Constraints and Cal...

Page 229: ...gid for malloc free define MEM_HEADERSIZE free block header size define MEM_HEADERMASK mask to align on MEM_HEADERSIZE define MEM_ILLEGAL illegal memory address MEM_Attrs MEM_ATTRS default attribute values 0 typedef struct MEM_Segment Ptr base base of the segment MEM_sizep length size of the segment Uns space memory space MEM_Segment typedef struct MEM_Stat MEM_sizep size original size of segment ...

Page 230: ...t SARAM HWISEG Reference prog get SARAM HWIVECSEG Reference prog get VECT RTDXTEXTSEG Reference prog get SARAM USERCOMMANDFILE Bool false TEXTSEG Reference prog get SARAM SWITCHSEG Reference prog get SARAM BSSSEG Reference prog get DARAM CINITSEG Reference prog get SARAM PINITSEG Reference prog get SARAM CONSTSEG Reference prog get DARAM DATASEG Reference prog get DARAM CIOSEG Reference prog get D...

Page 231: ...e No Dynamic Memory Heaps property for the MEM manager to true If you remove this capability your program cannot call any of the MEM functions or any object creation functions such as TSK_create You need to create all objects to be used by your program statically with Tconf You can also create or remove the dynamic memory heap from an individual memory segment in the configuration Software modules...

Page 232: ...perties The DSP BIOS Memory Section Manager allows you to specify the memory segments required to locate the various code and data sections of a DSP BIOS application Note that settings you specify in the Visual Linker normally override settings you specify in the configuration See the Visual Linker help for details on using the Visual Linker with DSP BIOS The following global properties can be set...

Page 233: ... and delete objects If this property is set to true the program may not call the MEM_alloc MEM_valloc MEM_calloc and malloc or the XXX_create function for any DSP BIOS module If this property is set to true the Segment For DSP BIOS Objects Segment for malloc free and Stack segment for dynamic tasks properties are set to MEM_NULL When you set this property to true heaps already specified in MEM seg...

Page 234: ...e in the same 64K page of memory that is the upper 7 bits of the stack address SPH are shared Tconf Name STACKSEG Type Reference Example bios MEM STACKSEG prog get myMEM System Stack Section sysstack The memory segment containing the system stack applicable only on the C55x device Tconf Name SYSSTACKSEG Type Reference Example bios MEM SYSSTACKSEG prog get myMEM DSP BIOS Init Tables gblinit The mem...

Page 235: ...ISEG Type Reference Example bios MEM HWISEG prog get myMEM Interrupt Service Table Memory hwi_vec The memory segment containing the Interrupt Service Table IST Tconf Name HWIVECSEG Type Reference Example bios MEM HWIVECSEG prog get myMEM RTDX Text Segment rtdx_text The memory segment containing the code sections for the RTDX module Tconf Name RTDXTEXTSEG Type Reference Example bios MEM RTDXTEXTSEG...

Page 236: ... Example bios MEM CINITSEG prog get myMEM C Function Initialization Table pinit The memory segment containing the table of global object constructors Global constructors must be called during program initialization The C C compiler produces a table of constructors to be called at startup The table is contained in a named section called pinit The constructors are invoked in the order that they occu...

Page 237: ... The linker allows you to allocate sections twice once to set a load address and again to set a run address If you do not select a separate load address for a section the section loads and runs at the same address If you do select a separate load address the section is allocated as if it were two separate sections of the same size The load address is where raw data for the section is placed Refere...

Page 238: ... Tconf Name LOADTRCDATASEG Type Reference Example bios MEM LOADTRCDATASEG prog get myMEM Load Address Text Section text The memory segment containing the load allocation of the section that contains the executable code string literals and compiler generated constants Tconf Name LOADTEXTSEG Type Reference Example bios MEM LOADTEXTSEG prog get myMEM Load Address Switch Jump Tables switch The memory ...

Page 239: ... the load allocation of the section that contains dispatch code for HWIs configured to be monitored Tconf Name LOADHWISEG Type Reference Example bios MEM LOADHWISEG prog get myMEM Load Address Interrupt Service Table Memory hwi_vec The memory segment containing the load allocation of the section that contains the Interrupt Service Table Tconf Name LOADHWIVECSEG Type Reference Example bios MEM LOAD...

Page 240: ... in this memory segment Memory can by allocated dynamically from a heap In order to remove the heap from a memory segment you can select another memory segment that contains a heap for properties that dynamically allocate memory in this memory segment The properties you should check are in the Memory Section Manager the Segment for DSP BIOS objects and Segment for malloc free properties and the Ta...

Page 241: ...Example myMem heapLabel prog extern seg_name asm space Type of memory segment This is set to code for memory segments that store programs and data for memory segments that store program data Tconf Name space Type EnumString Options code data io Example myMem space code data The predefined memory segments in a configuration file particularly those for external memory are dependent on the board temp...

Page 242: ...and returns MEM_ILLEGAL MEM functions that allocate and deallocate memory internally lock the memory by calling the LCK_pend and LCK_post functions If another task already holds a lock to the memory there is a context switch For this reason MEM_alloc cannot be called from the context of a SWI or HWI MEM_alloc checks the context from which it is called It calls SYS_error and returns MEM_ILLEGAL if ...

Page 243: ...d a length of 0x19000 The heap within MYRAM is also 100K words and has a heap identifier label of MYSEG So this heap also has a base address of 2 F000 and ends at 4 7FFF To prevent a memory block from crossing a page boundary the MEM Module separates this heap into the following memory blocks which are aligned along 64K page boundaries Figure 2 1 MYSEG Heap Initial Memory Map Suppose your program ...

Page 244: ...gure and list that follow Figure 2 2 MYSEG Memory Map After Allocation P3 MEM_alloc MYSEG 0xFF80 0 This call requests 0xFF80 words The first available block at 2 F000 has a size of 0x1000 it is too small for 0xFF80 The next block at 3 0000 has a size of 0x10000 it is large enough to allocate 0xFF80 words So P3 points to a block from 3 0080 to 3 FFFF because MEM_alloc takes memory from the bottom o...

Page 245: ... requests 0x800 words This time the first block is large enough So P4 points to a block from 2 F800 to 2 FFFF Consider how this memory map would change if the same MEM_alloc calls were made in the following sequence P1 MEM_alloc MYSEG 0x6000 0 P2 MEM_alloc MYSEG 0x1800 0 P3 MEM_alloc MYSEG 0xFF80 0 P4 MEM_alloc MYSEG 0x800 0 The results of this modified call sequence are as follows and are shown i...

Page 246: ...ize the size of memory blocks within the heap If possible allocate larger blocks of memory from the heap first Previous allocations of small memory blocks can reduce the size of the memory blocks available for large memory allocations Realize that MEM_alloc can fail and call SYS_error even if the heap contain a sufficient absolute amount of unallocated space This is because the largest free memory...

Page 247: ...t name as a variable with an integer value The block contains size MADUs and starts at an address that is a multiple of align If align is 0 or 1 there is no alignment constraint If the memory request cannot be satisfied MEM_calloc calls SYS_error with SYS_EALLOC and returns MEM_ILLEGAL MEM functions that allocate and deallocate memory internally lock the memory by calling the LCK_pend and LCK_post...

Page 248: ...ributes are specified through a structure of type MEM_Attrs Note No attributes are supported for segments and the type MEM_Attrs is defined as a dummy structure If there are undefined slots available in the internal table of memory segment identifiers one of those slots is re used for the new segment If there are no undefined slots available in the internal table the table size is increased via ME...

Page 249: ...efine Application Program Interface 2 221 The length parameter must be a multiple of MEM_HEADERSIZE and must be at least equal to MEM_HEADERSIZE The base Ptr cannot be NULL See Also MEM_redefine MEM_undefine ...

Page 250: ...te memory internally lock the memory by calling the LCK_pend and LCK_post functions If another task already holds a lock to the memory there is a context switch For this reason MEM_free cannot be called from the context of a SWI or HWI Although MEM_free combines newly freed blocks with adjacent free blocks it does not combine blocks that cross a 64K page boundary See the MEM_alloc topic for inform...

Page 251: ...ue Ptr addr heap base address pointer Description MEM_getBaseAddress returns the base address of the memory heap with the segment ID specified by the segid parameter Constraints and Calling Context The segid can be an integer or a memory segment name defined in the configuration See Also MEM Object Properties MEM_getBaseAddress Get base address of a memory heap ...

Page 252: ...lloc thus improving performance and determinism within the MEM_define call MEM_increaseTableSize internally locks memory by calling LCK_pend and LCK_post If another task already holds a lock to the memory there is a context switch For this reason MEM_increaseTableSize cannot be called from the context of a SWI or HWI It can be called from main or a TSK The duration that the API holds the memory lo...

Page 253: ... The new block should be aligned on a MEM_HEADERSIZE boundary and the length should be a multiple of MEM_HEADERSIZE Constraints and Calling Context MEM_redefine internally locks the memory by calling LCK_pend and LCK_post If another task already holds a lock to the memory there is a context switch For this reason MEM_redefine cannot be called from the context of a SWI or HWI It can be called from ...

Page 254: ...f minimum addressable units MADUs MEM_stat returns TRUE if segid corresponds to a valid memory segment and FALSE otherwise If MEM_stat returns FALSE the contents of statbuf are undefined If the segment has been undefined with MEM_undefine this function returns FALSE MEM functions that access memory internally lock the memory by calling the LCK_pend and LCK_post functions If another task already ho...

Page 255: ...by a subsequent MEM_define call MEM_undefine internally locks the memory by calling LCK_pend and LCK_post If another task already holds a lock to the memory there is a context switch For this reason MEM_undefine cannot be called from the context of a SWI or HWI It can be called from main or a TSK The duration that the API holds the memory lock is variable Constraints and Calling Context Do not cal...

Page 256: ...size MADUs and starts at an address that is a multiple of align If align is 0 or 1 there is no alignment constraint If the memory request cannot be satisfied MEM_valloc calls SYS_error with SYS_EALLOC and returns MEM_ILLEGAL MEM functions that allocate and deallocate memory internally lock the memory by calling the LCK_pend and LCK_post functions If another task already holds a lock to the memory ...

Page 257: ...gId 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_isLocalQueue Returns TRUE if local message queue 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 rea...

Page 258: ...cture typedef struct MSGQ_Config MSGQ_Obj msgqQueues Array of MSGQ handles MSGQ_TransportObj transports Transport array Uint16 numMsgqQueues Number of MSGQ handles Uint16 numProcessors Number of processors Uint16 startUninitialized 1st MSGQ to init MSGQ_Queue errorQueue Receives transport err Uint16 errorPoolId Alloc errors from poolId MSGQ_Config Asynchronous locate message typedef struct MSGQ_As...

Page 259: ...or messaging The MSGQ module with a substantially similar API is implemented in DSP BIOS Link for certain TI general purpose processors GPPs particularly those used in OMAP devices MSGQ provides more sophisticated messaging than other modules It is typically used for complex situations such as multi processor messaging The following are key features of the MSGQ module Writers and readers can be re...

Page 260: ...ue Once a message is sent the writer loses ownership of the message and should not attempt to modify the message Once the reader receives the message it owns the message It may either free the message or re use the message Messages in a message queue can be of variable length The only requirement is that the first field in the definition of a message must be a MSGQ_MsgHeader element typedef struct...

Page 261: ...r more about using the MSGQ module including information about multi processor issues and a comparison of data transfer modules see the DSP BIOS User s Guide SPRU423F MSGQ APIs The MSGQ APIs are used to open and close message queues and to send and receive messages The MSGQ APIs shield the application from having to contain any knowledge about transports and allocators The following figure shows t...

Page 262: ...ronous non blocking alternative Static Configuration In order to use the MSGQ module and the allocators it depends upon you must statically configure the following ENABLEMSGQ property of the MSGQ module using Tconf see MSGQ Manager Properties on page 2 238 MSGQ_config variable in application code see below PROCID property of the GBL module using Tconf see GBL Module Properties on page 2 109 ENABLE...

Page 263: ... array of MSGQ_TransportObj items defines transport objects with the following structure typedef struct MSGQ_TransportObj MSGQ_MqtInit initFxn Transport init func MSGQ_TransportFxns fxns Interface funcs Ptr params Setup parameters Ptr object Transport specific object Uint16 procId Processor Id talked to MSGQ_TransportObj Field Type Description msgqQueues MSGQ_Obj Array of message queue objects The...

Page 264: ...QUEUES static MSGQ_TransportObj transports NUMPROCESSOR MSGQ_NOTRANSPORT MSGQ_Config MSGQ_config msgQueues transports NUMMSGQUEUES NUMPROCESSORS 0 MSGQ_INVALIDMSGQ POOL_INVALIDID Field Type Description initFxn MSGQ_MqtInit Initialization function for this transport This function is called during DSP BIOS startup More explicitly it is called before main fxns MSGQ_TransportFxns Pointer to the transp...

Page 265: ...RS 3 in this example processors The transports array in the single image might look like this MSGQ_TransportObj transports 2 NUMPROCESSORS MSGQ_NOTRANSPORT proc 0 talk to proc 0 proc 0 talk to proc 1 proc 0 talk to proc 2 proc 1 talk to proc 0 MSGQ_NOTRANSPORT proc 1 talk to proc 1 proc 1 talk to proc 2 In the User Init Function the application would call GBL_setProcId with the correct processor I...

Page 266: ...tified No messages should be sent to a closed message queue Additionally there should be no active call to MSGQ_get or MSGQ_getAttrs to a message queue that is being closed When a message queue is closed all unread messages in the message queue are freed MSGQ Manager Properties To configure the MSGQ manager the MSGQ_Config structure must be defined in the C code See Static Configuration on page 2 ...

Page 267: ...ed it can be sent Once a message is received it must either be freed or re used The poolId must correspond to one of the allocators specified by the allocators field of the POOL_Config structure specified by the application See Static Configuration on page 2 286 If a message is allocated SYS_OK is returned Otherwise SYS_EINVAL is returned if the poolId is invalid and SYS_EALLOC is returned if no m...

Page 268: ...If any messages are in the message queue they are deleted This function is performed by the reader Threads that have located with MSGQ_locate or MSGQ_locateAsync the message queue being closed are not notified about the closure If successful this function returns SYS_OK Constraints and Calling Context The message queue must have been returned from MSGQ_open See Also MSGQ_open MSGQ_close Close a me...

Page 269: ...eue should call this API to determine the number of messages in the reader s message queue This API is not thread safe with MSGQ_get when accessing the same message queue so the caller of MSGQ_count must prevent any calls to MSGQ_get If successful this function returns SYS_OK Constraints and Calling Context The message queue must have been returned from a MSGQ_open call Example status MSGQ_count r...

Page 270: ...he allocator If successful this function returns SYS_OK This call is non blocking and can be called from a HWI SWI or TSK Constraints and Calling Context The message must have been allocated via MSGQ_alloc Example status MSGQ_get readerMsgQueue MSGQ_Msg msg SYS_FOREVER if status SYS_OK SYS_printf MSGQ_get call failed process message MSGQ_free msg See Also MSGQ_alloc MSGQ_free Free a message ...

Page 271: ...ssed to MSGQ_open for this message queue is called The pend function blocks up to the timeout value SYS_FOREVER forever The timeout units are system clock ticks This function is deterministic if timeout is zero MSGQ_get can be called from a TSK with any timeout It can be called from a HWI or SWI if the timeout is zero If successful this function returns SYS_OK Otherwise SYS_ETIMEOUT is returned if...

Page 272: ... API returns SYS_OK unless the message queue is not local that is it was opened on another processor If the message queue is not local the API returns SYS_EINVAL and does not change the contents of the passed in attrs structure Example status MSGQ_getAttrs msgqQueue attrs if status SYS_OK return notifyHandle attrs notifyHandle Constraints and Calling Context The message queue must have been return...

Page 273: ...s the application to determine the destination message queue of a message This API is generally used by transports to determine the final destination of a message This API can also be used by the application once the message is received This function can be called from a HWI SWI or TSK Constraints and Calling Context The message must have been sent via MSGQ_put MSGQ_getDstQueue Get destination mes...

Page 274: ...GQ_getMsgId returns the message ID from a received message This message ID is specified via the MSGQ_setMsgId function This function can be called from a HWI SWI or TSK Example Make sure the message is the one expected if MSGQ_getMsgId MSGQ_Msg msg MESSAGEID SYS_abort Unexpected message See Also MSGQ_setMsgId MSGQ_getMsgId Return the message ID from a message ...

Page 275: ...ge size Reentrant yes Description MSGQ_getMsgSize returns the size of the message buffer out of the received message The size is in minimum addressable data units MADUs This function can be used to determine if a message can be re used This function can be called from a HWI SWI or TSK See Also MSGQ_alloc MSGQ_getMsgSize Return the message size from a message ...

Page 276: ...function without knowing the name of the message queue This function can be used even if the queueName used with MSGQ_open was NULL or non unique Note The msgqQueue may not be the sender s message queue handle The sender is free to use any created message queue handle This function can be called from a HWI SWI or TSK If successful this function returns SYS_OK Example Get the handle and send the me...

Page 277: ...ge queue is local that is opened on this processor or remote that is opened on a different processor If the message queue is local the flag returned is TRUE Otherwise it is FALSE Constraints and Calling Context This function can be called from a HWI SWI or TSK Example flag MSGQ_isLocalQueue readerMsgQueue if flag TRUE Message queue is local return See Also MSGQ_open MSGQ_isLocalQueue Return whethe...

Page 278: ...ueue the next transport is queried If no transport can locate the message queue an error is returned In a multiple processor environment transports can block when they are queried if you call MSGQ_locate The timeout in the MSGQ_LocateAttrs structure specifies the maximum time each transport can block The default is SYS_FOREVER that is each transport can block forever Remember that if you specify 1...

Page 279: ...ws MSGQ_LocateAttrs MSGQ_LOCATEATTRS SYS_FOREVER If successful this function returns SYS_OK Otherwise it returns SYS_ENOTFOUND to indicate that it could not locate the specified message queue Constraints and Calling Context Cannot be called from main Cannot be called in a SWI or HWI context Example status MSGQ_locate reader readerMsgQueue NULL if status SYS_OK SYS_abort Failed to locate reader mes...

Page 280: ...essage is sent to the specified replyQueue If no transport can locate the message queue no message is sent This function is performed by a writer The reader must have already called MSGQ_open for this queueName An asynchronous locate can be performed from a SWI or TSK It cannot be performed in main The message ID for an asynchronous locate message is Asynchronous locate message ID define MSGQ_ASYN...

Page 281: ...to allocate an asynchronous locate message Cannot be called in the context of main Example The following example shows an asynchronous locate performed in a task Time spent blocking is dictated by the timeout specified in the MSGQ_get call Error handling statements were omitted for brevity status MSGQ_open myMsgQueue myQueue msgqAttrs locateAsyncAttrs MSGQ_LOCATEATTRS locateAsyncAttrs poolId STATI...

Page 282: ...ise it returns SYS_ENOTFOUND to indicate that no empty spot was available in the message queue array If the application will use MSGQ_locate or MSGQ_locateAsync to find this message queue the queueName must be unique If the application will never need to use the locate APIs the queueName may be NULL or a non unique name Instead of using a fixed notification mechanism such as SEM_pend and SEM_post ...

Page 283: ...nd and SEM_post are an invalid pend post pair The following example in which the reader calls MSGQ_get with a timeout of SYS_FOREVER shows why 1 A writer sends 10 messages making the count 10 in the semaphore 2 The reader then calls MSGQ_get 10 times Each call returns a message without calling the pend function 3 The reader then calls MSGQ_get again Since there are no messages the pend function is...

Page 284: ...ers should use the message queue returned by MSGQ_locate MSGQ_locateAsync or MSGQ_getSrcQueue If a post function is specified the function must be non blocking If a pend function is specified the function must be non blocking when timeout is zero Each message queue must have a unique name if the application will use MSGQ_locate or MSGQ_locateAsync The queueName must be persistent The MSGQ module r...

Page 285: ... IDs defined for MSGQ_setMsgId The reader of a message can use MSGQ_getMsgId to get the ID from the message The source message queue parameter to MSGQ_setSrcQueue allows the sender of the message to specify a source message queue The receiver of the message can use MSGQ_getSrcQueue to extract the embedded message queue from the message A client server application might use this mechanism because i...

Page 286: ...must either be freed or re used Example Send the message back status MSGQ_put replyMsgQueue MSGQ_Msg msg if status SYS_OK Need to free the message MSGQ_free MSGQ_Msg msg SYS_abort Failed to send the message See Also MSGQ_get MSGQ_open MSGQ_setMsgId MSGQ_getMsgId MSGQ_setSrcQueue MSGQ_getSrcQueue ...

Page 287: ... located message queue That is it releases a message queue returned from MSGQ_locate or MSGQ_locateAsync This function is performed by a writer If successful this function returns SYS_OK Otherwise it may return an error code returned by the transport Constraints and Calling Context The handle must have been returned from MSGQ_locate or MSGQ_locateAsync See Also MSGQ_locate MSGQ_locateAsync MSGQ_re...

Page 288: ...olId specifies the allocator the transport should use to allocate error messages If the transports cannot allocate a message no action is performed If this function is not called or if errorHandler is set to MSGQ_INVALIDMSGQ no error messages will be allocated and sent This function can be called multiple times with only the last handler being active If successful this function returns SYS_OK The ...

Page 289: ... mqtId parameter MSGQ_MQTERROREXIT ID of the transport that is exiting Not used MSGQ_MQTFAILEDPUT ID of the transport that failed to send a message ID of destination queue The parameter is 16 bits so only the lower 16 bits of the msgqQueue is logged The top 16 bits of the msgQueue contain the destination processor ID which is also the mqtId You can OR the mqtId shifted over by 16 bits with the par...

Page 290: ... accordingly for example endian conversion is performed The message IDs used when sending messages are application specific They can have any value except values in the following ranges Reserved for the MSGQ module messages 0xFF00 0xFF7F Reserved for internal transport usage 0xFF80 0xFFFE Used to signify an invalid message ID 0xFFFF The following table lists the message IDs currently used by the M...

Page 291: ...263 Example Fill in the message msg sequenceNumber 0 MSGQ_setMsgId MSGQ_Msg msg MESSAGEID Send the message status MSGQ_put readerMsgQueue MSGQ_Msg msg if status SYS_OK SYS_abort Failed to send the message See Also MSGQ_getMsgId MSGQ_setErrorHandler ...

Page 292: ...MSGQ_INVALIDMSGQ When this API is called it updates the field accordingly This API can be called multiple times on a message If a message is sent to another processor the source message queue field is managed by the transports accordingly Constraints and Calling Context Message must have been allocated originally from MSGQ_alloc msgqQueue must have been returned from MSGQ_open Example Fill in the ...

Page 293: ...t the number of pipe frames available for reading PIP_getReaderSize Get the number of words of data in a pipe frame PIP_getWriterAddr Get the value of the writerAddr pointer of the pipe PIP_getWriterNumFrames Get the number of pipe frames available to write 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...

Page 294: ... Module Configuration Parameters Instance Configuration Parameters Description The PIP module manages data pipes which are used to buffer streams of input and output data These data pipes provide a consistent software data structure you can use to drive I O between the DSP device and all kinds of real time peripheral devices Name Type Default OBJMEMSEG Reference prog get DARAM Name Type Default En...

Page 295: ...ternally pipes are implemented as a circular list frames are reused at the writer end of the pipe after PIP_free releases them The notifyReader and notifyWriter functions are called from the context of the code that calls PIP_put or PIP_free These functions can be written in C or assembly To avoid problems with recursion the notifyReader and notifyWriter functions normally should not directly call...

Page 296: ...etween a single reader and a single writer This transfer is often between an HWI and a SWI but pipes can also be used to transfer data between two application threads The following global property can be set for the PIP module in the PIP Manager Properties dialog of the DSP BIOS Configuration Tool or in a Tconf script Object Memory The memory segment that contains the PIP objects Tconf Name OBJMEM...

Page 297: ...of each frame in words Tconf Name frameSize Type Int16 Example myPip frameSize 8 numframes The number of frames Tconf Name numFrames Type Int16 Example myPip numFrames 2 monitor The end of the pipe to be monitored by a hidden STS object Can be set to reader writer or nothing In the Statistics View analysis tool your choice determines whether the STS display for this pipe shows a count of the numbe...

Page 298: ...vailable This function should notify for example by calling SWI_andnHook the object that reads from this pipe that a full frame is ready to be processed The notifyReader function is performed as part of the thread that called PIP_put or PIP_get To avoid problems with recursion the notifyReader function should not directly call any of the PIP module functions for the same pipe Tconf Name notifyRead...

Page 299: ... property of the PIP object This function should notify for example by calling SWI_andnHook the object that writes to this pipe that an empty frame is available The notifyWriter function is performed as part of the thread that calls PIP_free or PIP_alloc To avoid problems with recursion the notifyWriter function should not directly call any PIP module functions for the same pipe Constraints and Ca...

Page 300: ...opy input data to output frame src PIP_getReaderAddr in dst PIP_getWriterAddr out size PIP_getReaderSize in PIP_setWriterSize out size for size 0 size dst src output copied data and free input frame PIP_put out PIP_free in The example for HST_getpipe page 2 147 also uses a pipe with host channel objects See Also PIP_free PIP_get PIP_put HST_getpipe ...

Page 301: ...tion specified by the notifyWriter property of the PIP object This function should notify for example by calling SWI_andnHook the object that writes to this pipe that an empty frame is available The notifyWriter function is performed as part of the thread that called PIP_free or PIP_alloc To avoid problems with recursion the notifyWriter function should not directly call any of the PIP module func...

Page 302: ... example by calling SWI_andnHook the object that reads from this pipe that a full frame is available The notifyReader function is performed as part of the thread that calls PIP_get or PIP_put To avoid problems with recursion the notifyReader function should not directly call any PIP module functions for the same pipe Constraints and Calling Context Before calling PIP_get a function should check th...

Page 303: ...iption PIP_getReaderAddr is a C function that returns the value of the readerAddr pointer of a pipe object The readerAddr pointer is normally used following a call to PIP_get as the address to begin reading from Example Void audio PIP_Obj in PIP_Obj out Uns src dst Uns size if PIP_getReaderNumFrames in 0 PIP_getWriterNumFrames out 0 error PIP_get in get input data PIP_alloc out allocate output buf...

Page 304: ...Syntax num PIP_getReaderNumFrames pipe Parameters PIP_Handle pipe pip object handle Return Value Uns num number of filled frames to be read Reentrant yes Description PIP_getReaderNumFrames is a C function that returns the value of the readerNumFrames element of a pipe object Before a function attempts to read from a pipe it should call PIP_getReaderNumFrames to ensure at least one full frame is av...

Page 305: ...IOS 5 32 C Interface Syntax num PIP_getReaderSize pipe Parameters PIP_Handle pipe pipe object handle Return Value Uns num number of words to be read from filled frame Reentrant yes Description PIP_getReaderSize is a C function that returns the value of the readerSize element of a pipe object As a function reads from a pipe it should use PIP_getReaderSize to determine the number of valid words of d...

Page 306: ...s to DSP BIOS 5 32 C Interface Syntax writerAddr PIP_getWriterAddr pipe Parameters PIP_Handle pipe pipe object handle Return Value Ptr writerAddr Reentrant yes Description PIP_getWriterAddr is a C function that returns the value of the writerAddr pointer of a pipe object The writerAddr pointer is normally used following a call to PIP_alloc as the address to begin writing to Example See the example...

Page 307: ... C Interface Syntax num PIP_getWriterNumFrames pipe Parameters PIP_Handle pipe pipe object handle Return Value Uns num number of empty frames to be written Reentrant yes Description PIP_getWriterNumFrames is a C function that returns the value of the writerNumFrames element of a pipe object Before a function attempts to write to a pipe it should call PIP_getWriterNumFrames to ensure at least one e...

Page 308: ...meters PIP_Handle pipe pipe object handle Return Value Uns num num of words to be written in empty frame Reentrant yes Description PIP_getWriterSize is a C function that returns the value of the writerSize element of a pipe object As a function writes to a pipe it can use PIP_getWriterSize to determine the maximum number words that can be written to a pipe frame Example if PIP_getWriterNumFrames r...

Page 309: ...ithout actually claiming the pipe frame The pipe parameter is the pipe object handle the addr parameter is the address of the variable that keeps the retrieved frame address and the rw parameter is the flag that indicates what side of the pipe PIP_peek is to operate on If rw is PIP_READER then PIP_peek operates on the reader side of the pipe If rw is PIP_WRITER then PIP_peek operates on the writer...

Page 310: ...e it runs the function specified by the notifyReader property of the PIP object This function should notify for example by calling SWI_andnHook the object that reads from this pipe that a full frame is ready to be processed The notifyReader function is performed as part of the thread that called PIP_get or PIP_put To avoid problems with recursion the notifyReader function should not directly call ...

Page 311: ...ers PIP_Handle pipe pipe object handle Return Value Void Description PIP_reset resets all fields of a pipe object to their original values The pipe parameter specifies the address of the pipe object that is to be reset Constraints and Calling Context PIP_reset should not be called between the PIP_alloc call and the PIP_put call or between the PIP_get call and the PIP_free call PIP_reset should be ...

Page 312: ...5 32 C Interface Syntax PIP_setWriterSize pipe size Parameters PIP_Handle pipe pipe object handle Uns size size to be set Return Value Void Reentrant no Description PIP_setWriterSize is a C function that sets the value of the writerSize element of a pipe object As a function writes to a pipe it can use PIP_setWriterSize to indicate the number of valid words being written to a pipe frame Example Se...

Page 313: ...erties heading For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Description The POOL module describes standard interface functions that allocators must provide The allocator interface functions are called internally by the MSGQ module and not by user applications A simple static allocator called STATICPOOL is provided with DSP BIOS Oth...

Page 314: ...page 2 289 POOL_config variable in application code see below An application must provide a filled in POOL_config variable if it uses one or more allocators POOL_Config POOL_config Where the POOL_Config structure has the following structure typedef struct POOL_Config POOL_Obj allocators Array of allocators Uint16 numAllocators Num of allocators POOL_Config The fields in this structure are as follo...

Page 315: ...messages from the buffer The following are its configuration parameters typedef struct STATICPOOL_Params Ptr addr size_t length size_t bufferSize STATICPOOL_Params Field Type Description initFxn POOL_Init Initialization function for this allocator This function will be called during DSP BIOS initialization More explicitly it is called before main fxns POOL_Fxns Pointer to the allocator s interface...

Page 316: ...ges in the two allocators Must be a multiple of 8 as required by static allocator define MSGSIZE0 64 define MSGSIZE1 128 enum Allocator ID and number of allocators MQASTATICID0 0 MQASTATICID1 NUMALLOCATORS Field Type Description addr Ptr User supplied block of memory for allocating messages from The address will be aligned on an 8 MADU boundary for correct structure alignment on all ISAs If there ...

Page 317: ...RS STATICPOOL_init POOL_Fxns STATICPOOL_FXNS poolParams0 poolObj0 STATICPOOL_init POOL_Fxns STATICPOOL_FXNS poolParams1 poolObj1 POOL_Config POOL_config allocators NUMALLOCATORS POOL Manager Properties To configure the POOL manager the POOL_Config structure must be defined in the application code See Static Configuration on page 2 286 The following global property must also be set in order to use ...

Page 318: ...P BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Description While some applications can schedule functions based on a real time clock many applications need to schedule functions based on I O availability or some other programmatic event The PRD module allows you to create PRD objects that schedule periodic execution of program functions The period ...

Page 319: ...escribed in the compiler manual The PRD module uses a SWI object called PRD_swi by default which itself is triggered on a periodic basis to manage execution of period objects Normally this SWI object should have the highest SWI priority to allow this SWI to be performed once per tick This SWI is automatically created or deleted by the configuration if one or more or no PRD objects exist The total ...

Page 320: ... the CLK module otherwise you must explicitly set this property The total time required to perform all PRD functions must be less than the number of microseconds between ticks Tconf Name MICROSECONDS Type Int16 Example bios PRD MICROSECONDS 1000 0 PRD Object Properties To create a PRD object in a configuration script use the following syntax The Tconf examples that follow assume the object has bee...

Page 321: ...ns must be less than the number of microseconds between ticks Tconf Name fxn Type Extern Example myPrd fxn prog extern prdFxn arg0 arg1 Two Arg type arguments for the user specified function above Tconf Name arg0 Type Arg Tconf Name arg1 Type Arg Example myPrd arg0 0 period ms The number of milliseconds represented by the period specified above This is an informational property only Tconf Name N A...

Page 322: ...tion clock ticks that have occurred since the program started running When the number of ticks reaches the maximum value that can be stored in 32 bits the value wraps back to 0 See the CLK Module page 2 39 for more details If the periodic functions are being driven programmatically the tick value is the number of times PRD_tick has been called Example showTicks Void showTicks LOG_printf trace tick...

Page 323: ...d be executed a certain number of periodic ticks after some condition is met When you use PRD_start to start a period object the exact time the function runs can vary by nearly one tick cycle As Figure 2 10 shows PRD ticks occur at a fixed rate and the call to PRD_start can occur at any point between ticks Figure 2 10 PRD Tick Cycles If PRD_start is called again before the period for the object ha...

Page 324: ...ot in the configuration Unlike PRD objects that are configured as continuous one shot PRD objects do not automatically continue to run A one shot PRD object runs its function only after the specified numbers of ticks have occurred after a call to PRD_start PRD_stop is the way to stop those one shot PRD objects once started and before their period counters have run out Example PRD_stop prd See Also...

Page 325: ...ld perform PRD_tick to notify a periodic function when data is available for processing Constraints and Calling Context All the registers that are modified by this API should be saved and restored before and after the API is invoked respectively When called within an HWI the code sequence calling PRD_tick must be either wrapped within an HWI_enter HWI_exit pair or invoked by the HWI dispatcher Int...

Page 326: ...urrent V F setpoint in effect PWRM_getDependencyCount Get count of dependencies currently declared on a resource PWRM_getNumSetpoints Get the number of V F setpoints supported for the current platform PWRM_getSetpointInfo Get the corresponding frequency and CPU core voltage for a setpoint PWRM_getTransitionLatency Get the latency to scale from one setpoint to another setpoint PWRM_idleClocks Immed...

Page 327: ...leep modes to save power during inactivity These can be set statically or at run time You can coordinate sleep modes and V F scaling using registration and notification mechanisms provided by the PWRM module PWRM functions are designed to save and restore the users environment where appropriate For example interrupt masks are saved before and restored after going to deep sleep For further descript...

Page 328: ... PWRM indicating that it cannot support the requested V F setpoint PWRM_EOUTOFRANGE The operation could not be completed because a parameter was out of the range supported by PWRM PWRM_ETIMEOUT A timeout occurred while trying to com plete the operation PWRM_ETOOMANYCALLS Indicates PWRM_releaseDependency has been called more times for a resource than PWRM_setDependency was called PWRM_EBUSY The req...

Page 329: ...clock domain OMAP 2420 only PWRM_IDLEXPORT Idle the XPORT clock domain OMAP 2420 only Name Usage Name Type Default Enum Options ENABLE Bool false BOOTHOOK Bool false BOOTHOOKFXN Extern prog extern FXN_F_nop ADAPTCLK Bool false DEVICEINIT Bool false RESOURCETRACKING Bool false DEVICEDBMEMSEG Bool prog get DARAM IDLEDOMAINS Bool false IDLEIPORT Bool false OMAP 2420 only IDLEHWA Bool false OMAP 2420 ...

Page 330: ...nf or in a Tconf script General tab Enable PWRM Manager Check this box if you want to enable the power manager If you do not plan to use the power manager you should leave it disabled to reduce the size of your application Tconf Name ENABLE Type Bool Example bios PWRM ENABLE false PSLCONFIGLIB String PSL_cfg_c5509a a55L ENABLESLEEP Bool true SLEEPIPORT Bool true OMAP 2420 only SLEEPHWA Bool true O...

Page 331: ...rs for CLK functionality that is if you use an external clock trigger set this property to false to save code space and eliminate unnecessary steps If you set this property to true do not use the CLK_reconfig CLK_stop or CLK_start APIs in your application Tconf Name ADAPTCLK Type Bool Example bios PWRM ADAPTCLK false Enable device initialization by PWRM Set this to true if you want PWRM to initial...

Page 332: ...mains are restored to their previous configuration If you want to idle a specific domain indefinitely use the PWRM_idleClocks function To configure which clock domains are idled in deep sleep mode use the Sleep tab Tconf Name IDLEDOMAINS Type Bool Example bios PWRM IDLEDOMAINS false HWA Checking this box causes the HWA clock domain to be idled during the DSP BIOS idle loop This setting can be modi...

Page 333: ...lock domain to be idled during the DSP BIOS idle loop This setting can be modified at runtime using the PWRM_configure function Checking this box does not ensure that every peripheral is idled during the idle loop Several peripherals can specify whether to idle when the peripheral domain is idled For example on the C5509A the McBSP is specified via the IDLE_EN bit in the PCRs timers via the IDLE_E...

Page 334: ...the application Tconf Name SCALING Type Bool Example bios PWRM SCALING false Initial frequency index to frequency table Specify the initial frequency of the DSP after booting This value is a setpoint from the Frequency Setpoint Table For details see PWRM_changeSetpoint on page 2 310 Tconf Name INITIALFREQ Type Numeric Example bios PWRM INITIALFREQ 15 Initial voltage volts Specify the initial volta...

Page 335: ...Specify the PSL configuration library to link with Specify only the filename of the library to link with for this property The include path to the PSL Configuration Library should be added to the linker command file if it is not in the default path An example library filename is PSL_cfg_c5509a a55L Tconf Name PSLCONFIGLIB Type String Example bios PWRM PSLCONFIGLIB PSL_cfg_c5509a a55L Sleep tab Ena...

Page 336: ...LKGEN clock domain to be idled during deep sleep The CACHE DMA and CPU domains must be idled for deep sleep before you can choose to idle the CLKGEN domain Tconf Name SLEEPCLKGEN Type Bool Example bios PWRM SLEEPCLKGEN true PERIPHS Checking this box causes the PERIPH clock domain to be idled during deep sleep See the description of the PERIPHS box in the Idling tab for details on idling various pe...

Page 337: ...0 Type Numeric Example bios PWRM WKUPIER0 0 Wakeup interrupt mask IER1 Specifies the wakeup interrupt mask for IER1 This mask is loaded into the DSP s Interrupt Enable Register 1 IER1 before the PWRM module causes the DSP to sleep Tconf Name WKUPIER1 Type Numeric Example bios PWRM WKUPIER1 0 Enable sleep until restart This property specifies whether sleep until restart mode is enabled In this mode...

Page 338: ...ic reduction in power consumption Note that there are issues you should be aware of when reducing the clock frequency For a discussion of these issues see the TMS320 DSP BIOS User s Guide SPRA423 The newSetpoint parameter is a numeric value that indexes into a table of frequency voltage pairs as defined by the underlying PSL library For example the following table shows the setpoints for the C5509...

Page 339: ...of type PWRM_Status The application should treat return values of PWRM_ETIMEOUT or PWRM_EFAIL as critical system failures These values indicate the notification client is unresponsive and the system is in an unknown state Name Usage PWRM_SOK The operation succeeded and the new setpoint is in effect PWRM_EFAIL A general failure occurred The requested setpoint transition did not occur PWRM_ENOTIMPLE...

Page 340: ...ints and Calling Context PWRM_changeSetpoint cannot be called from an HWI This API cannot be called from a program s main function PWRM_changeSetpoint can be called from a SWI only if notifyTimeout is 0 Example define TIMEOUT 10 timeout for notifications PWRM_Status status Int i status PWRM_changeSetpoint i TIMEOUT if status PWRM_SOK LOG_printf TRACE New setpoint d i else if status PWRM_ENOTSUPPOR...

Page 341: ...cy If scaleVoltage if FALSE the voltage is not scaled lower The voltage is always scaled up if the new setpoint frequency is higher than that supported at the current voltage The waitForVoltageScale flag indicates whether PWRM should wait for a down voltage transition to complete before returning from PWRM_changeSetpoint It corresponds to the Wait while voltage is being scaled down property in the...

Page 342: ...lock domain PWRM_IDLECACHE Idle the CACHE clock domain PWRM_IDLEPERIPH Idle the PERIPH clock domain PWRM_IDLECLKGEN Idle the CLKGEN clock domain PWRM_IDLEEMIF Idle the EMIF clock domain PWRM_IDLEIPORT Idle the IPORT clock domain OMAP 2420 only PWRM_IDLEHWA Idle the HWA clock domain OMAP 2420 only PWRM_IDLEMPORT Idle the MPORT clock domain OMAP 2420 only PWRM_IDLEXPORT Idle the XPORT clock domain O...

Page 343: ...ants to check for capabilities in the bitmask PWRM_getCapabilities returns one of the following constants as a status value of type PWRM_Status PWRM_getCapabilities Get information on PWRM capabilities on the current platform Name Usage PWRM_CDEEPSLEEP PWRM_sleepDSP supports deep sleep mode PWRM_CRESOURCETRACKING The PWRM module supports dynamic resource tracking PWRM_CSLEEPUNTILRESTART PWRM_sleep...

Page 344: ...ies on this platform status PWRM_getCapabilities capsMask LOG_printf TRACE Returned mask 0x X capsMask if status PWRM_SOK exit on error LOG_printf TRACE Status x status return exit if V F scaling not supported if capsMask PWRM_CVFSCALING 0 LOG_printf TRACE V F scaling not supported return ...

Page 345: ...is preempted by a thread that changes the setpoint the value PWRM_getCurrentSetpoint returns is the old setpoint and not the new setpoint If this may cause a problem in your application you can disable scheduling around the call to PWRM_getCurrentSetpoint Example PWRM_Status status Uns currSetpoint status PWRM_getCurrentSetpoint currSetpoint LOG_printf TRACE Setpoint d currSetpoint if status PWRM_...

Page 346: ...rce enumeration in a device specific header file For example see pwrm5509a h for the C5509A PWRM_getDependencyCount returns one of the following constants as a status value of type PWRM_Status Example Display some dependency counts LOG_printf trace Initial dependencies PWRM_getDependencyCount PWRM_5509A_CLKOUT count LOG_printf trace CLKOUT count d count PWRM_getDependencyCount PWRM_5509A_MCBSP0 co...

Page 347: ...of setpoints is greater than or equal to 1 PWRM_getNumSetpoints returns one of the following constants as a status value of type PWRM_Status Example PWRM_Status status Uns numSetpoints status PWRM_getNumSetpoints numSetpoints LOG_printf TRACE NumSetpoints d numSetpoints if status PWRM_SOK exit on error LOG_printf TRACE Error status x status return PWRM_getNumSetpoints Get the number of setpoints s...

Page 348: ...tpointInfo should write the DSP core frequency for the specified setpoint The voltage parameter should point to the location where PWRM_getSetpointInfo should write the DSP voltage for the specified setpoint PWRM_getSetpointInfo returns one of the following constants as a status value of type PWRM_Status PWRM_getSetpointInfo Get frequency and CPU core voltage for a setpoint Name Usage PWRM_SOK The...

Page 349: ...mple PWRM_Status status global arrays for saving setpoint info define MAX_SETPOINTS 16 float freq MAX_SETPOINTS float volts MAX_SETPOINTS status PWRM_getSetpointInfo i freq i volts i if status PWRM_SOK exit on error LOG_printf TRACE Error status x status return ...

Page 350: ...e transition would end See PWRM_changeSetpoint for a list of valid setpoints The frequencyLatency parameter should point to the location where PWRM_getTransitionLatency should write the time required to change the CPU frequency from that of the initialSetpoint to that of the finalSetpoint in microseconds Similarly the voltageLatency should point to the location where PWRM_getTransitionLatency shou...

Page 351: ...getTransitionLatency numSetpoints 1 0 frequencyLatency voltageLatency LOG_printf TRACE Frequency latency d Voltage latency d frequencyLatency voltageLatency if status PWRM_SOK exit on error LOG_printf TRACE Error status x status return PWRM_EINVALIDVALUE The operation failed because the initialSetpoint or finalSetpoint parameter was invalid PWRM_EINVALIDPOINTER The operation failed because the lat...

Page 352: ...using the following predefined mask constants The idleStatus parameter should point to the location where PWRM_idleClocks should write the contents of the Idle Status Register ISTR after idling clock domains If PWRM_idleClocks returns PWRM_EFAIL this parameter can be used to determine which domains were idled and which were not For example if a bit was set in the domainMask but is not set in idleS...

Page 353: ...WRM_IDLEEMIF PWRM_IDLEDMA idleStatus if idleStatus PWRM_IDLEEMIF PWRM_IDLEDMA LOG_printf TRACE Idled domains successfully Name Usage PWRM_SOK The operation succeeded PWRM_EFAIL A general failure occurred One of the domains specified in domainMask did not go idle PWRM_EINVALIDPOINTER Operation failed because the idleStatus parameter was NULL PWRM_EINVALIDVALUE Operation failed because the domainMas...

Page 354: ...d in FIFO order The function registered must behave as described in the pwrmNotifyFxn section The eventType parameter identifies the type of power event for which the notify function being registered is to be called This parameter has an enumerated type of PWRM_Event This parameter may have one of the following values PWRM_registerNotify Register a function to be called on a specific power event V...

Page 355: ...cation where PWRM_registerNotify should write a notification handle If the application later needs to unregister the notification function the application should pass this handle to PWRM_unregisterNotify The delayedCompletionFxn is a pointer to a function provided by the PWRM module to the client at registration time If a client cannot act immediately upon notification its notify function should r...

Page 356: ... notifyHandle2 pointers to returned delayed completion fxns Fxn delayFxn1 Fxn delayFxn2 Client 1 registers pre setpoint notification PWRM_registerNotify PWRM_PENDINGSETPOINTCHANGE ALLSETPOINTSALLOWED Fxn myNotifyFxn1 Arg 0x1111 notifyHandle1 Fxn delayFxn1 Client 2 registers post setpoint notification PWRM_registerNotify PWRM_DONESETPOINTCHANGE SOMESETPOINTSALLOWED Fxn myNotifyFxn2 Arg 0x2222 notif...

Page 357: ...he PWRM module The eventType parameter identifies the type of power event for which the notify function is being called This parameter has an enumerated type of PWRM_Event The values for this parameter are listed in the PWRM_registerNotify topic The eventArg1 and eventArg2 parameters are event specific arguments Currently eventArg1 and eventArg2 are used only for V F scaling events PWRM_PENDINGSET...

Page 358: ...ntf TRACE nclient 1 notify PENDINGSETPOINTCHANGE LOG_printf TRACE eventArg p eventArg2 p eventArg eventArg2 LOG_printf TRACE clientArg p clientArg LOG_printf TRACE signal notify complete endif return PWRM_NOTIFYDONE notify complete Name Usage PWRM_NOTIFYDONE The client processed the notification function successfully PWRM_NOTIFYNOTDONE The client must wait for interrupt processing to occur before ...

Page 359: ...CALLS is returned if you call PWRM_releaseDependency when there are no dependencies currently declared for the specified resource either because all have been released or because none were set PWRM_releaseDependency returns one of the following constants as a status value of type PWRM_Status Example Release default dependency on CLKOUT to save power PWRM_releaseDependency PWRM_5509A_CLKOUT PWRM_re...

Page 360: ...n in a device specific header file For example see pwrm5509a h for the C5509A PWRM_setDependency returns one of the following constants as a status value of type PWRM_Status Example Declare an application dependency upon McBSP0 PWRM_setDependency PWRM_5509A_MCBSP0 Declare application dependency upon DMA domain PWRM_setDependency PWRM_5509A_DMA_DOMAIN PWRM_setDependency Declare a dependency upon a ...

Page 361: ...at can wake the DSP from deep sleep are specified by the following PWRM Manager Properties Wakeup interrupt mask IER0 and Wakeup interrupt mask IER1 A call to PWRM_sleepDSP with PWRM_SLEEPUNTILRESTART never returns The use of PWRM_SLEEPUNTILRESTART indicates that the only way to wake up is a DSP reset Note Snooze mode is currently not implemented The sleepArg parameter is a sleepCode specific argu...

Page 362: ...d Calling Context PWRM_sleepDSP cannot be called from an HWI This API cannot be called from a program s main function PWRM_sleepDSP can be called from a SWI only if notifyTimeout is 0 Example define TIMEOUT 10 timeout after 10 ticks LOG_printf TRACE Putting DSP to deep sleep n status PWRM_sleepDSP PWRM_DEEPSLEEP 0 TIMEOUT LOG_printf TRACE DSP awake from deep sleep LOG_printf TRACE Returned 0x x st...

Page 363: ...r is the parameter that was provided by PWRM_registerNotify when the function was registered PWRM_unregisterNotify returns one of the following constants as a status value of type PWRM_Status Constraints and Calling Context This API cannot be called from a program s main function Example PWRM_NotifyHandle notifyHandle1 PWRM_registerNotify PWRM_PENDINGSETPOINTCHANGE ALLSETPOINTSALLOWED Fxn myNotify...

Page 364: ...revious element in queue non atomically QUE_put Put element at end of queue atomically QUE_remove Remove from middle of queue non atomically Constants Types and Structures typedef struct QUE_Obj QUE_Handle queue obj handle struct QUE_Attrs queue attributes Int dummy DUMMY QUE_Attrs QUE_ATTRS default attribute values 0 typedef QUE_Elem queue element Configuration Properties The following list shows...

Page 365: ...command DEV_Frame Many QUE module functions either are passed or return a pointer to an element having the structure defined for QUE elements The functions QUE_put and QUE_get are atomic in that they manipulate the queue with interrupts disabled These functions can therefore be used to safely share queues between tasks or between tasks and SWIs or HWIs All other QUE functions should only be called...

Page 366: ...ollow assume the object has been created as shown here var myQue bios QUE create myQue The following property can be set for a QUE object in the PRD Object Properties dialog of the DSP BIOS Configuration Tool or in a Tconf script comment Type a comment to identify this QUE object Tconf Name comment Type String Example myQue comment my QUE ...

Page 367: ...s is defined as a dummy structure All default attribute values are contained in the constant QUE_ATTRS which can be assigned to a variable of type QUE_Attrs prior to calling QUE_create You can also create a queue by declaring a variable of type QUE_Obj and initializing the queue with QUE_new QUE_create calls MEM_alloc to dynamically create the object s data structure MEM_alloc must acquire a lock ...

Page 368: ...a lock to the memory before proceeding If another task already holds a lock to the memory then there is a context switch Constraints and Calling Context queue must be empty QUE_delete cannot be called from a SWI or HWI No check is performed to prevent QUE_delete from being used on a statically created object If a program attempts to delete a queue object that was created using Tconf SYS_error is c...

Page 369: ...ue is non atomic Therefore the method described for QUE_get of checking to see if a queue is empty and returning the first element otherwise is non atomic Note You should use QUE_get instead of QUE_dequeue if multiple threads share a queue QUE_get runs atomically and is never interrupted QUE_dequeue performs the same action but runs non atomically You can use QUE_dequeue if you disable interrupts ...

Page 370: ...empty queue Parameters QUE_Handle queue queue object handle Return Value Bool empty TRUE if queue is empty Description QUE_empty returns TRUE if there are no elements in queue and FALSE otherwise See Also QUE_get QUE_empty Test for an empty queue ...

Page 371: ...e first field in the structure must be of type QUE_Elem and is used as an internal pointer Note Use QUE_put instead of QUE_enqueue if multiple threads share a queue QUE_put is never interrupted QUE_enqueue performs the same action but runs non atomically You can use QUE_enqueue if you disable interrupts or use a synchronization mechanism such as LCK or SEM to protect the queue QUE_enqueue is somew...

Page 372: ...d SWIs or HWIs Calling QUE_get with an empty queue returns the queue itself This provides a means for using a single atomic action to check if a queue is empty and to remove and return the first element if it is not empty if QUE_Handle elem QUE_get q q process elem Note Use QUE_get instead of QUE_dequeue if multiple threads share a queue QUE_get is never interrupted QUE_dequeue performs the same a...

Page 373: ...f queue The element is not removed from the queue The return value elem is a pointer to the element at the front of the QUE Such elements have a structure defined similarly to that in the example in the QUE Module topic The first field in the structure must be of type QUE_Elem and is used as an internal pointer Calling QUE_head with an empty queue returns the queue itself See Also QUE_create QUE_e...

Page 374: ... to an element to be placed in the QUE Such elements have a structure defined similarly to that in the example in the QUE Module topic The first field in the structure must be of type QUE_Elem and is used as an internal pointer Note If the queue is shared by multiple tasks or tasks and SWIs or HWIs QUE_insert should be used in conjunction with some mutual exclusion mechanism for example SEM_pend S...

Page 375: ...tomic A typical use of QUE_new is to initialize a queue object that has been statically declared instead of being created with QUE_create Note that if the queue is not empty the element s in the queue are not freed or otherwise handled but are simply abandoned If you created a queue by declaring a variable of type QUE_Obj you can initialize the queue with QUE_new See Also QUE_create QUE_delete QUE...

Page 376: ...le in the QUE Module topic The first field in the structure must be of type QUE_Elem and is used as an internal pointer Since QUE queues are implemented as doubly linked lists with a dummy node at the head it is possible for QUE_next to return a pointer to the queue itself Be careful not to call QUE_remove elem in this case Note If the queue is shared by multiple tasks or tasks and SWIs or HWIs QU...

Page 377: ...that in the example in the QUE Module topic The first field in the structure must be of type QUE_Elem and is used as an internal pointer Since QUE queues are implemented as doubly linked lists with a dummy node at the head it is possible for QUE_prev to return a pointer to the queue itself Be careful not to call QUE_remove elem in this case Note If the queue is shared by multiple tasks or tasks an...

Page 378: ...pointer Since QUE_put manipulates queues with interrupts disabled queues can be shared by multiple tasks or by tasks and SWIs or HWIs Note Use QUE_put instead of QUE_enqueue if multiple threads share a queue QUE_put is never interrupted QUE_enqueue performs the same action but runs non atomically You can use QUE_enqueue if you disable interrupts or use a synchronization mechanism such as LCK or SE...

Page 379: ...at the head be careful not to remove the header node This can happen when qelem is the return value of QUE_next or QUE_prev The following code sample shows how qelem should be verified before calling QUE_remove QUE_Elem qelem get pointer to first element in the queue qelem QUE_head queue scan entire queue for desired element while qelem queue if qelem is the elem we re looking for break qelem QUE_...

Page 380: ...QUE_remove 2 352 Constraints and Calling Context QUE_remove should not be called when qelem is equal to the queue itself See Also QUE_head QUE_insert QUE_next QUE_prev ...

Page 381: ...d in a Tconf script along with their types and default values For details see the RTDX Manager Properties and RTDX Object Properties headings For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Description The RTDX module provides the data types and functions for Sending data from the target to the host S...

Page 382: ...for most targets Set this to simulator if you use a simulator The HS RTDX emulation technology is also available If this property is set incorrectly a message says RTDX target application does not match emulation protocol when you load the program Tconf Name MODE Type EnumString Options JTAG Simulator Example bios RTDX MODE JTAG RTDX Data Segment rtdx_data The memory segment used for buffering tar...

Page 383: ...nf Name comment Type String Example myRtdx comment my RTDX Channel Mode Select output if the RTDX channel handles output from the DSP to the host Select input if the RTDX channel handles input to the DSP from the host Tconf Name channelMode Type EnumString Options input output Example myRtdx channelMode output Examples The rtdx xls example is in the TI_DIR examples hostapps rtdx folder The example...

Page 384: ...lBusy is designed to be used in conjunction with RTDX_readNB The return value indicates whether the specified data channel is currently in use or not If a channel is busy reading the test control flag TC bit of status register 0 STO is set to 1 Otherwise the TC bit is set to O Constraints and Calling Context RTDX_channelBusy cannot be called by an HWI function See Also RTDX_readNB RTDX_channelBusy...

Page 385: ...sed either for input or output but not both The contents of an input or output data channel are unknown to the user A channel can be in one of two states enabled or disabled Channels are initialized as disabled Channels can be enabled or disabled via a User Interface function They can also be enabled or disabled remotely from Code Composer or its COM interface Constraints and Calling Context RTDX_...

Page 386: ... or output but not both The contents of an input or output data channel are unknown to the user A channel can be in one of two states enabled or disabled Channels are initialized as disabled Channels can be enabled or disabled via a User Interface function They can also be enabled or disabled remotely from Code Composer Studio or its OLE interface Constraints and Calling Context RTDX_CreateOutputC...

Page 387: ...ifier for the input data channel Return Value void Reentrant yes Description A call to a disable function causes the specified input channel to be disabled Constraints and Calling Context RTDX_disableInput cannot be called by an HWI function See Also RTDX_disableOutput RTDX_enableInput RTDX_read RTDX_disableInput Disable an input data channel ...

Page 388: ...tput data channel Return Value void Reentrant yes Description A call to a disable function causes the specified data channel to be disabled Constraints and Calling Context RTDX_disableOutput cannot be called by an HWI function See Also RTDX_disableInput RTDX_enableOutput RTDX_read RTDX_disableOutput Disable an output data channel ...

Page 389: ...ata channel ichan Identifier for the input data channel Return Value void Reentrant yes Description A call to an enable function causes the specified data channel to be enabled Constraints and Calling Context RTDX_enableInput cannot be called by an HWI function See Also RTDX_disableInput RTDX_enableOutput RTDX_read RTDX_enableInput Enable an input data channel ...

Page 390: ...utput data channel Return Value void Reentrant yes Description A call to an enable function causes the specified data channel to be enabled Constraints and Calling Context RTDX_enableOutput cannot be called by an HWI function See Also RTDX_disableOutput RTDX_enableInput RTDX_write RTDX_enableOutput Enable an output data channel ...

Page 391: ...ant yes Description The RTDX_isInputEnabled macro tests to see if an input channel is enabled and sets the test control flag TC bit of status register 0 to 1 if the input channel is enabled Otherwise it sets the TC bit to 0 Constraints and Calling Context RTDX_isInputEnabled cannot be called by an HWI function See Also RTDX_isOutputEnabled RTDX_isInputEnabled Return status of the input data channe...

Page 392: ...on The RTDX_isOutputEnabled macro tests to see if an output channel is enabled and sets the test control flag TC bit of status register 0 to 1 if the output channel is enabled Otherwise it sets the TC bit to 0 Constraints and Calling Context RTDX_isOutputEnabled cannot be called by an HWI function See Also RTDX_isInputEnabled RTDX_isOutputEnabled Return status of the output data channel ...

Page 393: ...g or is not enabled When RTDX_read is used the target application notifies the RTDX Host Library that it is ready to receive data and then waits for the RTDX Host Library to write data to the target buffer When the data is received the target application continues execution The specified data is to be written to the specified output data channel provided that channel is enabled On return from the ...

Page 394: ...turns 0 if it cannot post the read request due to lack of space in the RTDX target buffer When the function RTDX_readNB is used the target application notifies the RTDX Host Library that it is ready to receive data but the target application does not wait Execution of the target application continues immediately Use the RTDX_channelBusy and RTDX_sizeofInput functions to determine when the RTDX Hos...

Page 395: ... buffer Reentrant yes Description RTDX_sizeofInput is designed to be used in conjunction with RTDX_readNB after a read operation has completed The function returns the number of sizeof units actually read from the specified data channel into the accumulator register A Constraints and Calling Context RTDX_sizeofInput cannot be called by an HWI function See Also RTDX_readNB RTDX_sizeofInput Return t...

Page 396: ...nt yes Description RTDX_write causes the specified data to be written to the specified output data channel provided that channel is enabled On return from the function the data has been copied out of the specified user buffer and into the RTDX target buffer If the channel is not enabled the write operation is suppressed If the RTDX target buffer is full Failure is returned Constraints and Calling ...

Page 397: ...pedef struct SEM_Obj SEM_Handle handle for semaphore object struct SEM_Attrs semaphore attributes String name printable name SEM_Attrs SEM_ATTRS default attribute values name Configuration Properties The following list shows the properties that can be configured in a Tconf script along with their types and default values For details see the SEM Manager Properties and SEM Object Properties topics F...

Page 398: ...sted or not SEM_pendBinary and SEM_postBinary are for use with binary semaphores The MBX module uses a counting semaphore internally to manage the count of free or full mailbox elements Another example of a counting semaphore is an ISR that might fill multiple buffers of data for consumption by a task After filling each buffer the ISR puts the buffer on a queue and calls SEM_post The task waiting ...

Page 399: ...BJMEMSEG Type Reference Example bios SEM OBJMEMSEG prog get myMEM SEM Object Properties To create a SEM object in a configuration script use the following syntax The Tconf examples that follow assume the object has been created as shown here var mySem bios SEM create mySem The following properties can be set for a SEM object in the SEM Object Properties dialog of the DSP BIOS Configuration Tool or...

Page 400: ...tax count SEM_count sem Parameters SEM_Handle sem semaphore handle Return Value Int count current semaphore count Description SEM_count returns the current value of the semaphore specified by sem SEM_count Get current semaphore count ...

Page 401: ...re of type SEM_Attrs struct SEM_Attrs semaphore attributes String name printable name Default attribute values are contained in the constant SEM_ATTRS which can be assigned to a variable of type SEM_Attrs before calling SEM_create SEM_Attrs SEM_ATTRS default attribute values name SEM_create calls MEM_alloc to dynamically create the object s data structure MEM_alloc must acquire a lock to the memor...

Page 402: ...he memory before proceeding If another task already holds a lock to the memory then there is a context switch Constraints and Calling Context No tasks should be pending on sem when SEM_delete is called SEM_delete cannot be called from a SWI or HWI No check is performed to prevent SEM_delete from being used on a statically created object If a program attempts to delete a semaphore object that was c...

Page 403: ...on SEM_new initializes the semaphore object pointed to by sem with count The function should be used on a statically created semaphore for initialization purposes only No task switch occurs when calling SEM_new Constraints and Calling Context count must be greater than or equal to 0 no tasks should be pending on the semaphore when SEM_new is called See Also QUE_new SEM_new Initialize semaphore obj...

Page 404: ...ent task until SEM_post is called or the timeout expires If timeout is SYS_FOREVER a task stays suspended until SEM_post is called on this semaphore If timeout is 0 SEM_pend returns immediately If timeout expires or timeout is 0 before the semaphore is available SEM_pend returns FALSE Otherwise SEM_pend returns TRUE If timeout is not equal to SYS_FOREVER or 0 the task suspension time can be up to ...

Page 405: ...ple if you have a group of resources that are shared between tasks The APIs for binary and counting semaphores cannot be mixed for a single semaphore If the semaphore count is non zero available SEM_pendBinary sets the count to zero unavailable and returns TRUE If the semaphore count is zero unavailable SEM_pendBinary suspends execution of this task until SEM_post is called or the timeout expires ...

Page 406: ...main function If you need to call this API within a TSK_disable TSK_enable block you must use a timeout of 0 This API should not be called from within an IDL function Doing so prevents analysis tools from gathering run time information See Also SEM_pend SEM_postBinary ...

Page 407: ...lable state The APIs for binary and counting semaphores cannot be mixed for a single semaphore SEM_post readies the first task waiting for the semaphore If no task is waiting SEM_post simply increments the semaphore count and returns A task switch occurs when calling SEM_post if a higher priority task is made ready to run Constraints and Calling Context When called within an HWI the code sequence ...

Page 408: ... which keep track of the number of times the semaphore has been posted This is useful for example if you have a group of resources that are shared between tasks The APIs for binary and counting semaphores cannot be mixed for a single semaphore SEM_postBinary readies the first task in the list if one or more tasks are waiting SEM_postBinary sets the semaphore count to non zero available if no tasks...

Page 409: ... Return Value Void Description SEM_reset resets the semaphore count to count No task switch occurs when calling SEM_reset Constraints and Calling Context count must be greater than or equal to 0 No tasks should be waiting on the semaphore when SEM_reset is called SEM_reset cannot be called by an HWI or a SWI See Also SEM_create SEM_reset Reset semaphore count ...

Page 410: ...back from a stream SIO_segid Memory segment used by a stream SIO_select Select a ready device SIO_staticbuf Acquire static buffer from stream Constants Types and Structures define SIO_STANDARD 0 open stream for standard streaming model define SIO_ISSUERECLAIM 1 open stream for issue reclaim streaming model define SIO_INPUT 0 open for input define SIO_OUTPUT 1 open for output typedef SIO_Handle str...

Page 411: ...OS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Name Type Default OBJMEMSEG Reference prog get DARAM USEISSUERECLAIM Bool false Name Type Default Enum Options comment String add comments here deviceName Reference prog get dev name controlParameter String mode EnumString input output bufSize Int16 0x80 numBufs Int16 2 bufSegId Reference prog get SIO OBJM...

Page 412: ... clients to supply their own buffers to a stream and to get them back in the order that they were submitted The SIO_issue and SIO_reclaim functions also provide a user argument that can be used for passing information between the stream client and the stream devices Both SWI and TSK threads can be used with the SIO module However SWI threads can be used only with the issue reclaim model and only t...

Page 413: ...elect input if this stream is to be used for input to the application program and output if this stream is to be used for output Tconf Name mode Type EnumString Options input output Example mySio mode input Buffer size If this stream uses the Standard model this property controls the size of buffers in MADUs allocated for use by the stream If this stream uses the Issue Reclaim model the stream can...

Page 414: ... 0 TSK threads can be used with either model Tconf Name modelName Type EnumString Options Standard Issue Reclaim Example mySio modelName Standard Allocate Static Buffer s If this property is set to true the configuration allocates stream buffers for the user The SIO_staticbuf function is used to acquire these buffers from the stream When the Standard model is used checking this box causes one buff...

Page 415: ... posts a SWI This function gets called by the class driver see the DIO Adapter in the class driver s callback function This callback function in the class driver usually gets called in the mini driver code as a result of the HWI Tconf Name callBackFxn Type Extern Example mySio callBackFxn prog extern SWI_andnHook argument 0 The first argument to pass to the callback function If the callback functi...

Page 416: ...m Parameters SIO_Handle stream Return Value size_t size Description SIO_bufsize returns the size of the buffers used by stream This API can be used only if the model is SIO_STANDARD See Also SIO_segid SIO_bufsize Return the size of the buffers used by a stream ...

Page 417: ...open to open a device The mode parameter specifies whether the stream is to be used for input SIO_INPUT or output SIO_OUTPUT If the stream is being opened in SIO_STANDARD mode SIO_create allocates buffers of size bufsize for use by the stream Initially these buffers are placed on the device todevice queue for input streams and the device fromdevice queue for output streams If the stream is being o...

Page 418: ...sh Indicates the desired behavior for an output stream when it is deleted If flush is TRUE a call to SIO_delete causes the stream to discard all pending data and return without blocking If flush is FALSE a call to SIO_delete causes the stream to block until all pending data has been processed The default value is FALSE model Indicates the usage model that is to be used with this stream The two usa...

Page 419: ... must acquire a lock to the memory before proceeding If another thread already holds a lock to the memory then there is a context switch The segment from which the object is allocated is set by the Segment for DSP BIOS objects property in the MEM Manager Properties Constraints and Calling Context A stream can only be used by one task simultaneously Catastrophic failure can result if more than one ...

Page 420: ... a control operation to be issued to the device associated with stream cmd and arg are passed directly to the device SIO_ctrl returns SYS_OK if successful and a non zero device dependent error value if unsuccessful Internally SIO_ctrl calls Dxx_ctrl to send control commands to a device Constraints and Calling Context SIO_ctrl cannot be called from an HWI See Also Dxx_ctrl SIO_ctrl Perform a device...

Page 421: ...essed by the stream SIO_delete returns SYS_OK if and only if the operation is successful SIO_delete calls MEM_free to delete a stream MEM_free must acquire a lock to the memory before proceeding If another task already holds a lock to the memory then there is a context switch Internally SIO_delete first calls Dxx_idle to idle the device Then it calls Dxx_close Constraints and Calling Context SIO_d...

Page 422: ...dled as a result of calling SIO_flush In general the interrupt is disabled for the device One of the purposes of this function is to provide synchronization with the external environment SIO_flush returns SYS_OK if and only if the stream is successfully idled Internally SIO_flush calls Dxx_idle and flushes all pending data If a callback was specified in the SIO_Attrs structure used with SIO_create...

Page 423: ... for nmadus As a failure indicator nmadus is the actual error code multiplied by 1 An inconsistency exists between the sizes of buffers in a stream and the return types corresponding to these sizes While all buffer sizes in a stream are of type size_t APIs that return a buffer size return a type of Int The inconsistency is due to a change in stream buffer sizes and the need to retain the return ty...

Page 424: ...y data buffers in stream Internally SIO_get calls Dxx_issue and Dxx_reclaim for the device Constraints and Calling Context The stream must not be created with attrs model set to SIO_ISSUERECLAIM The results of calling SIO_get on a stream created for the issue reclaim streaming model are undefined SIO_get cannot be called from a SWI or HWI This API is callable from the program s main function only ...

Page 425: ...underlying device connected to stream is idled as a result of calling SIO_idle In general the interrupt is disabled for this device If discarding of unrendered output is desired use SIO_flush instead One of the purposes of this function is to provide synchronization with the external environment SIO_idle returns SYS_OK if and only if the stream is successfully idled Internally SIO_idle calls Dxx_i...

Page 426: ...ssue was called In the first case the application is probably issuing more frames than the maximum MADUs allowed for the stream before it reclaims any frames In the second case the failure reveals an underlying device driver or hardware problem If SIO_issue fails SIO_idle should be called for an SIO_INPUT stream and SIO_flush should be called for an SIO_OUTPUT stream before attempting more I O thr...

Page 427: ...ening SIO_reclaim call but over the life of the stream SIO_issue and SIO_reclaim must be called the same number of times At any given point in the life of a stream the number of SIO_issue calls can exceed the number of SIO_reclaim calls by a maximum of nbufs The value of nbufs is determined by the SIO_create call or by setting the Number of buffers property for the object in the configuration Note...

Page 428: ...ate failure SIO_put returns a negative value the actual error code multiplied by 1 An inconsistency exists between the sizes of buffers in a stream and the return types corresponding to these sizes While all buffer sizes in a stream are of type size_t APIs that return a buffer size return a type of Int The inconsistency is due to a change in stream buffer sizes and the need to retain the return ty...

Page 429: ...ream Internally SIO_put calls Dxx_issue and Dxx_reclaim for the device Constraints and Calling Context The stream must not be created with attrs model set to SIO_ISSUERECLAIM The results of calling SIO_put on a stream created for the issue reclaim model are undefined SIO_put cannot be called from a SWI or HWI This API is callable from the program s main function only if the stream s configured tim...

Page 430: ...nt to use SIO_ready to avoid calling SIO_reclaim when it may fail because no buffers are available SIO_ready is similar to SIO_select except that it does not block You can prevent SIO_select from blocking by setting the timeout to zero however SIO_ready is more efficient because SIO_select performs SEM_pend with a timeout of zero SIO_ready simply polls the stream to see if the device is ready See ...

Page 431: ...he buffer is empty If a stream was opened in SIO_INPUT mode SIO_reclaim returns a non empty buffer and nmadus is the number of valid MADUs of data in the buffer If SIO_reclaim is called from a TSK thread it blocks in either mode until a buffer can be returned to the caller or until the stream s timeout attribute expires see SIO_create and it returns a positive number or zero indicating success or ...

Page 432: ... this situation on C55x large model since size_t is the same as unsigned int Since the sign in Int takes up one bit the size_t type contains just one more bit than an Int If you are using the C55x huge model size_t is 32 bits and Int allows positive integers only up to 15 bits SIO_reclaim is used in conjunction with SIO_issue to operate a stream opened in SIO_ISSUERECLAIM mode The SIO_issue call s...

Page 433: ...O_issue when an SIO_reclaim call is made SIO_reclaim returns an error if it is called from a SWI when no buffer is available SIO_reclaim does not block if called from a SWI All frames issued to a stream must be reclaimed before closing the stream SIO_reclaim cannot be called from a HWI This API is callable from the program s main function only if the stream s configured timeout attribute is 0 or i...

Page 434: ...us The returned frame status is valid only if SIO_reclaimx returns successfully If the nmadus value returned is negative the frame status should not be considered accurate Constraints and Calling Context The stream must be created with attrs model set to SIO_ISSUERECLAIM There must be at least one outstanding SIO_issue when an SIO_reclaimx call is made SIO_reclaimx returns an error if it is called...

Page 435: ... segid SIO_segid stream Parameters SIO_Handle stream Return Value Int segid memory segment ID Description SIO_segid returns the identifier of the memory segment that stream uses for buffers See Also SIO_bufsize SIO_segid Return the memory segment used by the stream ...

Page 436: ...p to 1 system clock tick less than timeout due to granularity in system timekeeping The return value is a mask indicating which streams are ready for I O A 1 in bit position j indicates the stream streamtab j is ready SIO_select results in a context switch if no streams are ready for I O Internally SIO_select calls Dxx_ready to determine if the device is ready for an I O operation SIO_ready is sim...

Page 437: ...s of type SIO_Handle returned from prior calls to SIO_create streamtab is an array of streams streamtab i corresponds to bit position i in mask SIO_select cannot be called from an HWI SIO_select can only be called from a SWI if the timeout value is zero See Also Dxx_ready SIO_get SIO_put SIO_ready SIO_reclaim ...

Page 438: ...atibility Because of this inconsistency it is not possible to return the correct buffer size when the actual buffer size exceeds the size of an Int type This issue has the following implications If the actual buffer size is less than equal to the maximum positive Int value 15 bits Check the return value for negative values which indicate errors Positive values reflect the correct size If the actua...

Page 439: ...that are defined statically using Tconf SIO_staticbuf should only be called for static streams whose Allocate Static Buffer s property has been set to true SIO_staticbuf cannot be called after SIO_get SIO_put SIO_issue or SIO_reclaim have been called for the given stream SIO_staticbuf cannot be called from an HWI See Also SIO_get ...

Page 440: ...set and STS_set are not reentrant Configuration Properties The following list shows the properties that can be configured in a Tconf script along with their types and default values For details see the STS Manager Properties and STS Object Properties headings For descriptions of data types see Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Param...

Page 441: ...the following modules by marking the appropriate checkbox You can also set the HWI Object Properties to perform various STS operations on registers addresses or pointers Except for tracing TSK execution your program does not need to include any calls to STS functions in order to gather these statistics The default units for the statistics values are shown in Table 2 6 Table 2 6 Statistics Units fo...

Page 442: ...t routine runs passing the result of CLK_gethtime each time STS_delta subtracts the previous value from the current value The count tracks how many times the interrupt routine was performed The maximum is the largest number of clock counts between interrupt routines The Statistics View also calculates the average number of clock counts Monitor differences between actual values and desired values F...

Page 443: ... operation Figure 2 11 Statistics Accumulation on the Host STS Manager Properties The following global property can be set for the STS module in the STS Manager Properties dialog of the DSP BIOS Configuration Tool or in a Tconf script Object Memory The memory segment that contains STS objects Tconf Name OBJMEMSEG Type Reference Example bios STS OBJMEMSEG prog get myMEM STS Object Properties To cre...

Page 444: ...fault Statistics View presents results in timer interrupt units Tconf Name unitType Type EnumString Options Not time based High resolution time based Low resolution time based Example mySts unitType Not time based host operation The expression evaluated by the host on the data for this object before it is displayed by the Statistics View real time analysis tool The operation can be A x X A x X B A...

Page 445: ...lls STS_add for this STS object The Total field tracks the total of all the amplitudes The Max field holds the largest value passed to this point The Statistics View analysis tool calculates the average amplitude You can count the occurrences of an event by passing a dummy value such as 0 to STS_add and watching the Count field You can view the statistics values with the Statistics View analysis t...

Page 446: ...erence between a variable and a desired value or to benchmark program performance You can benchmark code by using paired calls to STS_set and STS_delta that pass the value provided by CLK_gethtime STS_set sts CLK_gethtime processing to be benchmarked STS_delta sts CLK_gethtime Constraints and Calling Context Before the first call to STS_delta is made the previous value of the STS object should be ...

Page 447: ...e number STS_reset does not modify the value set by STS_set After the Statistics View analysis tool polls statistics data on the target it performs STS_reset internally This keeps the 32 bit total and count values from wrapping back to 0 on the target The host accumulates these values as 64 bit numbers to allow a much larger range than can be stored on the target Example STS_reset sts STS_set sts ...

Page 448: ...t you are measuring you can need to use STS_set to reset the previous value before the next call to STS_delta You can also set a previous value for an STS object in the configuration STS_set changes this value See STS_delta for details on how to use the value you set with STS_set Example This example gathers performance information for the processing between STS_set and STS_delta STS_set sts CLK_g...

Page 449: ...ogram Interface 2 421 STS_set sts baseValue processing STS_delta sts currentValue STS_set sts baseValue processing STS_delta sts currentValue STS_set sts baseValue See Also STS_add STS_delta STS_reset TRC_disable TRC_enable ...

Page 450: ...rn the mailbox value of the SWI when it started running SWI_getpri Return a SWI s priority mask SWI_inc Increment SWI s mailbox value and post the SWI SWI_isSWI Check current thread calling context SWI_or Or mask with value contained in SWI s mailbox and post the SWI SWI_orHook Specialized version of SWI_or for use as hook function for configured DSP BIOS objects Both its arguments are of type Arg...

Page 451: ...Section 1 4 DSP BIOS Tconf Overview page 1 3 Module Configuration Parameters Instance Configuration Parameters Description The SWI module manages software interrupt service routines which are patterned after HWI hardware interrupt service routines DSP BIOS manages four distinct levels of execution threads hardware interrupt service routines software interrupt routines tasks and background idle fun...

Page 452: ...rrupt preempts any lower priority software interrupt currently executing A target program uses an API call to post a SWI object This causes the SWI module to schedule execution of the software interrupt s function When a SWI is posted by an API call the SWI object s function is not executed immediately Instead the function is scheduled for execution DSP BIOS uses the SWI s priority to determine wh...

Page 453: ...swi object which runs the task TSK scheduler A SWI preempts any currently running SWI with a lower priority If two SWIs with the same priority level have been posted the SWI that was posted first runs first HWIs in turn preempt any currently running SWI allowing the target to respond quickly to hardware peripherals Interrupt threads including HWIs and SWIs are all executed using the same stack A c...

Page 454: ...mment Type a comment to identify this SWI object Tconf Name comment Type String Example mySwi comment my SWI function The function to execute 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 ...

Page 455: ... the 16 bit word used to determine if this SWI should be posted Tconf Name mailbox Type Int16 Example mySwi mailbox 7 arg0 arg1 Two arbitrary pointer type Arg arguments to the above configured user function Tconf Name arg0 Type Arg Tconf Name arg1 Type Arg Example mySwi arg0 0 ...

Page 456: ...le if multiple conditions that all be met before a SWI can run you should use a different bit in the mailbox for each condition When a condition is met clear the bit for that condition SWI_andn results in a context switch if the SWI s mailbox becomes zero and the SWI has higher priority than the currently executing thread You specify a SWI s initial mailbox value in the configuration The mailbox v...

Page 457: ...e enabled When called within an HWI the code sequence calling SWI_andn must be either wrapped within an HWI_enter HWI_exit pair or invoked by the HWI dispatcher Example ioReady Void ioReady unsigned int mask clear bits of ready mask SWI_andn copySWI mask See Also SWI_andnHook SWI_dec SWI_getmbox SWI_inc SWI_or SWI_orHook SWI_post SWI_self Mailbox value 3 SWI object Mailbox value 1 Mailbox value 0 ...

Page 458: ...can run you should use a different bit in the mailbox for each condition When a condition is met clear the bit for that condition SWI_andnHook results in a context switch if the SWI s mailbox becomes zero and the SWI has higher priority than the currently executing thread You specify a SWI s initial mailbox value in the configuration The mailbox value is automatically reset when the SWI executes C...

Page 459: ...he SWI object s attributes are specified through a structure of type SWI_attrs defined as follows struct SWI_Attrs SWI_Fxn fxn Arg arg0 Arg arg1 Int priority Uns mailbox If attrs is NULL the new SWI object is assigned the following default attributes SWI_Attrs SWI_ATTRS Default attribute values SWI_Fxn FXN_F_nop SWI function 0 arg0 0 arg1 1 priority 0 mailbox The fxn attribute which is the address...

Page 460: ...e the object s data structure MEM_alloc must acquire a lock to the memory before proceeding If another thread already holds a lock to the memory then there is a context switch The segment from which the object is allocated is described by the DSP BIOS objects property in the MEM Module page 2 205 Constraints and Calling Context SWI_create cannot be called from a SWI or HWI The fxn attribute cannot...

Page 461: ...value in the configuration The mailbox value is automatically reset when the SWI executes SWI_dec results in a context switch if the SWI s mailbox becomes zero and the SWI has higher priority than the currently executing thread Constraints and Calling Context If this macro API is invoked outside the context of an HWI interrupts must be enabled When called within an HWI the code sequence calling SW...

Page 462: ... lock to the memory then there is a context switch Constraints and Calling Context swi cannot be the currently executing SWI object SWI_self SWI_delete cannot be called from a SWI or HWI SWI_delete must not be used to delete a statically created SWI object No check is performed to prevent SWI_delete from being used on a statically created object If a program attempts to delete a SWI object that wa...

Page 463: ...SWIs and have them performed in priority order See the following example SWI_disable calls can be nested The number of nesting levels is stored internally SWI handling is not reenabled until SWI_enable has been called as many times as SWI_disable Constraints and Calling Context The calls to HWI_enter and HWI_exit required in any HWIs that schedule SWIs automatically disable and reenable SWI handli...

Page 464: ...ed until SWI_enable has been called as many times as SWI_disable SWI_enable results in a context switch if a higher priority SWI is ready to run Constraints and Calling Context The calls to HWI_enter and HWI_exit are required in any HWI that schedules SWIs They automatically disable and reenable SWI handling You should not call SWI_disable or SWI_enable within a HWI SWI_enable cannot be called fro...

Page 465: ...fied through a structure of type SWI_attrs defined as follows struct SWI_Attrs SWI_Fxn fxn Arg arg0 Arg arg1 Int priority Uns mailbox The fxn attribute which is the address of the SWI function serves as the entry point of the software interrupt service routine The arg0 and arg1 attributes specify the arguments passed to the SWI function fxn The priority attribute specifies the SWI object s executi...

Page 466: ... extern SWI_Handle swi SWI_Attrs attrs SWI_getattrs swi attrs attrs priority 5 SWI_setattrs swi attrs Constraints and Calling Context SWI_getattrs cannot be called from a SWI or HWI The attrs parameter cannot be NULL See Also SWI_create SWI_delete SWI_setattrs ...

Page 467: ...lled from with the context of a SWI the value returned by SWI_getmbox is zero if the SWI was posted by a call to SWI_andn SWI_andnHook or SWI_dec Therefore SWI_getmbox provides relevant information only if the SWI was posted by a call to SWI_inc SWI_or SWI_orHook or SWI_post Constraints and Calling Context SWI_getmbox cannot be called from the context of an HWI or TSK SWI_getmbox cannot be called ...

Page 468: ...iority mask of swi Reentrant yes Description SWI_getpri returns the priority mask of the SWI passed in as the argument Example Get the priority key of swi1 key SWI_getpri swi1 Get the priorities of swi1 and swi3 key SWI_getpri swi1 SWI_getpri swi3 See Also SWI_raisepri SWI_restorepri SWI_getpri Return a SWI s priority mask ...

Page 469: ... SWI_getmbox to find out how many times this SWI has been posted since the last time it was executed You specify a SWI s initial mailbox value in the configuration The mailbox value is automatically reset when the SWI executes To get the mailbox value use SWI_getmbox SWI_inc results in a context switch if the SWI is higher priority than the currently executing thread Constraints and Calling Contex...

Page 470: ...ntext of a SWI or PRD function This applies no matter whether the SWI was posted by an HWI TSK or IDL thread This macro returns FALSE in all other contexts In previous versions of DSP BIOS calling SWI_isSWI from a task switch hook resulted in TRUE This is no longer the case task switch hooks are identified as part of the TSK context See Also HWI_isHWI TSK_isTSK SWI_isSWI Check to see if called in ...

Page 471: ...or example you might use SWI_or to post a SWI if any of three events should cause a SWI to be executed but you want the SWI s function to be able to tell which event occurred Each event would correspond to a different bit in the mailbox SWI_or results in a context switch if the SWI is higher priority than the currently executing thread Note Use the specialized version SWI_orHook when SWI_or functi...

Page 472: ...tically reset when the SWI executes To get the mailbox value use SWI_getmbox For example you might use SWI_orHook to post a SWI if any of three events should cause a SWI to be executed but you want the SWI s function to be able to tell which event occurred Each event would correspond to a different bit in the mailbox SWI_orHook results in a context switch if the SWI is higher priority than the cur...

Page 473: ...tion property of a PRD object and the name of the SWI object you want to post its function as the arg0 property SWI_post results in a context switch if the SWI is higher priority than the currently executing thread Constraints and Calling Context If this macro API is invoked outside the context of an HWI interrupts must be enabled When called within an HWI the code sequence calling SWI_post must b...

Page 474: ... to the shared resource A call to SWI_raisepri not followed by a SWI_restorepri keeps the SWI s priority for the rest of the processing at the raised level A SWI_post of the SWI posts the SWI at its original priority level A SWI object s execution priority must range from 0 to 14 The highest level is SWI_MAXPRI 14 The lowest is SWI_MINPRI 0 Priority zero 0 is reserved for the KNL_swi object which ...

Page 475: ...ovide a mutual exclusion mechanism without disabling all SWIs SWI_raisepri should be called right before the shared resource is referenced and SWI_restorepri should be called after the reference to the shared resource Constraints and Calling Context SWI_restorepri cannot be called from an HWI or TSK level SWI_restorepri cannot be called from the program s main function Example raise priority to th...

Page 476: ...ns the address of the currently executing SWI Constraints and Calling Context SWI_self cannot be called from an HWI or TSK level SWI_self cannot be called from the program s main function Example You can use SWI_self if you want a SWI to repost itself SWI_post SWI_self See Also SWI_andn SWI_getmbox SWI_post SWI_self Return address of currently executing SWI object ...

Page 477: ..._attrs defined as follows struct SWI_Attrs SWI_Fxn fxn Arg arg0 Arg arg1 Int priority Uns mailbox The fxn attribute which is the address of the swi function serves as the entry point of the software interrupt service routine The arg0 and arg1 attributes specify the arguments passed to the swi function fxn The priority attribute specifies the SWI object s execution priority and must range from 1 to...

Page 478: ...priority 5 SWI_setattrs swi attrs Constraints and Calling Context SWI_setattrs must not be used to set the attributes of a SWI that is preempted or is ready to run The fxn attribute cannot be NULL The priority attribute must be less than or equal to 14 and greater than or equal to 1 See Also SWI_create SWI_delete SWI_getattrs ...

Page 479: ...ine SYS_ENODEV 3 dev driver not found define SYS_EBUSY 4 device driver busy define SYS_EINVAL 5 invalid parameter define SYS_EBADIO 6 I O failure define SYS_EMODE 7 bad mode for driver define SYS_EDOMAIN 8 domain error define SYS_ETIMEOUT 9 call timed out define SYS_EE0F 10 end of file define SYS_EDEAD 11 deleted obj define SYS_EBADOBJ 12 invalid object define SYS_ENOTIMPL 13 action not implemente...

Page 480: ...ctions SYS Manager Properties The following global properties can be set for the SYS module in the SYS Manager Properties dialog of the DSP BIOS Configuration Tool or in a Tconf script Trace Buffer Size The size of the buffer that contains system trace information This system trace buffer can be viewed only by looking for the SYS_PUTCBEG symbol in the Code Composer Studio memory view For example b...

Page 481: ...ist ap Tconf Name ERRORFXN Type Extern Example bios SYS ERRORFXN prog extern myError Exit Function The function to run when the application exits by calling SYS_exit The default function is UTL_halt which loops forever with interrupts disabled and prevents other processing The prototype for this function should be Void myExit Int status Tconf Name EXITFXN Type Extern Example bios SYS EXITFXN prog ...

Page 482: ...d to SYS_abort Abort_function format vargs The function bound to Abort function can elect to pass the format and vargs parameters directly to SYS_vprintf or SYS_vsprintf prior to terminating program execution The default Abort function for the SYS manager is _UTL_doAbort which logs an error message and calls UTL _halt which is defined in the boot c file The UTL_halt function performs an infinite l...

Page 483: ...il empty and calls each function as follows where status is the parameter passed to SYS_exit handler status SYS_atexit returns TRUE if handler has been successfully stacked FALSE if the internal stack is full The handlers on the stack are called only if either of the following happens SYS_exit is called All tasks for which the Don t shut down system while this task is still running property is TRU...

Page 484: ...eturns The default function can be replaced with your own error function by setting the SYS ERRORFXN configuration property The default error function or an alternate configured error function is called as follows where vargs is of type va_list a void pointer which can be interpreted as an argument list and represents the sequence of arg parameters originally passed to SYS_error Error_function s e...

Page 485: ...d to the configuration parameter Exit function passing on its original status parameter handlerN status handler2 status handler1 status Exit_function status The default Exit function for the SYS manager is UTL_halt which performs an infinite loop with all processor interrupts disabled Constraints and Calling Context If the function bound to Exit function or any of the handler functions is not reen...

Page 486: ...h a conversion character The conversion characters recognized by SYS_printf are limited to the characters shown in Table 2 7 Table 2 7 Conversion Characters Recognized by SYS_printf Note that the f conversion character is supported only on devices that have a native floating point type for example the C67x Between the and the conversion character the following symbols or specifiers contained in sq...

Page 487: ... replaced by a va_list on which the standard C macro va_start has already been applied SYS_sprintf and SYS_vsprintf are counterparts of SYS_printf and SYS_vprintf respectively in which output is placed in a specified buffer Both SYS_printf and SYS_vprintf internally call the function SYS_putchar to output individual characters via the Putc function configured in the SYS Manager Properties The defa...

Page 488: ...nctions to reduce code size and execution time Conversion specifications begin with a and end with a conversion character The conversion characters recognized by SYS_sprintf are limited to the characters in Table 2 8 Table 2 8 Conversion Characters Recognized by SYS_sprintf Note that the f conversion character is supported only on devices that have a native floating point type for example the C67x...

Page 489: ...precede d u o and x if the corresponding argument is a long integer SYS_vprintf is equivalent to SYS_printf except that the optional set of arguments is replaced by a va_list on which the standard C macro va_start has already been applied SYS_sprintf and SYS_vsprintf are counterparts of SYS_printf and SYS_vprintf respectively in which output is placed in a specified buffer Both SYS_printf and SYS_...

Page 490: ...o reduce code size and execution time Conversion specifications begin with a and end with a conversion character The conversion characters recognized by SYS_vprintf are limited to the characters in Table 2 9 Table 2 9 Conversion Characters Recognized by SYS_vprintf Note that the f conversion character is supported only on devices that have a native floating point type for example the C67x SYS_vpri...

Page 491: ...rintf is equivalent to SYS_printf except that the optional set of arguments is replaced by a va_list on which the standard C macro va_start has already been applied SYS_sprintf and SYS_vsprintf are counterparts of SYS_printf and SYS_vprintf respectively in which output is placed in a specified buffer Both SYS_printf and SYS_vprintf internally call the function SYS_putchar to output individual char...

Page 492: ...odule functions to reduce code size and execution time Conversion specifications begin with a and end with a conversion character The conversion characters recognized by SYS_vsprintf are limited to the characters in Table 2 10 Table 2 10 Conversion Characters Recognized by SYS_vsprintf Note that the f conversion character is supported only on devices that have a native floating point type for exam...

Page 493: ... precede d u o and x if the corresponding argument is a long integer SYS_vprintf is equivalent to SYS_printf except that the optional set of arguments is replaced by a va_list on which the standard C macro va_start has already been applied SYS_sprintf and SYS_vsprintf are counterparts of SYS_printf and SYS_vprintf respectively in which output is placed in a specified buffer Both SYS_printf and SYS...

Page 494: ...termination The default Putc function for the SYS manager is _UTL_doPutc which writes a character to the system trace buffer The size and memory segment for the system trace buffer can be set in the SYS Manager Properties This system trace buffer can be viewed only by looking for the SYS_PUTCBEG symbol in the Code Composer Studio memory view SYS_putchar is also used internally by SYS_printf and SY...

Page 495: ...I Gather statistics on monitored values within HWIs off TRC_STSPIP Count number of frames read from or written to data pipe off TRC_STSPRD Gather statistics on number of ticks elapsed during execution off TRC_STSSWI Gather statistics on length of SWI execution off TRC_STSTSK Gather statistics on length of TSK execution Statistics are gathered from the time TSK is made ready to run until the applic...

Page 496: ... not need to enable tracing for messages written with LOG_printf or LOG_event and statistics added with STS_add or STS_delta Your program can call the TRC_enable and TRC_disable operations to explicitly start and stop event logging or statistics accumulation in response to conditions encountered during real time execution This enables you to preserve the specific log or statistics information you ...

Page 497: ... following C code would disable tracing of statistics for software interrupts and periodic functions TRC_disable TRC_LOGSWI TRC_LOGPRD Internally DSP BIOS uses a bitwise AND NOT operation to disable multiple trace types For example you might want to use TRC_disable with a circular log and disable tracing when an unwanted condition occurs This allows test equipment to retrieve the log events that h...

Page 498: ...ng C code would enable tracing of statistics for software interrupts and periodic functions TRC_enable TRC_STSSWI TRC_STSPRD Internally DSP BIOS uses a bitwise OR operation to enable multiple trace types For example you might want to use TRC_enable with a fixed log to enable tracing when a specific condition occurs This allows test equipment to retrieve the log events that happened just after this...

Page 499: ...s 0 if statistics tracing for the PRD class is enabled result TRC_query TRC_STSPRD The following C code returns 0 if both logging and statistics tracing for the SWI class are enabled result TRC_query TRC_LOGSWI TRC_STSSWI Note that TRC_query does not return 0 unless the bits you are querying and the TRC_GBLHOST and TRC_GBLTARG bits are set TRC_query returns non zero if either TRC_GBLHOST or TRC_GB...

Page 500: ...bject TSK_isTSK Check current thread calling context TSK_itick Advance system alarm clock interrupt only TSK_self Get handle of currently executing task TSK_setenv Set task environment TSK_seterr Set task error number TSK_setpri Set a task s 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 Advanc...

Page 501: ...LEPRI 0 used for idle task Int TSK_MINPRI 1 minimum execution priority Int TSK_MAXPRI 15 maximum execution priority Int TSK_STACKSTAMP TSK_Attrs TSK_ATTRS default attribute values TSK PRIORITY priority NULL stack TSK STACKSIZE stacksize ifdef _55_ TSK SYSSTACKSIZE system stacksize in MADUs endif TSK STACKSEG stackseg NULL environ name TRUE exitflag TRUE initstackflag enum TSK_Mode task execution m...

Page 502: ...16 1024 SYSSTACKSIZE Int16 256 STACKSEG Reference prog get DARAM PRIORITY EnumInt 1 1 to 15 DRIVETSKTICK EnumString PRD User CREATEFXN Extern prog extern FXN_F_nop DELETEFXN Extern prog extern FXN_F_nop EXITFXN Extern prog extern FXN_F_nop CALLSWITCHFXN Bool false SWITCHFXN Extern prog extern FXN_F_nop CALLREADYFXN Bool false READYFXN Extern prog extern FXN_F_nop Name Type Default Enum Options com...

Page 503: ...les of scope defined for C functions Each task is in one of four modes of execution at any point in time running ready blocked or terminated By design there is always one and only one task currently running even if it is a dummy idle task managed internally by TSK The current task can be suspended from execution by calling certain TSK functions as well as functions provided by other modules like t...

Page 504: ...w task becomes the TSK_RUNNING task The Switch function gives the application access to both the current and next task handles at task switch time The function should use these argument types Void mySwitchFxn TSK_Handle currTask TSK_Handle nextTask This function can be used to save restore additional task context for example external hardware registers to check for task stack overflow to monitor t...

Page 505: ...pe Bool Example bios TSK ENABLETSK true Object Memory The memory segment that contains the TSK objects created with Tconf Tconf Name OBJMEMSEG Type Reference Example bios TSK OBJMEMSEG prog get myMEM Default stack size The default size of the stack in MADUs used by tasks You can override this value for an individual task you create with Tconf or TSK_create The estimated minimum task size is shown ...

Page 506: ...hose created dynamically using TSK_create If you are using Tconf do not add an underscore before the function name Tconf adds the underscore needed to call a C function from assembly internally The TSK_create topic describes the Create function Tconf Name CREATEFXN Type Extern Example bios TSK CREATEFXN prog extern tskCreate Delete function The name of a function to call when any task is deleted a...

Page 507: ...e following syntax The Tconf examples that follow assume the object has been created as shown here var myTsk bios TSK create myTsk The following properties can be set for a TSK object in the TSK Object Properties dialog of the DSP BIOS Configuration Tool or in a Tconf script General tab comment Type a comment to identify this TSK object Tconf Name comment Type String Example myTsk comment my TSK A...

Page 508: ... pointer and system stack pointer share the same register for their upper bits Tconf Name sysStackSize Type Int16 Example myTsk sysStackSize 256 Stack Memory Segment If you set the Automatically allocate stack property to true specify the memory segment to contain the stack space for this task Tconf Name stackMemSeg Type Reference Example myTsk stackMemSeg prog get myMEM Priority The priority leve...

Page 509: ...envPointer Type Arg Example myTsk envPointer 0 Don t shut down system while this task is still running Check this box if you do not want the application to be able to end if this task is still running The application can still abort For example you might clear this box for a monitor task that collects data whenever all other tasks are blocked The application does not need to explicitly shut down t...

Page 510: ...o TSK_create Statically configured tasks always initialize the stack You can call TSK_checkstacks directly from your application For example you can check the current task s stack integrity at any time with a call like the following TSK_checkstacks TSK_self TSK_self However it is more typical to call TSK_checkstacks in the task Switch function specified for the TSK manager in your configuration fi...

Page 511: ...ed This includes tasks that are created statically and those created dynamically using TSK_create The default Create function is a no op function For TSK objects created statically the Create function is called during the BIOS_start portion of the program startup process which runs after the main function and before the program drops into the idle loop For TSK objects created dynamically the Creat...

Page 512: ...e default configuration You should not use a priority of 0 for any other tasks The stack attribute specifies a pre allocated block of stacksize MADUs to be used for the task s private stack this attribute defaults to NULL in which case the task s stack is automatically allocated using MEM_alloc from the memory segment given by the stackseg attribute If you specify a pre allocated stack for C55x th...

Page 513: ...both in cases where the stack attribute is NULL stack is allocated by TSK_create and where the stack attribute is used to specify a pre allocated stack If your application does not call TSK_checkstacks you can reduce the time consumed by TSK_create by setting this attribute to FALSE All default attribute values are contained in the constant TSK_ATTRS which can be assigned to a variable of type TSK...

Page 514: ...kseg attribute must identify a valid memory segment You can reduce the size of your application program by creating objects with Tconf rather than using the XXX_create functions See Also MEM_alloc SYS_error TSK_delete TSK_exit ...

Page 515: ... be called from the Delete function DSP BIOS passes the task handle of the task being deleted to your Delete function Your Delete function declaration should be similar to the following Void myDeleteFxn TSK_Handle task TSK_delete calls MEM_free to delete the TSK object MEM_free must acquire a lock to the memory before proceeding If another task already holds a lock to the memory then there is a co...

Page 516: ...cs because TSK functions typically run an infinite loop that blocks when waiting for other threads In contrast HWI and SWI functions run to completion without blocking Because of this difference DSP BIOS allows programs to identify the beginning of a TSK function s processing loop by calling TSK_settime and the end of the loop by calling TSK_deltatime For example if a task waits for data and then ...

Page 517: ... BIOS sets the task s statistics object with the current time when the semaphore becomes available and the task is made ready to run Thus the call to TSK_deltatime effectively measures the processing time of the task Constraints and Calling Context The results of calls to TSK_deltatime and TSK_settime are displayed in the Statistics View only if Enable TSK accumulators is selected in the RTA Contr...

Page 518: ...sted Since TSK_disable can prohibit ready tasks of higher priority from running it should not be used as a general means of mutual exclusion SEM Module semaphores should be used for mutual exclusion when possible Constraints and Calling Context Do not call any function that can cause the current task to block within a TSK_disable TSK_enable block For example SEM_pend if timeout is non zero TSK_sle...

Page 519: ...ater than the currently executing task Constraints and Calling Context Do not call any function that can cause the current task to block within a TSK_disable TSK_enable block For example SEM_pend if timeout is non zero TSK_sleep TSK_yield and MEM_alloc can all cause blocking For a complete list see Section A 1 Function Callability Table page A 2 TSK_enable cannot be called from a SWI or HWI TSK_en...

Page 520: ...cation wide Exit function that runs whenever a task is terminated The default Exit function is a no op function The Exit function is called before the task has been blocked and marked TSK_TERMINATED Any DSP BIOS function can be called from an Exit function Calling TSK_self within an Exit function returns the task being exited Your Exit function declaration should be similar to the following Void m...

Page 521: ...v returns the environment pointer of the specified task The environment pointer environ references an arbitrary application defined data structure If your program uses multiple HOOK objects HOOK_getenv allows you to get environment pointers you have set for a particular HOOK and TSK object combination See Also HOOK_getenv HOOK_setenv TSK_setenv TSK_seterr TSK_setpri TSK_getenv Get task environment...

Page 522: ...le Return Value Int errno error number Description Each task carries a task specific error number This number is initially SYS_OK but it can be changed by TSK_seterr TSK_geterr returns the current value of this number See Also SYS_error TSK_setenv TSK_seterr TSK_setpri TSK_geterr Get task error number ...

Page 523: ...SK_getname returns the task s name For tasks created with Tconf the name is available to this function only if the Allocate Task Name on Target property is set to true for this task For tasks created with TSK_create TSK_getname returns the attrs name field value or an empty string if this attribute was not specified See Also TSK_setenv TSK_seterr TSK_setpri TSK_getname Get task name ...

Page 524: ...x priority TSK_getpri task Parameters TSK_Handle task task object handle Return Value Int priority task priority Description TSK_getpri returns the priority of task See Also TSK_setenv TSK_seterr TSK_setpri TSK_getpri Get task priority ...

Page 525: ...t handle Return Value STS_Handle sts statistics object handle Description This function provides access to the task s internal STS object For example you can want the program to check the maximum value to see if it has exceeded some value See Also TSK_deltatime TSK_settime TSK_getsts Get the handle of the task s STS object ...

Page 526: ...us TSK_isTSK returns TRUE when it is invoked within a task thread main or a task switch hook In previous versions of DSP BIOS calling the context checking functions from main resulted in TRUE for HWI_isHWI And calling the context checking functions from a task switch hook resulted in TRUE for SWI_isSWI This is no longer the case they are identified as part of the TSK context In applications that c...

Page 527: ... whose timeout intervals have expired Constraints and Calling Context TSK_itick cannot be called by a TSK object TSK_itick cannot be called from the program s main function When called within an HWI the code sequence calling TSK_itick must be either wrapped within an HWI_enter HWI_exit pair or invoked by the HWI dispatcher See Also SEM_pend TSK_sleep TSK_tick TSK_itick Advance the system alarm clo...

Page 528: ...bject Description TSK_self returns the object handle for the currently executing task This function is useful when inspecting the object or when the current task changes its own priority through TSK_setpri No task switch occurs when calling TSK_self See Also TSK_setpri TSK_self Returns handle to the currently executing task ...

Page 529: ... Description TSK_setenv sets the task environment pointer to environ The environment pointer environ references an arbitrary application defined data structure If your program uses multiple HOOK objects HOOK_setenv allows you to set individual environment pointers for each HOOK and TSK object combination See Also HOOK_getenv HOOK_setenv TSK_getenv TSK_geterr TSK_setenv Set task environment ...

Page 530: ...dle Int errno error number Return Value Void Description Each task carries a task specific error number This number is initially SYS_OK but can be changed to errno by calling TSK_seterr TSK_geterr returns the current value of this number See Also TSK_getenv TSK_geterr TSK_seterr Set task error number ...

Page 531: ... than 0 the task is barred from further execution until its priority is raised at a later time by another task if newpri equals TSK_MAXPRI execution of the task effectively locks out all other program activity except for the handling of interrupts The current task can change its own priority and possibly preempt its execution by passing the output of TSK_self as the value of the task parameter A c...

Page 532: ...run TSK statistics are handled differently than other statistics because TSK functions typically run an infinite loop that blocks when waiting for other threads In contrast HWI and SWI functions run to completion without blocking Because of this difference DSP BIOS allows programs to identify the beginning of a TSK function s processing loop by calling TSK_settime and the end of the loop by callin...

Page 533: ...semaphore becomes available and the task is made ready to run Thus the call to TSK_deltatime effectively measures the processing time of the task Constraints and Calling Context TSK_settime cannot be called from the program s main function The results of calls to TSK_deltatime and TSK_settime are displayed in the Statistics View only if Enable TSK accumulators is selected within the RTA Control Pa...

Page 534: ... system timekeeping After the specified period of time has elapsed the task reverts to the TSK_READY mode and is scheduled for execution A task switch always occurs when calling TSK_sleep if nticks 0 Constraints and Calling Context TSK_sleep cannot be called from a SWI or HWI or within a TSK_disable TSK_enable block TSK_sleep cannot be called from the program s main function TSK_sleep should not b...

Page 535: ...d ifdef _55_ size_t sysused task system stack used endif When a task is preempted by a software or hardware interrupt the task execution mode returned for that task by TSK_stat is still TSK_RUNNING because the task runs when the preemption ends The current task can inquire about itself by passing the output of TSK_self as the first argument to TSK_stat However the task stack pointer sp in the TSK_...

Page 536: ...ter is particularly useful for testing timeouts in a controlled environment A task switch occurs when calling TSK_tick if the priority of any of the readied tasks is greater than the priority of the currently executing task Constraints and Calling Context When called within an HWI the code sequence calling TSK_tick must be either wrapped within an HWI_enter HWI_exit pair or invoked by the HWI disp...

Page 537: ...ote that since the system clock is usually updated asynchronously via TSK_itick or TSK_tick curtime can lag behind the actual system time This lag can be even greater if a higher priority task preempts the current task between the call to TSK_time and when its return value is used Nevertheless TSK_time is useful for getting a rough idea of the current system time TSK_time Return current value of s...

Page 538: ...ask without the need for a call to TSK_yield If only lower priority tasks are ready to run when you call TSK_yield the current task continues to run Control does not pass to a lower priority task Constraints and Calling Context When called within an HWI the code sequence calling TSK_yield must be either wrapped within an HWI_enter HWI_exit pair or invoked by the HWI dispatcher TSK_yield cannot be ...

Page 539: ...r arg include stdlib h int atexit void fcn void void calloc size_t nobj size_t size void exit int status void free void p char getenv char name void malloc size_t size void realloc void p size_t size Description The DSP BIOS library contains some C standard library functions which supersede the library functions bundled with the C compiler These functions follow the ANSI C specification for parame...

Page 540: ...t should not be called from a SWI or an HWI function see LCK_pend on page 2 180 To determine whether a particular RTS function uses LCK_pend refer to the source code for that function shipped with Code Composer Studio The following table shows some of the RTS functions that call LCK_pend in certain versions of Code Composer Studio The C new operator calls malloc which in turn calls LCK_pend As a r...

Page 541: ...ppendix A Function Callability and Error Tables This appendix provides tables describing TMS320C55x errors and function callability A 1 Function Callability Table A 2 A 2 DSP BIOS Error Codes A 11 Topic Page ...

Page 542: ...s Callableby HWIs Possible Context Switch Callable from main ATM_andi Yes Yes Yes No Yes ATM_andu Yes Yes Yes No Yes ATM_cleari Yes Yes Yes No Yes ATM_clearu Yes Yes Yes No Yes ATM_deci Yes Yes Yes No Yes ATM_decu Yes Yes Yes No Yes ATM_inci Yes Yes Yes No Yes ATM_incu Yes Yes Yes No Yes ATM_ori Yes Yes Yes No Yes ATM_oru Yes Yes Yes No Yes ATM_seti Yes Yes Yes No Yes ATM_setu Yes Yes Yes No Yes B...

Page 543: ...es Yes No No DEV_createDevice Yes No No Yes Yes DEV_deleteDevice Yes No No Yes Yes DEV_match Yes Yes Yes No Yes GBL_getClkin Yes Yes Yes No Yes GBL_getFrequency Yes Yes Yes No Yes GBL_getProcId Yes Yes Yes No Yes GBL_getVersion Yes Yes Yes No Yes GBL_setFrequency No No No No Yes GBL_setProcId No No No No No GIO_abort Yes No No Yes No GIO_control Yes No No Yes Yes GIO_create Yes No No No Yes GIO_de...

Page 544: ... Yes No Yes LOG_event Yes Yes Yes No Yes LOG_message Yes Yes Yes No Yes LOG_printf Yes Yes Yes No Yes LOG_reset Yes Yes Yes No Yes MBX_create Yes No No Yes Yes MBX_delete Yes No No Yes No MBX_pend Yes Yes Yes Yes No MBX_post Yes Yes Yes Yes Yes MEM_alloc Yes No No Yes Yes MEM_calloc Yes No No Yes Yes MEM_define Yes No No Yes Yes MEM_free Yes No No Yes Yes MEM_getBaseAddress Yes Yes Yes No Yes MEM_...

Page 545: ...orHandler Yes Yes Yes No Yes MSGQ_setMsgId Yes Yes Yes No Yes MSGQ_setSrcQueue Yes Yes Yes No Yes PIP_alloc Yes Yes Yes Yes Yes PIP_free Yes Yes Yes Yes Yes PIP_get Yes Yes Yes Yes Yes PIP_getReaderAddr Yes Yes Yes No Yes PIP_getReaderNumFrames Yes Yes Yes No Yes PIP_getReaderSize Yes Yes Yes No Yes PIP_getWriterAddr Yes Yes Yes No Yes PIP_getWriterNumFrames Yes Yes Yes No Yes PIP_getWriterSize Ye...

Page 546: ... QUE_create Yes No No Yes Yes QUE_delete Yes No No Yes Yes QUE_dequeue Yes Yes Yes No Yes QUE_empty Yes Yes Yes No Yes QUE_enqueue Yes Yes Yes No Yes QUE_get Yes Yes Yes No Yes QUE_head Yes Yes Yes No Yes QUE_insert Yes Yes Yes No Yes QUE_new Yes Yes Yes No Yes QUE_next Yes Yes Yes No Yes QUE_prev Yes Yes Yes No Yes QUE_put Yes Yes Yes No Yes QUE_remove Yes Yes Yes No Yes RTDX_channelBusy Yes Yes ...

Page 547: ...bufsize Yes Yes Yes No Yes SIO_create Yes No No Yes Yes SIO_ctrl Yes Yes No No Yes SIO_delete Yes No No Yes Yes SIO_flush Yes Yes No No No SIO_get Yes No No Yes Yes SIO_idle Yes Yes No Yes No SIO_issue Yes Yes No No Yes SIO_put Yes No No Yes Yes SIO_ready Yes Yes Yes No No SIO_reclaim Yes Yes No Yes Yes SIO_reclaimx Yes Yes No Yes Yes SIO_segid Yes Yes Yes No Yes SIO_select Yes Yes No Yes No SIO_s...

Page 548: ... No No No SWI_setattrs Yes Yes Yes No Yes SYS_abort Yes Yes Yes No Yes SYS_atexit Yes Yes Yes No Yes SYS_error Yes Yes Yes No Yes SYS_exit Yes Yes Yes No Yes SYS_printf Yes Yes Yes No Yes SYS_putchar Yes Yes Yes No Yes SYS_sprintf Yes Yes Yes No Yes SYS_vprintf Yes Yes Yes No Yes SYS_vsprintf Yes Yes Yes No Yes TRC_disable Yes Yes Yes No Yes TRC_enable Yes Yes Yes No Yes TRC_query Yes Yes Yes No Y...

Page 549: ...No Yes TSK_seterr Yes Yes Yes No Yes TSK_setpri Yes Yes Yes Yes Yes TSK_settime Yes Yes Yes No No TSK_sleep Yes No No Yes No TSK_stat Yes Yes Yes No Yes TSK_tick Yes Yes Yes Yes No TSK_time Yes Yes Yes No No TSK_yield Yes Yes Yes Yes No Function Callable by TSKs Callable by SWIs Callableby HWIs Possible Context Switch Callable from main Function Callable by TSKs Callable by SWIs Callableby HWIs Po...

Page 550: ... std h and stdlib h functions page 2 511 for more information srand Yes No No Yes strftime Yes No No Yes vfprintf Yes No No Yes vprintf Yes No No Yes vsprintf Yes No No Yes Function Callable by TSKs Callable by SWIs Callableby HWIs Possible Context Switch ...

Page 551: ... the I O operation SYS_EMODE 7 SYS_EMODE invalid mode An attempt was made to open a device in an improper mode e g an attempt to open an input device for output SYS_EDOMAIN 8 SYS_EDOMAIN domain error Used by SPOX MATH when type of operation does not match vector or filter type SYS_ETIMEOUT 9 SYS_ETIMEOUT timeout error Used by device drivers to indicate that reclaim timed out SYS_EEOF 10 SYS_EEOF e...

Page 552: ...A 12 ...

Page 553: ...s appendix provides tables describing the TMS320C55x register conventions in terms of preservation across multi threaded context switching and preconditions B 1 Overview B 2 B 2 Register Conventions B 2 B 3 Status Register Conventions B 4 Topic Page ...

Page 554: ...served in the task s execution context during a synchronous context switch This is because it is assumed that the function that invoked the task switch has already saved its parent register set Task context switches that result from preemption by an interrupt will preserve the entire processor state so that execution can safely resume at the instruction following the interrupted instruction G Glob...

Page 555: ...return IFR0 IFR1 Interrupt Flag Registers G Initialized by DSP BIOS at boot time untouched thereafter IVPD IVPH Interrupt Vector Table Pointers G Initialized by DSP BIOS at boot time untouched thereafter PC Program Counter H T RPTC Single Repeat Counter H RSA0 RSA1 Block repeat start address registers H REA0 REA1 Block repeat end address registers H RETA Return Address Register H T X SP Stack Poin...

Page 556: ... does not manipulate these bits nor depend on their values B n BIOS DSP BIOS sets the bit s to the value n at boot time and before entering a HWI that uses the HWI dispatcher or HWI_enter HWI_exit Proper operation of DSP BIOS is not guaranteed if an application changes these status bit settings P Propagated These bits are not restored upon returning from an interrupt or task context switch Instead...

Page 557: ...ter int ST2 ARMS AR mode switch B 1 Restored after int DBGM Debug mode X Restored after int EALLOW Emulation access enable X Restored after int RDM Rounding mode B 0 Restored after int CDPLC CDP linear circular configuration B 0 Restored after int AR0 7LC ARn linear circular configuration B 0 Restored after int ST3 CAFRZ Cache freeze X P CAEN Cache enable X P CACLR Cache clear X P HINT Host interr...

Page 558: ...B 6 ...

Page 559: ... know about DSP BIOS in order to use it with the OMAP 2320 platform C 1 Overview C 2 C 2 OMAP 2320 and the CLK Module C 2 C 3 OMAP 2320 and the HWI Module C 4 C 4 OMAP 2320 and the C55 Module C 8 C 5 Building DSP BIOS Applications for OMAP 2320 C 8 C 6 Usage Examples C 9 Topic Page ...

Page 560: ... OMAP 2320 has 2 core timers which can be use to drive the low and high resolution DSP BIOS clock functionality C 2 1 Static Configuration By default the low resolution CLK function see CLK_getltime is enabled and assigned to core Timer 0 Alternately you can configure Timer 1 for this function To change the configuration add the following line to your Tconf configuration file bios CLK TIMERSELECT ...

Page 561: ...OMAP 2320 and the CLK Module DSP BIOS for OMAP 2320 C 3 In the Gconf configuration tool the CLK properties for the OMAP 2320 are as follows ...

Page 562: ...s that formerly interrupted the DSP at level 1 have been moved to level 2 The DSP BIOS interface to this interrupt controller is called the Level 2 Interrupt Manager L2IM The complexities of the L2IM are concealed by reusing and enhancing existing HWI module APIs As a result very few new API elements are needed The following sections describe extensions made to the HWI module to support the OMAP 2...

Page 563: ...errupts The none option disables no level 2 interrupts The bitmask option causes the mirmask and mir1mask properties to be used to specify the level 2 interrupts to disable mirmask This property is valid for both level 1 and 2 interrupts It defines a bitmask of level 2 interrupts 0 31 to be disabled by the DSP BIOS HWI dispatcher when executing this HWI function This property is writable only when...

Page 564: ...ctor IDs allowed is extended from 0 31 to 0 95 The IDs 32 95 correspond to level 2 interrupts 0 63 respectively The c55 h file now includes definitions for C55_L2_INT0 through C55_L2_INT63 which map to vector IDs 32 95 The HWI_Attrs structure used by HWI_dispatchPlug has been expanded to include two additional fields mirmask and mir1mask Each of these fields contains a 32 bit mask to specify which...

Page 565: ...2 bit bitmasks define which level 2 interrupts are to be masked while executing the HWI body In HWI_exit these masks define which level 2 interrupts are to be restored to their prior state before returning from the interrupt The OMAP 2320 macro invocation syntax is shown below HWI_enter C55_AR_DR_X_MASK C55_ACC_X_MASK C55_MISC1_X_MASK C55_MISC2_X_MASK C55_MISC3_X_MASK IER0DISABLEMASK IER1DISABLEMA...

Page 566: ...t Disable an individual interrupt C55_enableInt Enable an individual interrupt C55_l2AckInt Explicitly acknowledge an L2 interrupt C55_l2DisableMIR Disable a mask of L2 interrupts C55_l2EnableMIR Enable a mask of L2 interrupts C55_l2SetIntPriority Set the priority of a L2 interrupt C 5 Building DSP BIOS Applications for OMAP 2320 In order for the proper DSP BIOS header files to be used during the ...

Page 567: ... and enables the 23xx Level 2 interrupt 1 l2_example1 c DSP BIOS Level 2 interrupt example include std h include hwi h include log h include c55 h extern LOG_Obj trace void myIsr Arg id LOG_printf trace My l2 ISR d ArgToInt id 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 Lev...

Page 568: ... log h include c55 h extern LOG_Obj trace void l2FiqFunc Arg id LOG_printf trace l2_fiq d n ArgToInt id 32 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 attrs arg Arg C55_L2_INT11 HWI_dispatchPlug C55_L2_INT11 Fxn l2FiqFunc attrs C55_l2SetIntPriority C55_L2_INT11 1 attrs arg Arg C55_L2_INT1...

Page 569: ...rrupt number 1 l2_example3 c DSP BIOS Level 2 interrupt example include std h include hwi h include log h include c55 h extern LOG_Obj trace interrupt void myIsr Acknowledge this level 2 interrupt to the L2IC C55_l2AckInt Your code here Void main Plug Level 2 Interrupt 1 Vector C55_plug C55_L2_INT1 Fxn myIsr Enable Level 2 interrupt C55_enableInt C55_L2_INT1 ...

Page 570: ...R_DR_REGS C55_ALL_ACC_REGS C55_ALL_MISC1_REGS C55_ALL_MISC2_REGS C55_ALL_MISC3_REGS 0x0000 ier0 interrupt mask unchanged 0x0000 ier1 interrupt mask unchanged 0xffffffff all level 2 ints 0 31 masked 0xffffffff all level 2 ints 32 63 masked Your code here HWI_exit C55_ALL_AR_DR_REGS C55_ALL_ACC_REGS C55_ALL_MISC1_REGS C55_ALL_MISC2_REGS C55_ALL_MISC3_REGS 0x0000 ier0 interrupt mask unchanged 0x0000 ...

Page 571: ...de c55 h extern LOG_Obj trace void myIsr Arg id LOG_printf trace My L2 ISR d ArgToInt id Void main Enable Level 2 interrupt number 43 C55_enableInt C55_L2_INT43 TCONF script l2_example4 tcf bios HWI_L2_INT43 useDispatcher 1 use HWI dispatcher bios HWI_L2_INT43 fxn prog extern myIsr attach to myIsr C function bios HWI_L2_INT43 arg 43 pass interrupt ID as argument bios HWI_L2_INT43 iMirMask all mask...

Page 572: ...C 14 ...

Page 573: ...know about DSP BIOS in order to use it with the OMAP 2420 platform D 1 Overview D 2 D 2 OMAP 2420 and the CLK Module D 2 D 3 OMAP 2420 and the HWI Module D 5 D 4 OMAP 2420 and the C55 Module D 9 D 5 Building DSP BIOS Applications for OMAP 2420 D 9 D 6 Usage Examples D 10 Topic Page ...

Page 574: ...on For OMAP 2420 the high and low resolution DSP BIOS clocks are completely independent of each other It is possible to disable the low resolution CLK while still supporting the high resolution CLK features and vice versa The following CLK module properties have differences for OMAP 2420 TIMERSELECT This property may be set to Timer 5 or Timer 6 to set the GP timer used for the low resolution time...

Page 575: ...RM side GEL commands which are also provided with CCStudio or dedicated ARM code hotmenu ProgramMMU DSP MMU_SYSCONFIG Set bit 1 to perform a SOFTRESET int 0x5A000010 0x2 TLB 0 GPTIMER5 0x7000 Big Endian int 0x5A000050 0x00000000 DSP MMU_LOCK int 0x5A000058 0x00fdc00e DSP MMU_CAM int 0x5A00005C 0x4807c340 DSP MMU_RAM int 0x5A000054 0x00000001 DSP MMU_LD_TLB TLB 1 GPTIMER6 0x7400 Big Endian int 0x5A...

Page 576: ...done using the following ARM side GEL commands or dedicated ARM code hotmenu RouteGPTClocks CM_FCKLEN1_CORE Enable functional clock to GPT 5 6 7 int 0x48008200 0x380 CM_ICKLEN1_CORE Enable interface clock to GPT 5 6 7 int 0x48008210 0x380 CM_CLKSEL2_CORE route 32kHz clock to gpt5 6 and sys_clk to gpt7 int 0x48008244 0x1000 PRCM_CLKCFG_CTRL Validate CLK config in previous step int 0x48008080 1 ...

Page 577: ...nterrupted the DSP at level 1 have been moved out to level 2 The L2IC contains a 32 bit Interrupt Mask Register MIR which defines which level 2 interrupts are enabled or disabled The DSP BIOS interface to the L2IC is implemented as part of the HWI module The following sections describe extensions made to the HWI module to support the OMAP 2420 D 3 1 Level 2 Interrupt Controller Base Address By def...

Page 578: ...configured The all option disables all level 2 interrupts The none option disables no level 2 interrupts The bitmask option causes the mirmask property to be used to specify which level 2 interrupts to disable mirmask This property is valid for both level 1 and 2 interrupts It defines a bitmask of the level 2 interrupts to be disabled by the DSP BIOS HWI dispatcher when executing this HWI function...

Page 579: ... which additional level 2 interrupts to mask during the interrupt Each bit in this mask corresponds to a level 2 interrupt The default value of mirmask for all interrupts is to mask only the current level 2 interrupt typedef struct HWI_Attrs Uns ier0mask Level 1 interrupt masks Uns ier1mask Arg arg fxn arg default 0 LgUns mirmask Level 2 interrupt mask HWI_Attrs D 3 4 HWI_enter and HWI_exit APIs T...

Page 580: ...MASK C55_ACC_X_MASK C55_MISC1_X_MASK C55_MISC2_X_MASK C55_MISC3_X_MASK IER0DISABLEMASK IER1DISABLEMASK MIRDISABLEMASK HWI_exit C55_AR_DR_X_MASK C55_ACC_X_MASK C55_MISC1_X_MASK C55_MISC2_X_MASK C55_MISC3_X_MASK IER0RESTOREMASK IER1RESTOREMASK MIRRESTOREMASK ...

Page 581: ...5_disableInt Disable an individual interrupt C55_enableInt Enable an individual interrupt C55_l2AckInt Explicitly acknowledge an L2 interrupt C55_l2DisableMIR Disable a mask of L2 interrupts C55_l2EnableMIR Enable a mask of L2 interrupts C55_l2SetIntPriority Set the priority of a L2 interrupt D 5 Building DSP BIOS Applications for OMAP 2420 In order for the proper DSP BIOS header files to be used ...

Page 582: ...s the 24xx Level 2 interrupt 1 l2_example1 c DSP BIOS Level 2 interrupt example include std h include hwi h include log h include c55 h extern LOG_Obj trace void myIsr Arg id LOG_printf trace My l2 ISR d ArgToInt id 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 interr...

Page 583: ...i h include log h include c55 h extern LOG_Obj trace void l2FiqFunc Arg id LOG_printf trace l2_fiq d n ArgToInt id 32 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 attrs arg Arg C55_L2_INT11 HWI_dispatchPlug C55_L2_INT11 Fxn l2FiqFunc attrs C55_l2SetIntPriority C55_L2_INT11 1 attrs arg Arg ...

Page 584: ... 1 l2_example3 c DSP BIOS Level 2 interrupt example include std h include hwi h include log h include c55 h extern LOG_Obj trace interrupt void myIsr Acknowledge this level 2 interrupt to the L2IC C55_l2AckInt Your code here Void main Plug Level 2 Interrupt 1 Vector C55_plug C55_L2_INT1 Fxn myIsr Enable Level 2 interrupt C55_enableInt C55_L2_INT1 ...

Page 585: ...ref _trace ref _reportInfo _myIsr HWI_enter C55_ALL_AR_DR_REGS C55_ALL_ACC_REGS C55_ALL_MISC1_REGS C55_ALL_MISC2_REGS C55_ALL_MISC3_REGS 0x0000 ier0 interrupt mask unchanged 0x0000 ier1 interrupt mask unchanged 0xffffffff all level 2 interrupts masked Your code here HWI_exit C55_ALL_AR_DR_REGS C55_ALL_ACC_REGS C55_ALL_MISC1_REGS C55_ALL_MISC2_REGS C55_ALL_MISC3_REGS 0x0000 ier0 interrupt mask unch...

Page 586: ... h include c55 h extern LOG_Obj trace void myIsr Arg id LOG_printf trace My L2 ISR d ArgToInt id Void main Enable Level 2 interrupt number 7 C55_enableInt C55_L2_INT7 TCONF script l2_example4 tcf bios HWI_L2_INT7 useDispatcher 1 use HWI dispatcher bios HWI_L2_INT7 fxn prog extern myIsr attach to myIsr C function bios HWI_L2_INT7 arg 7 pass interrupt ID as argument bios HWI_L2_INT7 iMirMask all mas...

Page 587: ...cs for data series 2 413 B BIOS clock see timer BIOS library instrumented or non instrumented 2 111 BK registers conventions for B 3 board clock frequency 2 109 board input clock 2 112 board name 2 109 Bool data type 1 4 Boolean values 1 4 BR registers conventions for B 3 BSA registers conventions for B 3 BUF module 2 15 configuration properties 2 15 function callability A 2 functions in list of 1...

Page 588: ...MD register 2 110 clock domains idling 2 300 2 304 2 314 2 324 idling during deep sleep 2 307 clock function not callable from SWI or HWI A 9 Clock Mode Register 2 110 clocks see clock domains real time clock system clock timer communication channels closing 2 127 control call on 2 124 opening 2 125 2 129 consumer of data pipe 2 267 context CLK checking for 2 170 HWI checking for 2 170 SWI checkin...

Page 589: ...t properties 2 90 DIO adapter 2 62 2 92 configuration properties for 2 92 global properties 2 93 object properties 2 94 DNL driver 2 62 2 95 DOV driver 2 62 2 96 DP register conventions for B 3 DPI driver 2 62 2 99 object properties 2 101 D port write operation 2 111 drivers see device drivers DSP speed 2 109 DSP BIOS clock see timer DSP BIOS functions list of 1 5 DSP BIOS modules list of 1 2 DSP ...

Page 590: ...117 Gconf underscore preceding C function names 1 3 2 47 2 174 2 426 GEL configuration D 3 General Purpose GP Timers C 2 D 2 generators 2 80 getenv function 2 511 not callable from SWI or HWI A 9 GIO module 2 118 configuration properties 2 120 function callability A 3 functions in list of 1 8 2 118 global properties 2 121 object properties 2 122 GIO_abort function 2 123 GIO_control function 2 124 ...

Page 591: ... IER Interrupt Enable Register disable interrupts using 2 27 enable interrupts using 2 29 IER0 register conventions for B 3 IER1 register conventions for B 3 IFR0 register conventions for B 3 IFR1 register conventions for B 3 initialization 2 137 input channels declaring 2 357 disabling 2 359 enabling 2 361 number of MADUs read from 2 367 reading from 2 365 2 366 status of determining 2 363 input ...

Page 592: ...s 2 413 MBX module 2 195 configuration properties 2 195 function callability A 4 functions in list of 1 10 2 195 global properties 2 196 object properties 2 196 MBX_create function 2 197 MBX_delete function 2 198 MBX_pend function 2 199 MBX_post function 2 200 MEM module 2 201 configuration properties 2 201 function callability A 4 functions in list of 1 10 2 201 global properties 2 204 object pro...

Page 593: ...rors handling 2 260 static configuration 2 234 MSGQ_alloc function 2 239 MSGQ_close function 2 240 MSGQ_count function 2 241 MSGQ_free function 2 242 MSGQ_get function 2 243 MSGQ_getAttrs function 2 244 MSGQ_getDstQueue function 2 245 MSGQ_getMsgId function 2 246 MSGQ_getMsgSize function 2 247 MSGQ_getSrcQueue function 2 248 MSGQ_isLocalQueue function 2 249 MSGQ_locate function 2 250 MSGQ_locateAs...

Page 594: ...r of frames available to write 2 279 number of words written setting 2 284 putting frame in 2 282 recycling frame that has been read to 2 273 writerAddr point of getting 2 278 POOL module 2 285 configuration properties 2 285 functions in list of 2 285 global properties 2 289 posted mode 2 111 power event function to be called on 2 326 registered function to be called on 2 329 power management 2 29...

Page 595: ...ter to next element of 2 348 returning pointer to previous element of 2 349 testing if empty 2 342 R rand function not callable from SWI or HWI A 9 REA0 register conventions for B 3 REA1 register conventions for B 3 reader of data pipe 2 267 readers MSGQ module 2 231 2 233 read time data exchange settings 2 353 realloc function 2 511 not callable from SWI or HWI A 9 real time clock see CLK module ...

Page 596: ... SIO_ISSUERECLAIM streaming model DPI and 2 100 SIO_put function 2 400 SIO_ready function 2 402 SIO_reclaim function 2 403 SIO_reclaimx function 2 406 SIO_segid function 2 407 SIO_select function 2 408 SIO_staticbuf function 2 410 sleep changing sleep states 2 333 deep sleep enabling 2 307 for tasks 2 506 software generator driver 2 61 software interrupt manager 2 422 software interrupts address o...

Page 597: ... types for 2 467 SWI_andn function 2 428 SWI_andnHook function 2 430 SWI_create function 2 431 SWI_dec function 2 433 SWI_delete function 2 434 SWI_enable function 2 436 SWI_getattrs function 2 437 SWI_getmbox function 2 439 SWI_getpri function 2 440 SWI_inc function 2 441 SWI_isSWI function 2 442 SWI_or function 2 443 SWI_orHook function 2 444 SWI_post function 2 445 SWI_raisepri function 2 446 S...

Page 598: ... from 2 512 tick count determining 2 294 tick counter see PRD module ticks timer 2 39 2 40 counts per millisecond 2 48 reprogramming after frequency scaling 2 303 resetting 2 54 timer counter 2 41 timer divide down register 2 39 timer period register resetting 2 54 trace buffer memory segment for 2 452 size of 2 452 trace manager 2 467 tracing disabling 2 469 enabling 2 470 querying enabled trace ...

Page 599: ...er hook function 2 303 V V F setpoints changing 2 310 determining 2 317 frequency and voltage of determining 2 320 latency to scale between 2 322 number of determining 2 319 variables manipulating with interrupts disabled 2 2 vfprintf function not callable from SWI or HWI A 10 voltage changing 2 310 for setpoint determining 2 320 voltage scaling 2 306 vprintf function not callable from SWI or HWI ...

Search results

Summary of Contents for TMS320C55 Series

Reviews:

Related manuals for TMS320C55 Series

Brands by name

Popular brands

Texas Instruments TMS320C55 Series, Reference Manual

Search results

Summary of Contents for TMS320C55 Series

Reviews:

Related manuals for TMS320C55 Series

Brands by name

Popular brands