Download Print this page

Texas Instruments TMS320C55 Series Reference Manual

Texas Instruments TMS320C55 Series Reference Manual

Dsp/bios 5.32 application programming interface api

Table Of Contents

page of 599

/ 599
Contents
Table of Contents
Bookmarks

Table of Contents

Advertisement

Quick Links

Download this manual

TMS320C55x DSP/BIOS 5.32

Application Programming Interface

(API) Reference Guide

Literature Number: SPRU404N

September 2007

Table of Contents

Advertisement

Table of Contents

Need help?

Need help?

Do you have a question about the TMS320C55 Series and is the answer not in the manual?

Questions and answers

Summary of Contents for Texas Instruments TMS320C55 Series

Page 1 TMS320C55x DSP/BIOS 5.32 Application Programming Interface (API) Reference Guide Literature Number: SPRU404N September 2007...
Page 2 IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improve- ments, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete.
Page 3 Preface Read This First About This Manual DSP/BIOS gives developers of mainstream applications on Texas Instruments TMS320C5000 DSP devices the ability to develop embedded real-time software. DSP/BIOS provides a small firmware real-time library and easy-to-use tools for real-time tracing and analysis. You should read and become familiar with the TMS320 DSP/BIOS User’s Guide, a companion volume to this API reference guide.
Page 4 Related Documentation From Texas Instruments The following books describe TMS320 devices and related support tools. To obtain a copy of any of these TI documents, call the Texas Instruments Literature Response Center at (800) 477-8924. When ordering, please identify the book by its title and literature number.
Page 5 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, TMS320C67x, TMS320C5000, and TMS320C6000.
Page 7: Table Of Contents
Contents API Functional Overview ........... .1-1 This chapter provides an overview to the TMS320C55x DSP/BIOS API functions.
Page 8 Contents 2.27 SYS Module ............2-451 2.28 TRC Module .
Page 9 Figures MYSEG Heap Initial Memory Map ................2-215 MYSEG Memory Map After Allocation................ 2-216 MYSEG Memory Map After Modified Allocation ............2-217 Writers and Reader of a Message Queue ..............2-232 Components of the MSGQ Architecture ..............2-233 MSGQ Function Calling Sequence ................2-233 Pipe Schematic ......................
Page 10 Tables DSP/BIOS Modules ......................1-2 DSP/BIOS Operations ....................1-5 Timer Counter Rates, Targets, and Resets ..............2-41 High-Resolution Time Determination ................2-42 HWI interrupts for the ‘C55x..................2-158 Conversion Characters for LOG_printf ............... 2-191 Typical Memory Segments for C5000 Boards ............2-213 Statistics Units for HWI, PIP, PRD, and SWI Modules ..........
Page 11: Api Functional Overview
Chapter 1 API Functional Overview This chapter provides an overview to the TMS320C55x DSP/BIOS API functions. Topic Page 1.1 DSP/BIOS Modules ........1–2 1.2 Naming Conventions.
Page 12: Dsp/Bios Modules
DSP/BIOS Modules DSP/BIOS Modules Table 1-1. DSP/BIOS Modules Module Description ATM Module Atomic functions written in assembly language BUF Module Maintains buffer pools of fixed size buffers C55 Module Target-specific functions CLK Module System clock manager DEV Module Device driver interface GBL Module Global setting manager GIO Module...
Page 13: Naming Conventions
Naming Conventions Naming Conventions The format for a DSP/BIOS operation name is a 3- or 4-letter prefix for the module that contains the operation, an underscore, and the action. Assembly Language Interface Overview The assembly interface that was provided for some of the DSP/BIOS APIs has been deprecated.
Page 14 DSP/BIOS Tconf Overview In general, property names of Module objects are in all uppercase letters. For example, "STACKSIZE". Property names of Instance objects begin with a lowercase word. Subsequent words have their first letter capitalized. For example, "stackSize". Default values for many properties are dependent on the values of other properties.
Page 15: Dsp/Bios Operations
List of Operations List of Operations Table 1-2. DSP/BIOS Operations ATM module operations Function Operation ATM_andi, ATM_andu Atomically AND memory location with mask and return previous value ATM_cleari, ATM_clearu Atomically clear memory location and return previous value ATM_deci, ATM_decu Atomically decrement memory and return new value ATM_inci, ATM_incu Atomically increment memory and return new value ATM_ori, ATM_oru...
Page 16 List of Operations Function Operation C55_l2DisableMIR, Disable certain level 2 interrupts (OMAP 2320/2420 only) C55_l2DisableMIR1 C55_l2EnableMIR, Enable certain level 2 interrupts (OMAP 2320/2420 only) C55_l2EnableMIR1 C55_l2SetIntPriority Set the priority of an L2 interrupt (OMAP 2320/2420 only) C55_plug C function to plug an interrupt vector CLK module operations Function Operation...
Page 17 List of Operations Function Operation Dxx_issue Send a buffer to the device Dxx_open Open device Dxx_ready Check if device is ready for I/O Dxx_reclaim Retrieve a buffer from a device DGN Driver Software generator driver DGS Driver Stackable gather/scatter driver DHL Driver Host link driver DIO Driver...
Page 18 List of Operations GIO module operations Function Operation GIO_abort Abort all pending input and output GIO_control Device-specific control call GIO_create Allocate and initialize a GIO object GIO_delete Delete underlying IOM mini-drivers and free GIO object and its structure GIO_flush Drain output buffers and discard any pending input GIO_new Initialize a pre-allocated GIO object GIO_read...
Page 19 List of Operations Function Operation HWI_exit Hardware interrupt service routine epilog HWI_isHWI Check to see if called in the context of an HWI HWI_restore Restore global interrupt enable state IDL module operations Function Operation IDL_run Make one pass through idle functions LCK module operations Function Operation...
Page 20 List of Operations MBX module operations Function Operation MBX_create Create a mailbox MBX_delete Delete a mailbox MBX_pend Wait for a message from mailbox MBX_post Post a message to mailbox MEM module operations Function Operation MEM_alloc, MEM_valloc, Allocate from a memory heap MEM_calloc MEM_define Define a new memory heap...
Page 21 List of Operations Function Operation MSGQ_getMsgId Return the message ID from a message. MSGQ_getMsgSize Return the message size from a message. MSGQ_getSrcQueue Extract the reply destination from a message. MSGQ_isLocalQueue Return whether queue is local. MSGQ_locate Synchronously find a message queue. Performed by writer. MSGQ_locateAsync Asynchronously find a message queue.
Page 22 List of Operations PRD module operations Function Operation PRD_getticks Get the current tick counter PRD_start Arm a periodic function for one-time execution PRD_stop Stop a periodic function from execution PRD_tick Advance tick counter, dispatch periodic functions PWRM module operations Function Operation PWRM_changeSetpoint Initiate a change to the V/F setpoint...
Page 23 List of Operations QUE module operations Function Operation QUE_create Create an empty queue QUE_delete Delete an empty queue QUE_dequeue Remove from front of queue (non-atomically) QUE_empty Test for an empty queue QUE_enqueue Insert at end of queue (non-atomically) QUE_get Get element from front of queue (atomically) QUE_head Return element at front of queue QUE_insert...
Page 24 List of Operations Function Operation RTDX_readNB Read from an input channel without blocking RTDX_sizeofInput Return the number of bytes read from an input channel RTDX_write Write to an output channel SEM module operations Function Operation SEM_count Get current semaphore count SEM_create Create a semaphore SEM_delete...
Page 25 List of Operations Function Operation SIO_ready Determine if device for stream is ready SIO_reclaim Request a buffer back from a stream SIO_reclaimx Request a buffer and frame status back from a stream SIO_segid Memory section used by a stream SIO_select Select a ready device SIO_staticbuf Acquire static buffer from stream...
Page 26 List of Operations Function Operation SWI_or Set or mask in an SWI’s mailbox and post SWI_orHook Specialized version of SWI_or SWI_post Post a software interrupt SWI_raisepri Raise an ’s priority SWI_restorepri Restore an ’s priority SWI_self Return address of currently executing SWI object SWI_setattrs Set attributes of a software interrupt SYS module operations...
Page 27 List of Operations Function Operation TSK_disable Disable DSP/BIOS task scheduler TSK_enable Enable DSP/BIOS task scheduler TSK_exit Terminate execution of the current task TSK_getenv Get task environment TSK_geterr Get task error number TSK_getname Get task name TSK_getpri Get task priority TSK_getsts Get task STS object TSK_isTSK Check to see if called in the context of a TSK...
Page 28 List of Operations DSP/BIOS std.h special utility C macros Function Operation ArgToInt(arg) Casting to treat Arg type parameter as integer (Int) type on the given target ArgToPtr(arg) Casting to treat Arg type parameter as pointer (Ptr) type on the given target 1-18...
Page 29: Topic Page
Chapter 2 Application Program Interface This chapter describes the DSP/BIOS API modules and functions. Topic Page 2.1 ATM Module ..........2–2 2.2 BUF Module .
Page 30 ATM Module ATM Module The ATM module includes assembly language functions. ❏ ATM_andi, ATM_andu. AND memory and return previous value Functions ❏ ATM_cleari, ATM_clearu. Clear memory and return previous value ❏ ATM_deci, ATM_decu. Decrement memory and return new value ❏ ATM_inci, ATM_incu. Increment memory and return new value ❏...
Page 31 ATM_andi ATM_andi Atomically AND Int memory location and return previous value C Interface Syntax ival = ATM_andi(idst, isrc); Parameters volatile Int *idst; /* pointer to integer */ isrc; /* integer mask */ Return Value ival; /* previous value of *idst */ Description ATM_andi atomically ANDs the mask contained in isrc with a destination memory location and overwrites the destination value *idst with the result...
Page 32 ATM_andu ATM_andu Atomically AND Uns memory location and return previous value C Interface Syntax uval = ATM_andu(udst, usrc); Parameters volatile Uns *udst; /* pointer to unsigned */ usrc; /* unsigned mask */ Return Value uval; /* previous value of *udst */ Description ATM_andu atomically ANDs the mask contained in usrc with a destination memory location and overwrites the destination value *udst...
Page 33 ATM_cleari ATM_cleari Atomically clear Int memory location and return previous value C Interface Syntax ival = ATM_cleari(idst); Parameters volatile Int *idst; /* pointer to integer */ Return Value ival; /* previous value of *idst */ Description ATM_cleari atomically clears an Int memory location and returns its previous value as follows: `interrupt disable` ival = *idst;...
Page 34 ATM_clearu ATM_clearu Atomically clear Uns memory location and return previous value C Interface Syntax uval = ATM_clearu(udst); Parameters volatile Uns *udst; /* pointer to unsigned */ Return Value uval; /* previous value of *udst */ Description ATM_clearu atomically clears an Uns memory location and returns its previous value as follows: `interrupt disable` uval = *udst;...
Page 35 ATM_deci ATM_deci Atomically decrement Int memory and return new value C Interface Syntax ival = ATM_deci(idst); Parameters volatile Int *idst; /* pointer to integer */ Return Value ival; /* new value after decrement */ Description ATM_deci atomically decrements an Int memory location and returns its new value as follows: `interrupt disable` ival = *idst - 1;...
Page 36 ATM_decu ATM_decu Atomically decrement Uns memory and return new value C Interface Syntax uval = ATM_decu(udst); Parameters volatile Uns *udst; /* pointer to unsigned */ Return Value uval; /* new value after decrement */ Description ATM_decu atomically decrements a Uns memory location and returns its new value as follows: `interrupt disable` uval = *udst - 1;...
Page 37 ATM_inci ATM_inci Atomically increment Int memory and return new value C Interface Syntax ival = ATM_inci(idst); Parameters volatile Int *idst; /* pointer to integer */ Return Value ival; /* new value after increment */ Description ATM_inci atomically increments an Int memory location and returns its new value as follows: `interrupt disable` ival = *idst + 1;...
Page 38 ATM_incu ATM_incu Atomically increment Uns memory and return new value C Interface Syntax uval = ATM_incu(udst); Parameters volatile Uns *udst; /* pointer to unsigned */ Return Value uval; /* new value after increment */ Description ATM_incu atomically increments an Uns memory location and returns its new value as follows: `interrupt disable` uval = *udst + 1;...
Page 39 ATM_ori ATM_ori Atomically OR Int memory location and return previous value C Interface Syntax ival = ATM_ori(idst, isrc); Parameters volatile Int *idst; /* pointer to integer */ isrc; /* integer mask */ Return Value ival; /* previous value of *idst */ Description ATM_ori atomically ORs the mask contained in isrc with a destination memory location and overwrites the destination value *idst with the result...
Page 40 ATM_oru ATM_oru Atomically OR Uns memory location and return previous value C Interface Syntax uval = ATM_oru(udst, usrc); Parameters volatile Uns *udst; /* pointer to unsigned */ usrc; /* unsigned mask */ Return Value uva; /* previous value of *udst */ Description ATM_oru atomically ORs the mask contained in usrc with a destination memory location and overwrites the destination value *udst with the...
Page 41 ATM_seti ATM_seti Atomically set Int memory and return previous value C Interface Syntax iold = ATM_seti(idst, inew); Parameters volatile Int *idst; /* pointer to integer */ inew; /* new integer value */ Return Value iold; /* previous value of *idst */ Description ATM_seti atomically sets an Int memory location to a new value and returns its previous value as follows:...
Page 42 ATM_setu ATM_setu Atomically set Uns memory and return previous value C Interface Syntax uold = ATM_setu(udst, unew); Parameters volatile Uns *udst; /* pointer to unsigned */ unew; /* new unsigned value */ Return Value uold; /* previous value of *udst */ Description ATM_setu atomically sets an Uns memory location to a new value and returns its previous value as follows:...
Page 43: Buf Module
BUF Module BUF Module The BUF module maintains buffer pools of fixed-size buffers. ❏ BUF_alloc. Allocate a fixed-size buffer from the buffer pool Functions ❏ BUF_create. Dynamically create a buffer pool ❏ BUF_delete. Delete a dynamically-created buffer pool ❏ BUF_free. Free a fixed-size buffer back to the buffer pool ❏...
Page 44 BUF Module Module Configuration Parameters Name Type Default (Enum Options) OBJMEMSEG Reference prog.get("DARAM") Instance Configuration Parameters Name Type Default (Enum Options) comment String "<add comments here>" bufSeg Reference prog.get("DARAM") bufCount Int32 size Int32 4 (’C55x) align Int32 2 (’C55x) Int32 4 (’C55x) postalignsize Int32...
Page 45 BUF Module ❏ Less fragmentation. Since the buffers are of fixed-size, the pool does not become fragmented. BUF Manager The following global properties can be set for the BUF module in the BUF Properties Manager Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏...
Page 46 BUF Module ❏ Buffer alignment. Specify the alignment boundary for fixed-length buffers in the pool. Each buffer is aligned on boundaries with a multiple of this number. The default size shown is the minimum valid value for that platform. The value must be a power of 2. Tconf Name: align Type: Int32 Example:...
Page 47 BUF_alloc BUF_alloc Allocate a fixed-size buffer from a buffer pool C Interface Syntax bufaddr = BUF_alloc(buf); Parameters BUF_Handle buf; /* buffer pool object handle */ Return Value bufaddr; /* pointer to free buffer */ Reentrant Description BUF_alloc allocates a fixed-size buffer from the specified buffer pool and returns a pointer to the buffer.
Page 48 BUF_create BUF_create Dynamically create a buffer pool C Interface Syntax buf = BUF_create(numbuff, size, align, attrs); Parameters numbuff; /* number of buffers in the pool */ MEM_sizep size; /* size of a single buffer in the pool */ align; /* alignment for each buffer in the pool */ BUF_Attrs *attrs;...
Page 49 BUF_create The segid element can be used to specify the memory segment in which buffer pool should be created. If attrs is NULL, the new buffer pool is created the default attributes specified in BUF_ATTRS, which uses the default memory segment. BUF_create calls MEM_alloc to dynamically create the BUF object's data structure and the buffer pool.
Page 50 BUF_delete BUF_delete Delete a dynamically-created buffer pool C Interface Syntax status = BUF_delete(buf); Parameters BUF_Handle buf; /* buffer pool object handle */ Return Value status; /* returned status */ Reentrant Description BUF_delete frees the buffer pool object and the buffer pool memory referenced by the handle provided.
Page 51 BUF_free BUF_free Free a fixed memory buffer into the buffer pool C Interface Syntax status = BUF_free(buf, bufaddr); Parameters BUF_Handle buf; /* buffer pool object handle */ bufaddr; /* address of buffer to free */ Return Value Bool status; /* returned status */ Reentrant Description BUF_free frees the specified buffer back to the specified buffer pool.
Page 52 BUF_maxbuff BUF_maxbuff Check the maximum number of buffers from the buffer pool C Interface Syntax count = BUF_maxbuff(buf); Parameters BUF_Handle buf; /* buffer pool object Handle */ Return Value count; /*maximum number of buffers used */ Reentrant Description BUF_maxbuff returns the maximum number of buffers that have been allocated from the specified buffer pool at any time.
Page 53 BUF_stat BUF_stat Determine the status of a buffer pool C Interface Syntax BUF_stat(buf,statbuf); Parameters BUF_Handle buf; /* buffer pool object handle */ BUF_Stat *statbuf; /* pointer to buffer status structure */ Return Value none Reentrant Description BUF_stat returns the status of the specified buffer pool. The buf parameter is the handle that identifies the buffer pool object.
Page 54: C55 Module
C55 Module C55 Module The C55 module include target-specific functions for the TMS320C5000 family ❏ C55_disableIER0, C55_disableIER1. ASM macros to disable Functions selected interrupts in the IER0/IER1, respectively ❏ C55_disableInt. Disable an individual interrupt. ❏ C55_enableIER0, C55_enableIER1. ASM macros to enable selected interrupts in the IER0/IER1, respectively ❏...
Page 55 C55_disableIER0, C55_disableIER1 C55_disableIER0, Disable certain maskable interrupts C55_disableIER1 C Interface Syntax oldmask = C55_disableIER0(mask); oldmask = C55_disableIER1(mask); Parameters mask; /* disable mask */ Return Value oldmask; /* actual bits cleared by disable mask */ Description C55_disableIER0 and C55_disableIER1 disable interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER0/IER1).
Page 56 C55_disableInt C55_disableInt Disable an individual interrupt C Interface Syntax C55_disableInt(vecid); Parameters vecid; /* vector ID for interrupt */ Return Value Void Description This function disables an individual 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).
Page 57 C55_enableIER0, C55_enableIER1 C55_enableIER0, Enable certain maskable interrupts C55_enableIER1 C Interface Syntax C55_enableIER0(oldmask); C55_enableIER1(oldmask); Parameters oldmask; /* enable mask */ Return Value Void Description C55_disableIER0, C55_disableIER1, C55_enableIER0, C55_enableIER1 disable and enable specific internal interrupts by modifying the Interrupt Enable Register (IER0/IER1). C55_disableIER0 and C55_disableIER1 clear the bits specified by the mask parameter in the Interrupt Mask Register and return a mask of the bits it cleared.
Page 58 C55_enableIER0, C55_enableIER1 this region, it could cause a task switch. You can prevent this by enclosing it with TSK_disable / TSK_enable to disable DSP/BIOS task scheduling. oldmask; TSK_disable(); oldmask0 = C55_disableIER0(INTMASK0); oldmask1 = C55_disableIER1(INTMASK1); `do some critical operation;` `NOT OK to call TSK_sleep, SEM_post, etc.` C55_enableIER0(oldmask0);...
Page 59 C55_enableInt C55_enableInt Enable an individual interrupt C Interface Syntax C55_enableInt(vecid); Parameters vecid; /* vector ID for interrupt */ Return Value Void Description This function enables an individual interrupt referenced by a vector ID. The vector ID can match a level 1 interrupt (vecids 0-31) or an OMAP2320/2420 level 2 interrupt (vecids 32-63).
Page 60 C55_l2AckInt C55_l2AckInt Explicitly acknowledge an L2 interrupt C Interface Syntax C55_l2AckInt(); Parameters Void Return Value Void Description This API applies to the OMAP 2320/2420 platforms only. The L2IC requires the interrupts be explicitly acknowledged prior to returning from an ISR in order to allow other L2 interrupts to be processed.
Page 61 C55_l2DisableMIR C55_l2DisableMIR Disable certain level 2 interrupts C Interface Syntax C55_l2DisableMIR(mirmask); Parameters LgUns mirmask; /* disable mask */ Return Value Void Description This API applies to OMAP 2320/2420 platforms only. C55_l2DisableMIR disables level 2 interrupts by setting the bits specified by mirmask in the Interrupt Mask Register (MIR).
Page 62 C55_l2DisableMIR1 C55_l2DisableMIR1 Disable certain level 2 interrupts C Interface Syntax C55_l2DisableMIR1(mir1mask); Parameters LgUns mir1mask;/* disable mask */ Return Value Void Description This API applies to the OMAP 2320 platform only. C55_l2DisableMIR1 disables level 2 interrupts by setting the bits specified by mir1mask in the Interrupt Mask Register1 (MIR1). The MIR1 is a register in the Level 2 Interrupt Controller (L2IC) that defines which level 2 interrupts (32-63) are enabled or disabled.
Page 63 C55_l2EnableMIR C55_l2EnableMIR Enable certain level 2 interrupts C Interface Syntax C55_l2EnableMIR(mirmask); Parameters LgUns mirmask; /* disable mask */ Return Value Void Description This API applies to the OMAP 2320/2420 platforms only. C55_l2EnableMIR enables level 2 interrupts by clearing the bits specified by mirmask in the Interrupt Mask Register (MIR).
Page 64 C55_l2EnableMIR1 C55_l2EnableMIR1 Enable certain level 2 interrupts C Interface Syntax C55_l2EnableMIR1(mir1mask); Parameters LgUns mir1mask;/* disable mask */ Return Value Void Description This API applies to the OMAP 2320 platform only. C55_l2EnableMIR1 enables level 2 interrupts by clearing the bits specified by mir1mask in the Interrupt Mask Register1 (MIR1). The MIR1 is a register in the Level 2 Interrupt Controller (L2IC) that defines which level 2 interrupts (32-63) are enabled or disabled.
Page 65 C55_l2SetIntPriority C55_l2SetIntPriority Set the priority of a level 2 interrupt C Interface Syntax C55_l2SetIntPriority(vecid, priority); Parameters vecid; /* vector ID of interrupt */ priority; /* new priority of interrupt */ Return Value Void Description This API applies to the OMAP 2320/2420 platforms only. The Level 2 Interrupt Controller (L2IC) allows you to set the relative priority of each of the level 2 interrupts.
Page 66 C55_plug C55_plug C function to plug an interrupt vector C Interface Syntax C55_plug(vecid, fxn); Parameters vecid; /* interrupt id */ fxn; /* pointer to HWI function */ Return Value Void Description C55_plug hooks up the specified function as the branch target for a hardware interrupt (fielded by the CPU) at the vector address corresponding to vecid.
Page 67: Clk Module
CLK Module CLK Module The CLK module is the clock manager ❏ CLK_countspms. Timer counts per millisecond Functions ❏ CLK_cpuCyclesPerHtime. Return high-res time to CPU cycles factor ❏ CLK_cpuCyclesPerLtime. Return low-res time to CPU cycles factor ❏ CLK_gethtime. Get high-resolution time ❏...
Page 68 CLK Module C55x Name Type Default (Enum Options) TCRPTV EnumInt 0 (0 to 7) (1x10, 59xx only) Int16 46666, 7499, or 59999 (varies by platform) (not used for 1x10, 59xx) INPUTCLK Numeric 0.032 MHz (OMAP 2420 only) HTIMECLK Numeric 12.0 MHz (OMAP 2420 only) Instance Configuration Parameters Name Type...
Page 69: Timer Counter Rates, Targets, And Resets
CLK Module Timer Counter The timer counter changes at a relatively fast rate until it reaches a target value. When the target value is reached, the timer counter is reset, a timer interrupt occurs, the low-resolution time is incremented, and any functions defined for CLK objects are run.
Page 70: High-Resolution Time Determination
CLK Module ❏ The CLK_F_isr function causes the low-resolution time to be incremented by 1. ❏ The CLK_F_isr function causes all the CLK Functions to be performed in sequence in the context of that HWI. Therefore, the low-resolution clock ticks at the timer interrupt rate and returns the number of timer interrupts that have occurred.
Page 71 CLK Module CLK Functions The CLK functions performed when a timer interrupt occurs are performed in the context of the hardware interrupt that caused the system clock to tick. Therefore, the amount of processing performed within CLK functions should be minimized and these functions can only invoke DSP/BIOS calls that are allowable from within an HWI.
Page 72 CLK Module ❏ Base Address of Timers in Data Space. This property points to the address of the OMAP 2420 timers as mapped in the Data space by the ARM. (OMAP 2420 only) Tconf Name: TIMERS_BASE_DATAMEM Type: Numeric Example: bios.CLK.TIMERS_BASE_DATAMEM = 0x7ee000; ❏...
Page 73 CLK Module ❏ Fix TDDR. If this property is set to true, the value in the TDDR property is not modified by changes to the Microseconds/Int property. (Not available for OMAP 2320/2420.) Tconf Name: FIXTDDR Type: Bool Example: bios.CLK.FIXTDDR = false; ❏...
Page 74 CLK Module ❏ Clock Rate to ltime timer. Specify the rate in MHz for the low- resolution time. On the OMAP 2420, this may be either the 0.032 MHz clock, the 12 MHz clock, or the external clock. (OMAP 2420 only.) Tconf Name: INPUTCLK Type: Numeric...
Page 75 CLK Module Since all CLK functions are performed at the same periodic rate, functions that need to run at a multiple of that rate should either count the number of interrupts and perform their activities when the counter reaches the appropriate value or be configured as PRD objects. If this function is written in C and you are using the DSP/BIOS Configuration Tool, use a leading underscore before the C function name.
Page 76 CLK_countspms CLK_countspms Number of hardware timer counts per millisecond C Interface Syntax ncounts = CLK_countspms(); Parameters Void Return Value LgUns ncounts; Reentrant Description CLK_countspms returns the number of high-resolution timer counts per millisecond. CLK_countspms can be used to compute an absolute length of time from the number of low resolution timer interrupts.
Page 77 CLK_cpuCyclesPerHtime CLK_cpuCyclesPerHtime Return multiplier for converting high-res time to CPU cycles C Interface Syntax ncycles = CLK_cpuCyclesPerHtime(Void); Parameters Void Return Value Float ncycles; Reentrant Description CLK_cpuCyclesPerHtime returns the multiplier required to convert from high-resolution time to CPU cycles. High-resolution time is returned by CLK_gethtime.
Page 78 CLK_cpuCyclesPerLtime CLK_cpuCyclesPerLtime Return multiplier for converting low-res time to CPU cycles C Interface Syntax ncycles = CLK_cpuCyclesPerLtime(Void); Parameters Void Return Value Float ncycles; Reentrant Description CLK_cpuCyclesPerLtime returns the multiplier required to convert from low-resolution time to CPU cycles. Low-resolution time is returned by CLK_gethtime.
Page 79 CLK_gethtime CLK_gethtime Get high-resolution time C Interface Syntax currtime = CLK_gethtime(); Parameters Void Return Value LgUns currtime /* high-resolution time */ Reentrant Description CLK_gethtime returns the number of high-resolution clock cycles that have occurred as a 32-bit value. When the number of cycles reaches the maximum value that can be stored in 32 bits, the value wraps back to 0.
Page 80 CLK_getltime CLK_getltime Get low-resolution time C Interface Syntax currtime = CLK_getltime(); Parameters Void Return Value LgUns currtime /* low-resolution time */ Reentrant Description CLK_getltime returns the number of timer interrupts that have occurred as a 32-bit time value. When the number of interrupts reaches the maximum value that can be stored in 32 bits, value wraps back to 0 on the next interrupt.
Page 81 CLK_getprd CLK_getprd Get period register value C Interface Syntax period = CLK_getprd(); Parameters Void Return Value period /* period register value */ Reentrant Description CLK_getprd returns the number of high-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.
Page 82 CLK_reconfig CLK_reconfig Reset timer period and registers using current CPU frequency C Interface Syntax status = CLK_reconfig(); Parameters Void Return Value Bool status /* FALSE if failed */ Reentrant Description This function needs to be called after a call to GBL_setFrequency. It computes values for the timer period and the prescalar registers using the new CPU frequency.
Page 83 CLK_reconfig ❏ When calling CLK_reconfig from anywhere other than main(), you Constraints and Calling Context must also use CLK_stop and CLK_start. ❏ 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_reconfig or if interrupt processing relies on having a running timer to ensure that these non-reentrant functions are not interrupted.
Page 84 CLK_start CLK_start Restart the low-resolution timer C Interface Syntax CLK_start(); Parameters Void Return Value Void Reentrant Description This function starts the low-resolution timer if it has been halted by CLK_stop. The period and prescalar registers are updated to reflect any changes made by a call to CLK_reconfig.
Page 85 CLK_stop CLK_stop Halt the low-resolution timer C Interface Syntax CLK_stop(); Parameters Void Return Value Void Reentrant Description This function stops the low-resolution timer. It can be used in conjunction with CLK_reconfig and CLK_start to reconfigure the timer at run-time. Note that all ’C55x platforms except the ’C5501, ’C5502, and OMAP 2320/2420 use the same timer to drive low-resolution and high-resolution times.
Page 86: Dev Module
DEV Module DEV Module Important Note: The DEV module is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). The DEV module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 87 DEV Module Application / Fram ew ork PIP APIs SIO APIs Class GIO APIs Driver Device PIO Adapter DIO Adapter Driver Mini- IOM Mini-Driver(s) Driver Chip Support Library (CSL) O n-Chip Peripheral Hardw are Off-Chip Peripheral Hardw are The SIO/DEV model provides a streaming I/O interface. In this model, the application indirectly invokes DEV functions implemented by the driver managing the physical device attached to the stream, using generic functions provided by the SIO module.
Page 88 DEV Module Constants, Types, and #define DEV_INPUT Structures #define DEV_OUTPUT typedef struct DEV_Frame { /* frame object */ QUE_Elem link; /* queue link */ addr; /* buffer address */ size_t size; /* buffer size */ misc; /* reserved for driver */ arg;...
Page 89 DEV Module typedef struct DEV_Device { /* device specifier */ String name; /* device name */ Void * fxns; /* device function table*/ #if (defined(_54_) && defined(_FAR_MODE)) || defined(_55_) LgInt devid; /* device ID */ #else devid; /*device ID */ #endif params;...
Page 90 DEV Module ❏ DHL Driver (host link driver). Driver that uses the HST interface to send data to and from the Host Channel Control Analysis Tool. ❏ DIO Adapter (class driver). Driver used with the device driver model. ❏ DPI Driver (pipe driver). Software device used to stream data between DSP/BIOS tasks.
Page 91 DEV Module ❏ function table type. Choose the type of function table used by the driver to which this device interfaces. Use the IOM_Fxns option if you are using the DIO class driver to interface to a mini-driver with an IOM_Fxns function table.
Page 92 DEV_createDevice DEV_createDevice Dynamically create device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 93 DEV_createDevice The attrs parameter points to a structure of type DEV_Attrs. This structure used pass additional device attributes DEV_createDevice. If attrs is NULL, the device is created with default attributes. DEV_Attrs has the following structure: typedef struct DEV_Attrs { #if (defined(_54_) && defined(_FAR_MODE)) || defined(_55_) LgInt devid;...
Page 94 DEV_createDevice DEV_createDevice returns one of the following status values: Constant Description SYS_OK Success. SYS_EINVAL A device with the specified name already exists. SYS_EALLOC The heap is not large enough to allocate the device. DEV_createDevice calls SYS_error if mdBindDev returns a failure condition.
Page 95 DEV_deleteDevice DEV_deleteDevice Delete a dynamically-created device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 96 DEV_deleteDevice ❏ This function can be used only if dynamic memory allocation is enabled. ❏ The device name must match a dynamically-created device. DSP/BIOS does not check that the device was not created statically. Example status = DEV_deleteDevice("/pipe0"); See Also SIO_delete 2-68...
Page 97 DEV_match DEV_match Match a device name with a driver Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616).
Page 98 Dxx_close Dxx_close Close device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 99 Dxx_ctrl Dxx_ctrl Device control operation Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 100 Dxx_idle Dxx_idle Idle device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 101 Dxx_init Dxx_init Initialize device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 102 Dxx_issue Dxx_issue Send a buffer to the device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616).
Page 103 Dxx_issue buffer data (transformed as necessary), the size (adjusted as appropriate by the transform) and the arg field. The DEV_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.
Page 104 Dxx_open Dxx_open Open device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This API is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 105 Dxx_ready Dxx_ready Check if device is ready for I/O Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616).
Page 106 Dxx_reclaim Dxx_reclaim Retrieve a buffer from a device Important Note: This API will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616).
Page 107 Dxx_reclaim Dxx_reclaim is used in conjunction with Dxx_issue 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 for input streams. The Dxx_reclaim recovers empty frames in output streams, and retrieves full frames and performs processing for input streams.
Page 108: Dsp/Bios Tconf Overview
DGN Driver DGN Driver Software generator driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 109 DGN Driver Name Type Default (Enum Options) phase Numeric rate Int32 Extern prog.extern("FXN_F_nop") 0x00000000 Data Streaming The DGN driver places no inherent restrictions on the size or memory segment of the data buffers used when streaming from a generator device. Since generators are fabricated entirely in software and do not overlap I/O with computation, no more than one buffer is required to attain maximum performance.
Page 110 DGN Driver ■ printInt. Writes the stream data buffers to the trace buffer in integer format. Tconf Name: device Type: EnumString Options: "user", "sine", "random", "constant", "printHex", "printInt" Example: myDgn.device = "user"; ❏ Use default parameters. Set this property to true if you want to use the default parameters for the Device category you selected.
Page 111 DGN Driver right-shifted before being copied into the input buffer. For example, if you set the Gain to 100, the sine wave magnitude is 128, the nearest power of two. Tconf Name: gain Type: Numeric Example: myDgn.gain = 32767; ❏ Frequency. The frequency of the generated sine wave (in cycles per second) if the Device category is sine.
Page 112 DGS Driver DGS Driver Stackable gather/scatter driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 113 DGS Driver DGS_Params is defined in dgs.h as follows: ======== DGS_Params ======== */ typedef struct DGS_Params { /* device parameters */ createFxn; deleteFxn; transFxn; arg; num; den; } DGS_Params; The device parameters are: ❏ create function. Optional, default is NULL. Specifies a function that is called to create and/or initialize a transform specific object.
Page 114 DGS Driver Transform Functions The following transform functions are already provided with the DGS driver: ❏ u32tou8/u8tou32. These functions provide conversion to/from packed unsigned 8-bit integers to unsigned 32-bit integers. The buffer must contain a multiple of 4 number of 32-bit/8-bit unsigned values.
Page 115 DGS Driver Example The following code example declares DGS_PRMS as a DGS_Params structure: #include <dgs.h> DGS_Params DGS_PRMS { NULL, /* optional create function */ NULL, /* optional delete function */ u32tou8, /* required transform function */ /* optional argument */ /* numerator */ /* denominator */ By typing _DGS_PRMS for the Parameters property of a device, the...
Page 116 DHL Driver DHL Driver Host link driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 117 DHL Driver Module Configuration Parameters Name Type Default OBJMEMSEG Reference prog.get("DARAM") Instance Configuration Parameters Name Type Default (Enum Options) comment String "<add comments here>" hstChannel Reference prog.get("myHST") mode EnumString "output" ("input") Data Streaming DHL devices can be opened for input or output data streaming. A DHL device used by a stream created in output mode must be associated with an output HST channel.
Page 118 DHL Driver has been transferred to HST channel frames, the DHL device returns the current frame to the channel’s pipe. In this situation, if the HST channel’s frames can hold more data than the stream’s buffers, the frames always return to the HST pipe partially full. The maximum performance in a DHL device is obtained when you configure the frame size of its HST channel to match the buffer size of the stream that uses the device.
Page 119 DHL Driver ❏ Underlying HST Channel. Select the underlying HST channel from the drop-down list. The "Make this channel available for a new DHL device" property in the HST Object Properties must be set to true for that HST object to be known here. Tconf Name: hstChannel Type: Reference Example:...
Page 120 DIO Adapter DIO Adapter SIO Mini-driver adapter Description The DIO adapter allows GIO-compliant mini-drivers to be used through SIO module functions. Such mini-drivers are described in the DSP/BIOS Device Driver Developer's Guide (SPRU616). Configure Mini-driver To create a DIO device object in a configuration script, first use the following syntax: var myUdev = bios.UDEV.create("myUdev");...
Page 121 DIO Adapter Description The mini-drivers described in the DSP/BIOS Device Driver Developer's Guide (SPRU616) are intended for use with the GIO module. However, the DIO driver allows them to be used with the SIO module instead of the GIO module. The following figure summarizes how modules are related in an application that uses the DIO driver and a mini-driver: Application...
Page 122 DIO Adapter calls to SIO_create fail. Setting this property to true reduces the application’s code size (so long as the application does not call MEM_alloc or its related functions elsewhere). Tconf Name: STATICCREATE Type: Bool Example: bios.DIO.STATICCREATE = false; DIO Object Properties The following properties can be set for a DIO device using the DIO Object Properties dialog in the DSP/BIOS Configuration Tool or in a Tconf script.
Page 123 DNL Driver DNL Driver Null driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 124 DOV Driver DOV Driver Stackable overlap driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 125 DOV Driver This causes SIO to open a stack of two devices. /overlap16 designates the device called overlap, and 16 tells the driver to use the last 16 MADUs of the previous frame as the first 16 MADUs of the next frame. codec specifies the name of the physical device which corresponds to the actual source for the data.
Page 126 DOV Driver To create the same streams statically (rather than dynamically with SIO_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.
Page 127 DPI Driver DPI Driver Pipe driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 128 DPI Driver And in the function for the other task: outStr = SIO_create("/pipe0", SIO_OUTPUT, bufsize, NULL); SIO_put(outStr, bufp, nmadus); or by adding with Tconf two streams that use pipe0, one in output mode (outStream) and the other one in input mode(inStream). Then, from the reader task call: extern SIO_Obj inStream;...
Page 129 DPI Driver mechanism works. When using this version of the DPI driver, the writer reclaims first the buffers issued by the reader rather than its own issued buffers, and vice versa. This version of the pipe driver is not suitable for applications in which buffers are broadcasted from a writer to several readers.
Page 130 DPI Driver named "pipe", you can call SIO_create to create pipe0, pipe1, and pipe2. Only integer numbers can be appended to the name. If this 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.
Page 131 DST Driver DST Driver Stackable split driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616). This driver is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 132 DST Driver Alternatively, you can create the stream with Tconf (rather than by calling SIO_create at run-time). To do so, first create and configure two user- defined devices called split and codec. Then, create an SIO object. Type 4/codec as the Device Control String. Select split from the Device list. Example 2: Conversely, you can open an output stream that accepts 1024-word buffers, but breaks them into 256-word buffers before passing them to...
Page 133 DTR Driver DTR Driver Stackable streaming transformer driver Important Note: This driver will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the IOM driver interface instead. See the DSP/BIOS Driver Developer’s Guide (SPRU616).
Page 134 DTR Driver ❏ device params ptr. Enter the name of a DTR_Params structure declared in your C application code. See the information following this list for details. The DTR_Params structure is defined in dtr.h as follows: ======== DTR_Params ======== */ typedef struct { /* device parameters */ struct {...
Page 135 DTR Driver if (user.fxn != NULL) { (*user.fxn)(user.arg, buffer, size); Data Streaming DTR transformer devices can be opened for input or output and use the same mode of I/O with the underlying streaming device. If a transformer is used as a data source, it inputs a buffer from the underlying streaming device and then transforms this data in place.
Page 136: Gbl Module
GBL Module GBL Module This module is the global settings manager. ❏ GBL_getClkin. Gets configured value of board input clock in KHz. Functions ❏ GBL_getFrequency. Gets current frequency of the CPU in KHz. ❏ GBL_getProcId. Gets configured processor ID used by MSGQ. ❏...
Page 137 GBL Module GBL Module The following Global Settings can be made: Properties ❏ Target Board Name. The name of the board or board family. Tconf Name: BOARDNAME Type: String Example: bios.GBL.BOARDNAME = "c55xx"; ❏ Processor ID (PROCID). ID used to communicate with other processors using the MSGQ Module.
Page 138 GBL Module ❏ Run-Time Support Library. The name of the run-time support (RTS) library to which the application is linked. These libraries are located in the <BIOS_INSTALL_DIR>\xdctools\packages\ti\targets tree. The library you select is used in the linker command file generated from the Tconf script when you build your application. Tconf Name: RTSLIB Type: String Example:...
Page 139 GBL Module In contrast, the Initialization function that may be specified for HOOK Module objects runs later and is intended for use in setting up data structures used by other functions of the same HOOK object. Tconf Name: USERINITFXN Type: Extern Example: bios.GBL.USERINITFXN = prog.extern("FXN_F_nop");...
Page 140 GBL_getClkin GBL_getClkin Get configured value of board input clock in KHz C Interface Syntax clkin = GBL_getClkin(Void); Parameters Void Return Value Uint32 clkin; /* CLKIN frequency */ Reentrant Description Returns the configured value of the board input clock (CLKIN) frequency in KHz.
Page 141 GBL_getFrequency GBL_getFrequency Get current frequency of the CPU in KHz C Interface Syntax frequency = GBL_getFrequency(Void); Parameters Void Return Value Uint32 frequency; /* CPU frequency in KHz */ Reentrant Description Returns the current frequency of the DSP CPU in an integer number of KHz.
Page 142 GBL_getProcId GBL_getProcId Get configured value of processor ID C Interface Syntax procid = GBL_getProcId(Void); Parameters Void Return Value Uint16 procid; /* processor ID */ Reentrant Description Returns the configured value of the processor ID (PROCID) for this processor. This numeric ID value is used by the MSGQ module when determining which processor to communicate with.
Page 143 GBL_getVersion GBL_getVersion Get DSP/BIOS version information C Interface Syntax version = GBL_getVersion(Void); Parameters Void Return Value Uint16 version; /* version data */ Reentrant Description Returns DSP/BIOS version information as a 4-digit hex number. For example: 0x5100. When comparing versions, compare the highest digits that are different. The digits in the version information are as follows: Bits Compatibility with Older DSP/BIOS Versions...
Page 144 GBL_setFrequency GBL_setFrequency Set frequency of the CPU in KHz C Interface Syntax GBL_setFrequency( frequency ); Parameters Uint32 frequency; /* CPU frequency in KHz */ Return Value Void Reentrant Description This function sets the value of the CPU frequency known to DSP/BIOS. Note that GBL_setFrequency does not affect the PLL, and therefore has no effect on the actual frequency at which the DSP is running.
Page 145 GBL_setProcId GBL_setProcId Set configured value of processor ID C Interface Syntax GBL_setProcId( procId ); Parameters Uint16 procId; /* processor ID */ Return Value Void Reentrant Description Sets the processor ID (PROCID) for this processor. This numeric ID value is used by the MSGQ module to determine which processor to communicate with.
Page 146: Gio Module
GIO Module GIO Module The GIO module is the Input/Output Module used with IOM mini-drivers as described in DSP/BIOS Device Driver Developer's Guide (SPRU616). ❏ GIO_abort. Abort all pending input and output. Functions ❏ GIO_control. Device specific control call. ❏ GIO_create. Allocate and initialize a GIO object. ❏...
Page 147 GIO Module /* Command codes for IOM_Packet */ #define IOM_READ #define IOM_WRITE #define IOM_ABORT #define IOM_FLUSH #define IOM_USER 128 /* 0-127 reserved for system */ /* Command codes reserved for control */ #define IOM_CHAN_RESET 0 /* reset channel only */ #define IOM_CHAN_TIMEDOUT 1 /* channel timeout occurred */ #define IOM_DEVICE_RESET...
Page 148 GIO Module typedef struct IOM_Packet { /* frame object */ QUE_Elem link; /* queue link */ addr; /* buffer address */ size_t size; /* buffer size */ misc; /* reserved for driver */ arg; /* user argument */ cmd; /* mini-driver command */ status;...
Page 149 GIO Module The following figure shows how modules are related in an application that uses the GIO module and an IOM mini-driver: Application typically TSK threads; SW I threads possible with custom ization DEV module GIO Module API (device driver table) IOM mini-driver (IOM_Fxns function table) The GIO module is the basis of communication between applications and...
Page 150 GIO Module ❏ Delete Function .The function the GIO module should use to delete a synchronization object. This function is typically SEM_delete. If you use another function, that function should have a prototype that matches that of SEM_delete: Void DELETEFXN(Ptr semHandle); Tconf Name: DELETEFXN Type: Extern Example:...
Page 151 GIO_abort GIO_abort Abort all pending input and output C Interface Syntax status = GIO_abort(gioChan); Parameters GIO_Handle gioChan; /* handle to an instance of the device */ Return Value status; /* returns IOM_COMPLETED if successful */ An application calls GIO_abort to abort all input and output from the Description device.
Page 152 GIO_control GIO_control Device specific control call C Interface status = GIO_control(gioChan, cmd, args); Syntax Parameters GIO_Handle gioChan; /* handle to an instance of the device */ cmd; /* control functionality to perform */ args; /* data structure to pass control information */ status;...
Page 153 GIO_create GIO_create Allocate and initialize a GIO object C Interface Syntax gioChan = GIO_create(name, mode, *status, chanParams, *attrs) Parameters String name /* name of the device to open */ mode /* mode in which the device is to be opened */ *status /* address to place driver return status */ chanParams /* optional */...
Page 154 GIO_create GIO_create returns a handle to the GIO_Obj object created upon a successful open. The handle returned by this call should be used by the application in subsequent calls to GIO functions. This function returns a NULL handle if the device could not be opened. For example, if a device is opened in a mode not supported by the device, this call returns a NULL handle.
Page 155 GIO_delete GIO_delete Delete underlying mini-drivers and free GIO object and its structures C Interface Syntax status = GIO_delete(gioChan); Parameters GIO_Handle gioChan; /* handle to device instance to be closed */ Return Value status; /* returns IOM_COMPLETED if successful */ An application calls GIO_delete to close a communication channel Description opened prior to this call with GIO_create.
Page 156 GIO_flush GIO_flush Drain output buffers and discard any pending input C Interface Syntax status = GIO_flush(gioChan); Parameters GIO_Handle gioChan; /* handle to an instance of the device */ Return Value status; /* returns IOM_COMPLETED if successful */ An application calls GIO_flush to flush the input and output channels of Description the device.
Page 157 GIO_new GIO_new Initialize a GIO object with pre-allocated memory C Interface Syntax gioChan = GIO_new(gioChan, name, mode, *status, optArgs, packetBuf[], syncObject, *attrs); Parameters GIO_Handle gioChan /* Handle to GIO Obj */ String name /* name of the device to open */ mode /* mode in which the device is to be opened */ *status...
Page 158 GIO_new The "optArgs" parameter is a pointer that may be used to pass device or domain-specific arguments to the mini-driver. The contents at the specified address are interpreted by the mini-driver in a device-specific manner. Use the "packetBuf[]" array to pass a list of IOM_Packet items. The number of items should match the nPackets member of the GIO_Attrs structure passed to the "attrs"...
Page 159 GIO_read GIO_read Synchronous read command C Interface Syntax status = GIO_read(gioChan, bufp, *pSize); Parameters GIO_Handle gioChan; /* handle to an instance of the device */ bufp /* pointer to data structure for buffer data */ size_t *pSize /* pointer to size of bufp structure */ Return Value status;...
Page 160 GIO_read ❏ This function can be called only after the device has been loaded and Constraints and Calling Context initialized. The handle supplied 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.
Page 161 GIO_submit GIO_submit Submit a GIO packet to the mini-driver C Interface Syntax status = GIO_submit(gioChan, cmd, bufp, *pSize, *appCallback); Parameters GIO_Handle gioChan; /* handle to an instance of the device */ /* specified mini-driver command */ bufp /* pointer to data structure for buffer data */ size_t *pSize /* pointer to size of bufp structure */...
Page 162 GIO_submit The appCallback parameter points to either a callback structure that contains the callback function to be called when the request completes, or it points to NULL, which causes the call to be synchronous. When a queued request is completed, the callback routine (if specified) is invoked (i.e.
Page 163 GIO_write GIO_write Synchronous write command C Interface Syntax status = GIO_write(gioChan, bufp, *pSize); Parameters GIO_Handle gioChan; /* handle to an instance of the device */ bufp /* pointer to data structure for buffer data */ size_t *pSize /* pointer to size of bufp structure */ Return Value status;...
Page 164 GIO_write ❏ This function can be called only after the device has been loaded and Constraints and Calling Context initialized. The handle supplied should have been obtained with a prior call to GIO_create or GIO_new. ❏ This function can be called within the program’s main() function only if the GIO channel is asynchronous (non-blocking).
Page 165: Hook Module
HOOK Module HOOK Module The HOOK module is the Hook Function manager. ❏ HOOK_getenv. Get environment pointer for a given HOOK and TSK Functions combination. ❏ HOOK_setenv. Set environment pointer for a given HOOK and TSK combination. Constants, Types, typedef Int HOOK_Id; /* HOOK instance id */ and Structures typedef Void (*HOOK_InitFxn)(HOOK_Id id);...
Page 166 HOOK Module In addition, each HOOK object can maintain private data environments for each task for use by its hook functions. The key execution points at which hook functions can be executed are during program initialization and at several TSK execution points. The HOOK module manages objects that reference a set of hook functions.
Page 167 HOOK Module HOOK Manager There are no global properties for the HOOK manager. HOOK objects Properties are placed in the C Variables Section (.bss). HOOK Object The following properties can be set for a HOOK object in the DPI Object Properties Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script.
Page 168 HOOK Module ❏ Delete function . The name of a function to call when any task is deleted at run-time with TSK_delete. Tconf Name: deleteFxn Type: Extern Example: myHook.deleteFxn = prog.extern("myDelete"); ❏ Exit function . The name of a function to call when any task exits. The TSK_exit topic describes the Exit function.
Page 169 HOOK_getenv HOOK_getenv Get environment pointer for a given HOOK and TSK combination C Interface Syntax environ = HOOK_getenv(task, id); TSK_Handle task; /* task object handle */ Parameters HOOK_Id /* HOOK instance id */ environ; /* environment pointer */ Return Value Reentrant Description HOOK_getenv returns the environment pointer associated with the...
Page 170 HOOK_setenv HOOK_setenv Set environment pointer for a given HOOK and TSK combination C Interface Syntax HOOK_setenv(task, id, environ); Parameters TSK_Handle task; /* task object handle */ HOOK_Id /* HOOK instance id */ environ; /* environment pointer */ Return Value Void Reentrant HOOK_setenv sets the environment pointer associated with the specified Description...
Page 171: Hst Module
HST Module HST Module Important Note: This module is being deprecated and will no longer be supported in the next major release of DSP/BIOS. The HST module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 172 HST Module called the source) read data from the host to the target. Output channels (also called the sink) transfer data from the target to the host. Note: HST channel names cannot begin with a leading underscore ( _ ). Each host channel is internally implemented using a data pipe (PIP) object.
Page 173 HST Module halted (for example, at a breakpoint). The program code size is smaller when the Host Link Type is set to None because RTDX code is not included in the program. Tconf Name: HOSTLINKTYPE Type: EnumString Options: "RTDX", "NONE" Example: bios.HST.HOSTLINKTYPE = "RTDX";...
Page 174 HST Module ❏ framesize. The length of each frame (in words) Tconf Name: frameSize Type: Int16 Example: myHst.frameSize = 128; ❏ numframes. The number of frames Tconf Name: numFrames Type: Int16 Example: myHst.numFrames = 2; ❏ statistics. Set this property to true if you want to monitor this channel with an STS object.
Page 175 HST_getpipe HST_getpipe Get corresponding pipe object Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. The HST module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 176: Hwi Module
HWI Module 2.10 HWI Module The HWI module is the hardware interrupt manager. ❏ HWI_disable. Disable hardware interrupts Functions ❏ HWI_dispatchPlug. Plug the HWI dispatcher ❏ HWI_enable. Enable hardware interrupts ❏ HWI_enter. Hardware ISR prolog ❏ HWI_exit. Hardware ISR epilog ❏...
Page 177 HWI Module Instance Configuration Parameters HWI instances are provided as a default part of the configuration and cannot be created. In the items that follow, HWI_INT* may be any provided instance. Default values for many HWI properties are different for each instance C55x Name Type Default (Enum Options)
Page 178 HWI Module Interrupt routines can be written completely in assembly, completely in C, or in a mix of assembly and C. In order to support interrupt routines written completely in C, an HWI dispatcher is provided that performs the requisite prolog and epilog for an interrupt routine. Note: RTS Functions Callable from TSK Threads Only Many runtime support (RTS) functions use lock and unlock functions to prevent reentrancy.
Page 179 HWI Module Notes In the following notes, references to the usage of HWI_enter/HWI_exit also apply to usage of the HWI dispatcher since, in effect, the dispatcher calls HWI_enter/HWI_exit. ❏ Do not call SWI_disable or SWI_enable within an HWI function. ❏ Do not call HWI_enter, HWI_exit, or any other DSP/BIOS functions from a non-maskable interrupt (NMI) service routine.
Page 180 HWI Module DSP/BIOS and NMI Support You should use the NMI interrupt only if tasking is disabled (that is, in a SWI-only system) or if tasking is enabled but all the task stacks and the ISR stack are in the same memory page. This is because it is not possible to atomically modify SP, SSP, and the page register such that the whole operation is protected from an NMI (non-maskable interrupt).
Page 181 HWI Module address is located in ROM space, it is not programmable. DSP/BIOS does not report an error if it is unable to modify the value at this address to set the specified stack mode. Tconf Name: STACKMODE Type: EnumString Options: "C54X_STK", "USE_RETA", "NO_RETA"...
Page 182 HWI Module at least partially in assembly language. Within an HWI function that 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. HWI functions can post SWIs, but they do not run until your HWI function (or the dispatcher) calls the HWI_exit assembly macro, which must be the last statement in any HWI function that calls HWI_enter.
Page 183 HWI Module ❏ operation . The operation to be performed on the value monitored. You can choose one of several STS operations. Tconf Name: operation Type: EnumString Options: "STS_add(*addr)", "STS_delta(*addr)", "STS_add(- *addr)", "STS_delta(-*addr)", "STS_add(|*addr|)", "STS_delta(|*addr|)" Example: bios.HWI_INT2.operation = "STS_add(*addr)"; ❏ Use Dispatcher . A check box that controls whether the HWI dispatcher is used.
Page 184 HWI Module ❏ Interrupt Bit Mask . An integer property that is writable when the interrupt mask is set to "bitmask". This should be a hexadecimal integer bitmask specifying the interrupts to disable. (For ’C55x, separate properties are provided for IER0 and IER1.) For OMAP 2320/2420, these properties disable only level 1 interrupts.
Page 185 HWI Module ❏ L2 Interrupt Bit Mask MIR1 . This property is similar to the previous one, except that it defines a bitmask of level 2 interrupts 32-63 for OMAP 2320 only. Tconf Name: mir1mask Type: Numeric Example: bios.HWI_INT2.mir1mask = 0x00000000; ❏...
Page 186: Hwi Interrupts For The 'C55X
HWI Module Table 2-3. HWI interrupts for the ‘C55x Name Interrupt Type HWI_RESET Reset interrupt. HWI_NMI Non-maskable interrupt. (See page 2–152) HWI_INT2 Maskable (IER0, bit2) hardware interrupt. HWI_INT3 Maskable (IER0, bit3) hardware interrupt. HWI_TINT Timer interrupt. (IER, bit4) HWI_INT5 Maskable (IER0, bit5) hardware interrupt through through HWI_INT15...
Page 187 HWI_disable HWI_disable Disable hardware interrupts C Interface Syntax oldST1 = HWI_disable(); Parameters Void Return Value Uns oldST1; Reentrant Description HWI_disable disables hardware interrupts by setting the intm bit in the status register. Call HWI_disable before a portion of a function that needs to run without interruption.
Page 188 HWI_dispatchPlug HWI_dispatchPlug Plug the HWI dispatcher C Interface Syntax HWI_dispatchPlug(vecid, fxn, attrs); Parameters vecid; /* interrupt id */ fxn; /* pointer to HWI function */ HWI_Attrs *attrs /*pointer to HWI dispatcher attributes */ Return Value Void Reentrant Description HWI_dispatchPlug fills the HWI dispatcher table with the function specified by the fxn parameter and the attributes specified by the attrs parameter.
Page 189 HWI_dispatchPlug The mirmask is a bitmask that specifies which level 2 interrupts to mask while executing the HWI. This field contains a 32-bit mask in which each bit corresponds to level 2 interrupts 0-31. The default value for each interrupt is to mask only the current level 2 interrupt. (OMAP 2320/2420 only) The mir1mask is a bitmask that specifies which level 2 interrupts to mask while executing the HWI.
Page 190 HWI_enable HWI_enable Enable interrupts C Interface Syntax HWI_enable(); Parameters Void Return Value Void Reentrant Description HWI_enable enables hardware interrupts by clearing the intm bit in the status register. Hardware interrupts are enabled unless a call to HWI_disable disables them. DSP/BIOS enables hardware interrupts after the program’s main() function runs.
Page 191 HWI_enter HWI_enter Hardware ISR prolog C Interface Syntax none Parameters none Return Value none Assembly Interface Syntax HWI_enter C55_AR_DR_X_MASK, C55_ACC_X_MASK, \ C55_MISC1_X_MASK, C55_MISC2_X_MASK, C55_MISC3_X_MASK, \ IER0DISABLEMASK, IER1DISABLEMASK OMAP 2320 only: HWI_enter C55_AR_DR_X_MASK, C55_ACC_X_MASK, \ C55_MISC1_X_MASK, C55_MISC2_X_MASK, C55_MISC3_X_MASK, \ IER0DISABLEMASK, IER1DISABLEMASK, MIRDISABLEMASK, \ MIR1DISABLEMASK OMAP 2420 only: HWI_enter C55_AR_DR_X_MASK, C55_ACC_X_MASK, \...
Page 192 HWI_enter HWI_enter is used by HWIs that are user-dispatched, as opposed to HWIs that are handled by the HWI dispatcher. HWI_enter must not be issued by HWIs that are handled by the HWI dispatcher. If the HWI dispatcher is not used by an HWI object, HWI_enter must be used in the HWI before any DSP/BIOS API calls that could trigger other DSP/BIOS objects, such as posting a SWI or semaphore.
Page 193 HWI_enter See c55.h55 for constants defined for working with these masks. If your HWI is coded in C, it is recommended that you use the SAVE_BY_CALLER masks provided in c55.h55. Note: The C55_saveCcontext, C55_restoreCcontext C55_saveBiosContext and C55_restoreBiosContext macros preserve processor register context per C and DSP/BIOS requirements, respectively.
Page 194 HWI_enter ❏ preserves the specified set 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 ❏...
Page 195 HWI_exit HWI_exit Hardware ISR epilog C Interface Syntax none Parameters none Return Value none Assembly Interface Syntax 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 OMAP 2320 only: HWI_enter C55_AR_DR_X_MASK, C55_ACC_X_MASK, \ C55_MISC1_X_MASK, C55_MISC2_X_MASK, C55_MISC3_X_MASK, \ IER0RESTOREMASK, IER1RESTOREMASK, MIRRESTOREMASK, \ MIR1RESTOREMASK OMAP 2420 only: HWI_enter C55_AR_DR_X_MASK, C55_ACC_X_MASK, \...
Page 196 HWI_exit HWI_exit restores the registers specified by C55_AR_DR_X_MASK, C55_ACC_X_MASK, C55_MISC1_X_MASK, C55_MISC2_X_MASK, and C55_MISC3_X_MASK. These masks are used to specify the set of registers that were saved by HWI_enter. HWI_enter and HWI_exit must surround all statements in any DSP/BIOS assembly language HWIs that call C functions only for HWIs that are not dispatched by the HWI dispatcher.
Page 197 HWI_exit ❏ This API cannot be called from the program’s main() function. ❏ This API cannot be called from a SWI, TSK, or IDL function. ❏ This API cannot be called from a CLK function. Examples Example #1: Calling a C function from within an HWI_enter/HWI_exit: Specify all registers in the C convention class, save-by-caller.
Page 198 HWI_isHWI HWI_isHWI Check to see if called in the context of an HWI C Interface Syntax result = HWI_isHWI(Void); Parameters Void Return Value Bool result; /* TRUE if in HWI context, FALSE otherwise */ Reentrant Description This macro returns TRUE when it is called within the context of an HWI or CLK function.
Page 199 HWI_restore HWI_restore Restore global interrupt enable state C Interface Syntax HWI_restore(oldST1); Parameters oldST1; Returns Void Reentrant Description HWI_restore sets the intm bit in the st1 register using bit 11 of the oldst1 parameter. If bit 11 is 1, the intm bit is not modified. If bit 11 is 0, the intm bit is set to 0, which enables interrupts.
Page 200: Idl Module
IDL Module 2.11 IDL Module The IDL module is the idle thread manager. ❏ IDL_run. Make one pass through idle functions. Functions Configuration The following list shows the properties that can be configured in a Tconf Properties script, along with their types and default values. For details, see the IDL Manager Properties and IDL Object Properties headings.
Page 201 IDL Module IDL context. IDL functions can be written in C or assembly and must follow the C calling conventions described in the compiler manual. When RTA is enabled (see page 2–111), an application contains an IDL_cpuLoad object, which runs a function that provides data about the CPU utilization of the application.
Page 202 IDL Module ❏ Idle Loop Instruction Count . This is the number of instruction cycles required to perform the IDL loop and the default IDL functions (LNK_dataPump, RTA_dispatcher, IDL_cpuLoad) that communicate with the host. Since these functions are performed whenever no other processing is needed, background processing is subtracted from the CPU load before it is displayed.
Page 203 IDL_run IDL_run Make one pass through idle functions C Interface Syntax IDL_run(); Parameters Void Return Value Void IDL_run makes one pass through the list of configured IDL objects, Description calling one function after the next. IDL_run returns after all IDL functions have been executed one time.
Page 204: Lck Module
LCK Module 2.12 LCK Module The LCK module is the resource lock manager. ❏ LCK_create. Create a resource lock Functions ❏ LCK_delete. Delete a resource lock ❏ LCK_pend. Acquire ownership of a resource lock ❏ LCK_post. Relinquish ownership of a resource lock Constants, Types, typedef struct LCK_Obj *LCK_Handle;...
Page 205 LCK Module ❏ Object Memory . The memory segment that contains the LCK objects. Tconf Name: OBJMEMSEG Type: Reference Example: bios.LCK.OBJMEMSEG = prog.get("myMEM"); LCK Object Properties To create a LCK object in a configuration script, use the following syntax. The Tconf examples that follow assume the object has been created as shown here.
Page 206 LCK_create LCK_create Create a resource lock C Interface Syntax lock = LCK_create(attrs); Parameters LCK_Attrs attrs; /* pointer to lock attributes */ Return Value LCK_Handle lock; /* handle for new lock object */ LCK_create creates a new lock object and returns its handle. The lock Description has no current owner and its corresponding resource is available for acquisition through LCK_pend.
Page 207 LCK_delete LCK_delete Delete a resource lock C Interface Syntax LCK_delete(lock); Parameters LCK_Handle lock; /* lock handle */ Return Value Void LCK_delete uses MEM_free to free the lock referenced by lock. Description LCK_delete calls MEM_free to delete the LCK object. MEM_free must acquire a lock to the memory before proceeding.
Page 208 LCK_pend LCK_pend Acquire ownership of a resource lock C Interface Syntax status = LCK_pend(lock, timeout); Parameters LCK_Handle lock; /* lock handle */ timeout; /* return after this many system clock ticks */ Return Value Bool status; /* TRUE if successful, FALSE if timeout */ LCK_pend acquires ownership of lock, which grants the current task Description exclusive access to the corresponding resource.
Page 209 LCK_pend The C++ new operator calls malloc, which in turn calls LCK_pend. As a result, the new operator cannot be used in the context of a SWI or HWI thread. ❏ The lock must be a handle for a resource lock object created through Constraints and Calling Context a prior call to LCK_create.
Page 210 LCK_post LCK_post Relinquish ownership of a resource LCK C Interface Syntax LCK_post(lock); Parameters LCK_Handle lock; /* lock handle */ Return Value Void LCK_post relinquishes ownership of lock, and resumes execution of the Description first task (if any) awaiting availability of the corresponding resource. If the current task calls LCK_pend more than once with lock, ownership remains with the current task until LCK_post is called an equal number of times.
Page 211: Log Module
LOG Module 2.13 LOG Module The LOG module captures events in real time. ❏ LOG_disable. Disable the system log. Functions ❏ LOG_enable. Enable the system log. ❏ LOG_error. Write a user error event to the system log. ❏ LOG_event. Append unformatted message to message log. ❏...
Page 212 LOG Module You can add messages to user logs or the system log by using LOG_printf or LOG_event. To reduce execution time, log data is always formatted on the host. LOG_error writes a user error event to the system log. This operation is not affected by any TRC trace bits;...
Page 213 LOG Module ❏ bufseg . The name of a memory segment to contain the log buffer. Tconf Name: bufSeg Type: Reference Example: myLog.bufSeg = prog.get("myMEM"); ❏ buflen . The length of the log buffer (in words). Tconf Name: bufLen Type: EnumInt Options: 0, 8, 16, 32, 64, ..., 32768 Example:...
Page 214 LOG_disable LOG_disable Disable a message log C Interface Syntax LOG_disable(log); Parameters LOG_Handle log; /* log object handle */ Return Value Void Reentrant 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 2-186...
Page 215 LOG_enable LOG_enable Enable a message log C Interface Syntax LOG_enable(log); Parameters LOG_Handle log; /* log object handle */ Return Value Void Reentrant 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 Application Program Interface...
Page 216 LOG_error LOG_error Write an error message to the system log C Interface Syntax LOG_error(format, arg0); Parameters String format; /* printf-style format string */ arg0; /* copied to second word of log record */ Return Value Void Reentrant Description LOG_error writes a program-supplied error message to the system log, which is defined in the default configuration by the LOG_system object.
Page 217 LOG_event LOG_event Append an unformatted message to a message log C Interface Syntax LOG_event(log, arg0, arg1, arg2); Parameters LOG_Handle log; /* log objecthandle */ arg0; /* copied to second word of log record */ arg1; /* copied to third word of log record */ arg2;...
Page 218 LOG_message LOG_message Write a program-supplied message to the system log C Interface Syntax LOG_message(format, arg0); Parameters String format; /* printf-style format string */ arg0; /* copied to second word of log record */ Return Value Void Reentrant Description LOG_message writes a program-supplied message to the system log, provided that both the host and target trace bits are enabled.
Page 219: Conversion Characters For Log_Printf
LOG_printf LOG_printf Append a formatted message to a message log C Interface Syntax LOG_printf(log, format); LOG_printf(log, format,arg0); LOG_printf(log, format, arg0, arg1); Parameters LOG_Handle log; /* log object handle */ String format; /* printf format string */ arg0; /* value for first format string token */ arg1;...
Page 220 LOG_printf Conversion Character Description Character string This character can only be used with constant string pointers. That is, the string must appear in the source and be passed to LOG_printf . For example, the following is supported: char *msg = "Hello world!"; LOG_printf(&trace, "%s", msg);...
Page 221 LOG_printf LOG_printf(&trace, "total count = 0x%04x%04x", (Int)(maincount >> 16), (Int)(maincount & 0xffff)); The 0x%04x%04x format string used in this example causes a literal string of "0x" to precede the value to indicate that it is a hex value. Then, each %04x tells LOG_printf to display the value as hex, padding to 4 characters with leading zeros.
Page 222 LOG_reset LOG_reset Reset a message log C Interface Syntax LOG_reset(log); LOG_Handle /* log object handle */ Parameters Return Value Void Reentrant Description LOG_reset enables the logging mechanism and allows the log buffer to be modified starting from the beginning of the buffer, with sequence number starting from 0.
Page 223: Mbx Module
MBX Module 2.14 MBX Module The MBX module is the mailbox manager. ❏ MBX_create. Create a mailbox Functions ❏ MBX_delete. Delete a mailbox ❏ MBX_pend. Wait for a message from mailbox ❏ MBX_post. Post a message to mailbox Constants, Types, typedef struct MBX_Obj *MBX_Handle;...
Page 224 MBX Module MBX_pend waits for a message from a mailbox. Its timeout parameter allows the task to wait until a timeout. A timeout value of SYS_FOREVER causes the calling task to wait indefinitely for a message. A timeout value of zero (0) causes MBX_pend to return immediately. MBX_pend’s return value indicates whether the mailbox was signaled successfully.
Page 225 MBX_create MBX_create Create a mailbox C Interface Syntax mbx = MBX_create(msgsize, mbxlength, attrs); Parameters size_t msgsize; /* size of message */ mbxlength;/* length of mailbox */ MBX_Attrs *attrs; /* pointer to mailbox attributes */ Return Value MBX_Handle mbx; /* mailbox object handle */ Description MBX_create creates a mailbox object which is initialized to contain up to mbxlength messages of size msgsize.
Page 226 MBX_delete MBX_delete Delete a mailbox C Interface Syntax MBX_delete(mbx); Parameters MBX_Handle mbx; /* mailbox object handle */ Return Value Void MBX_delete frees the mailbox object referenced by mbx. Description MBX_delete calls MEM_free to delete the MBX 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 context switch.
Page 227 MBX_pend MBX_pend Wait for a message from mailbox C Interface Syntax status = MBX_pend(mbx, msg, timeout); Parameters MBX_Handle mbx; /* mailbox object handle */ msg; /* message pointer */ timeout; /* return after this many system clock ticks */ Return Value Bool status;...
Page 228 MBX_post MBX_post Post a message to mailbox C Interface Syntax status = MBX_post(mbx, msg, timeout); Parameters MBX_Handle mbx; /* mailbox object handle */ msg; /* message pointer */ timeout; /* return after this many system clock ticks */ Return Value Bool status;...
Page 229: Mem Module
MEM Module 2.15 MEM Module The MEM module is the memory segment manager. ❏ MEM_alloc. Allocate from a memory segment. Functions ❏ MEM_calloc. Allocate and initialize to 0. ❏ MEM_define. Define a new memory segment. ❏ MEM_free. Free a block of memory. ❏...
Page 230 MEM Module Module Configuration Parameters C55x Name Type Default REUSECODESPACE Bool false ARGSSIZE Numeric x0008 STACKSIZE Numeric 0x0400 SYSSTACKSIZE Numeric 0x0100 NOMEMORYHEAPS Bool false BIOSOBJSEG Reference prog.get("DARAM") MALLOCSEG Reference prog.get("DARAM") ARGSSEG Reference prog.get("DARAM") STACKSEG Reference prog.get("DARAM") SYSSTACKSEG Reference prog.get("DARAM") GBLINITSEG Reference prog.get("SARAM") TRCDATASEG...
Page 231 MEM Module C55x Name Type Default LOADHWISEG Reference prog.get("SARAM") LOADHWIVECSEG Reference prog.get("VECT") LOADRTDXTEXTSEG Reference prog.get("SARAM") Instance Configuration Parameters Name Type Default (Enum Options) comment String "<add comments here>" base Numeric 0x000000 Numeric 0x000000 createHeap Bool true heapSize Numeric 0x03f80 enableHeapLabel Bool false heapLabel...
Page 232 MEM Module The MEM Manager property, Segment for malloc()/free(), is used to implement the standard C malloc, free, and calloc functions. These functions actually use the MEM functions (with segid = Segment for malloc/free) to allocate and free memory. Note: The MEM module does not set or configure hardware registers associated with a DSP’s memory subsystem.
Page 233 MEM Module ❏ Stack Size . The size of the data stack in MADUs. The upper-left corner of the DSP/BIOS Configuration Tool window shows the estimated minimum global stack size required for this application (as a decimal number). This size is shown as a hex value in Minimum Addressable Data Units (MADUs).
Page 234 MEM Module ❏ Segment For malloc() / free() . The memory segment from which space is allocated when a program calls malloc and from which space is freed when a program calls free. If you select MEM_NULL for this property, dynamic memory allocation at run-time is disabled. Tconf Name: MALLOCSEG Type: Reference Example:...
Page 235 MEM Module ❏ DSP/BIOS Conf Sections (.obj) . The memory segment containing configuration properties that can be read by the target program. Tconf Name: OBJSEG Type: Reference Example: bios.MEM.OBJSEG = prog.get("myMEM"); ❏ BIOS Code Section (.bios) . The memory segment containing the BIOS Code tab DSP/BIOS code.
Page 236 MEM Module ❏ Text Section (.text) . The memory segment containing the executable code, string literals, and compiler-generated constants. This segment can be located in ROM or RAM. Tconf Name: TEXTSEG Type: Reference Example: bios.MEM.TEXTSEG = prog.get("myMEM"); ❏ Switch Jump Tables (.switch) . The memory segment containing the jump tables for switch statements.
Page 237 MEM Module GROUP { .const: {} .printf (COPY): {} } > IRAM Tconf Name: CONSTSEG Type: Reference Example: bios.MEM.CONSTSEG = prog.get("myMEM"); ❏ Data Section (.data) . This memory segment contains program data. This segment can be located in ROM or RAM. Tconf Name: DATASEG Type: Reference Example:...
Page 238 MEM Module ❏ Load Address - Startup Code Section (.sysinit) . The memory segment containing the load allocation of the section that contains DSP/BIOS startup initialization code. Tconf Name: LOADSYSINITSEG Type: Reference Example: bios.MEM.LOADSYSINITSEG = prog.get("myMEM"); ❏ Load Address - DSP/BIOS Init Tables (.gblinit) . The memory segment containing the load allocation of the section that contains the DSP/BIOS global initialization tables.
Page 239 MEM Module ❏ Load Address - C Function Initialization Table (.pinit) . The memory segment containing the load allocation of the section that contains the table of global object constructors. Tconf Name: LOADPINITSEG Type: Reference Example: bios.MEM.LOADPINITSEG = prog.get("myMEM"); ❏ Load Address - Constant Sections (.const, .printf) . The memory segment containing the load allocation of the sections that contain string constants, data defined with the const C qualifier, and other constant strings used by the Real-Time Analysis tools.
Page 240 MEM Module To create a MEM object in a configuration script, use the following syntax. The Tconf examples that follow assume the object has been created as shown here. var myMem = bios.MEM.create("myMem"); The following properties can be set for a MEM object in the MEM Object Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏...
Page 241: Typical Memory Segments For C5000 Boards
MEM Module A heap can potentially be sized to cross a 64K page boundary. See the MEM_alloc topic for information about the effects of page boundaries on heaps. Tconf Name: heapSize Type: Numeric Example: myMem.heapSize = 0x03f80; ❏ enter a user defined heap identifier . If this property is set to true, you can define your own identifier label for this heap.
Page 242 MEM_alloc MEM_alloc Allocate from a memory segment C Interface Syntax addr = MEM_alloc(segid, size, align); segid; /* memory segment identifier */ Parameters size_t size; /* block size in MADUs */ size_t align; /* block alignment */ Void *addr; /* address of allocated block of memory */ Return Value Description MEM_alloc allocates a contiguous block of storage from the memory...
Page 243: Myseg Heap Initial Memory Map
MEM_alloc When using the large memory model, the MEM module divides heaps that cross page boundaries into memory blocks that do not cross boundaries. As a result, MEM_alloc and MEM_free can only allocate and free memory within a single memory block, and the largest block that MEM_alloc can allocate in any case is 64K words (0x10000).
Page 244: Myseg Memory Map After Allocation
MEM_alloc MEM_alloc allocates memory from the first available memory block that is large enough. The memory block with the lowest address is the first available. In our example, the memory block with base address 2:F000 and length 0x1000 is the first available memory block. MEM_alloc gets memory sections from the bottom of a memory block.
Page 245: Myseg Memory Map After Modified Allocation
MEM_alloc memory block has a size of 0x8000, and is large enough for this allocation. So, P1 points to a block from 4:2000 to 4:7FFF. ❏ P2 = MEM_alloc(MYSEG, 0x1800, 0); This call requests 0x1800 words. Blocks 1 and 2 are again too small. The last block has 0x2000 words remaining, and can accommodate this allocation.
Page 246 MEM_alloc ❏ P2 is allocated from 3:8800 to 3:9FFF. ❏ P3 is not allocated because no unallocated memory blocks are large enough to hold 0xFF80. ❏ P4 is allocated from 2:F800 to 2:FFFF. As a result of page boundary limitations on MEM_alloc, you should follow these guidelines when using large heaps and multiple MEM_alloc calls: ❏...
Page 247 MEM_calloc MEM_calloc Allocate from a memory segment and set value to 0 C Interface Syntax addr = MEM_calloc(segid, size, align) Parameters segid; /* memory segment identifier */ size_t size; /* block size in MADUs */ size_t align; /* block alignment */ Return Value Void *addr;...
Page 248 MEM_define MEM_define Define a new memory segment C Interface Syntax segid = MEM_define(base, length, attrs); Parameters base; /* base address of new segment */ MEM_sizep length; /* length (in MADUs) of new segment */ MEM_Attrs *attrs; /* segment attributes */ Return Value segid;...
Page 249 MEM_define ❏ 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. MEM_redefine See Also MEM_undefine Application Program Interface 2-221...
Page 250 MEM_free MEM_free Free a block of memory C Interface Syntax status = MEM_free(segid, addr, size); segid; /* memory segment identifier */ Parameters addr; /* block address pointer */ size_t size; /* block length in MADUs*/ Bool status; /* TRUE if successful */ Return Value Description MEM_free places the memory block specified by addr and size back into...
Page 251 MEM_getBaseAddress MEM_getBaseAddress Get base address of a memory heap C Interface Syntax addr = MEM_getBaseAddress(segid); Parameters segid; /* memory segment identifier */ Return Value addr; /* heap base address pointer */ MEM_getBaseAddress returns the base address of the memory heap Description with the segment ID specified by the segid parameter.
Page 252 MEM_increaseTableSize MEM_increaseTableSize Increase the internal MEM table size C Interface Syntax status = MEM_increaseTableSize(numEntries); numEntries; /* number of segments to increase table by */ Parameters Return Value status; /* TRUE if successful */ Reentrant Description MEM_increaseTableSize allocates numEntries of undefined memory segments.
Page 253 MEM_redefine MEM_redefine Redefine an existing memory segment C Interface Syntax MEM_redefine(segid, base, length); Parameters segid; /* segment to redefine */ base; /* base address of new block */ MEM_sizep length; /* length (in MADUs) of new block */ Return Value Void Reentrant Description...
Page 254 MEM_stat MEM_stat Return the status of a memory segment C Interface Syntax status = MEM_stat(segid, statbuf); Parameters segid; /* memory segment identifier */ MEM_Stat *statbuf; /* pointer to stat buffer */ Return Value Bool status; /* TRUE if successful */ Description MEM_stat returns the status of the memory segment specified by segid in the status structure pointed to by statbuf.
Page 255 MEM_undefine MEM_undefine Undefine an existing memory segment C Interface Syntax MEM_undefine(segid); Parameters segid; /* segment to undefine */ Return Value Void Reentrant Description MEM_undefine removes a memory segment from the internal memory tables. Once a memory segment has been undefined, the segid cannot be used in any of the MEM APIs (except MEM_stat).
Page 256 MEM_valloc MEM_valloc Allocate from a memory segment and set value C Interface Syntax addr = MEM_valloc(segid, size, align, value); Parameters segid; /* memory segment identifier */ size_t size; /* block size in MADUs */ size_t align; /* block alignment */ Char value;...
Page 257: Msgq Module
MSGQ Module 2.16 MSGQ Module The MSGQ module allows for the structured sending and receiving of variable length messages. This module can be used for homogeneous or heterogeneous multi-processor messaging. ❏ MSGQ_alloc. Allocate a message. Performed by writer. Functions ❏ MSGQ_close. Closes a message queue. Performed by reader. ❏...
Page 258 MSGQ Module MSGQ_Attrs MSGQ_ATTRS = { NULL, /* notifyHandle */ (MSGQ_Pend)SYS_zero, /* NOP pend */ FXN_F_nop /* NOP post */ /* Attributes for message queue location */ typedef struct MSGQ_LocateAttrs { timeout; } MSGQ_LocateAttrs; MSGQ_LocateAttrs MSGQ_LOCATEATTRS = {SYS_FOREVER}; /* Attrs for asynchronous message queue location */ typedef struct MSGQ_LocateAsyncAttrs { Uint16 poolId;...
Page 259 MSGQ Module /* Transport object */ typedef struct MSGQ_TransportObj { MSGQ_MqtInit initFxn; /* Transport init func */ MSGQ_TransportFxns *fxns; /* Interface funcs */ params; /* Setup parameters */ object; /* Transport-specific object */ Uint16 procId; /* Processor Id talked to */ } MSGQ_TransportObj;...
Page 260: Writers And Reader Of A Message Queue
MSGQ Module Messages are sent and received via a message queue . A reader is a thread that gets (reads) messages from a message queue. A writer is a thread that puts (writes) a message to a message queue. Each message queue has one reader and can have many writers.
Page 261: Components Of The Msgq Architecture
MSGQ Module ❏ Allocators. Messages sent via MSGQ must be allocated by an allocator. The allocator determines where and how the memory for the message is allocated. For more about allocators, see the DSP/BIOS User’s Guide (SPRU423F). ❏ Transports. Transports are responsible for locating and sending messages with other processors.
Page 262 MSGQ Module ❏ MSGQ_open ❏ MSGQ_get ❏ MSGQ_free ❏ MSGQ_close A writer calls the following APIs: ❏ MSGQ_locate or MSGQ_locateAsync ❏ MSGQ_alloc ❏ MSGQ_put ❏ MSGQ_release Wherever possible, the MSGQ APIs have been written to have a deterministic execution time. This allows application designers to be certain that messaging will not consume an unknown number of cycles.
Page 263 MSGQ Module typedef struct MSGQ_Config { MSGQ_Obj *msgqQueues; /* Array of message queue handles */ MSGQ_TransportObj *transports; /* Array of transports */ Uint16 numMsgqQueues; /* Number of message queue handles*/ Uint16 numProcessors; /* Number of processors */ Uint16 startUninitialized; /* First msgq to init */ MSGQ_Queue errorQueue;...
Page 264 MSGQ Module The following table describes the fields in the MSGQ_TransportObj structure: 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 transport's interface functions. params Pointer to the transport's parameters.
Page 265 MSGQ Module Managing Transports As described in the previous section, MSGQ uses an array of transports at Run-Time of type MSGQ_TransportObj in the MSGQ_config variable. This array is processor ID based. For example, MSGQ_config->transports[0] is the transport to processor 0. Therefore, if a single binary is used on multiple processors, the array must be changed at run-time.
Page 266 MSGQ Module transports[0].initFxn = ... transports[0].fxns = ... transports[0].object = ... transports[0].params = ... transports[0].procId = 0; transports[1] = MSGQ_NOTRANSPORT;//no self-transport transports[2].initFxn = ... transports[2].fxns = ... transports[2].procId = 2; MSGQ_config.transport = transports; Note that some of the parameters may not be able to be determined easily at run-time, therefore you may need to use a mixture of these two options.
Page 267 MSGQ_alloc MSGQ_alloc Allocate a message C Interface Syntax status = MSGQ_alloc(poolId, msg, size); Parameters Uint16 poolId; /* allocate the message from this allocator */ MSGQ_Msg *msg; /* pointer to the returned message */ Uint16 size; /* size of the requested message */ status;...
Page 268 MSGQ_close MSGQ_close Close a message queue C Interface Syntax status = MSGQ_close(msgqQueue); Parameters MSGQ_Queue msgqQueue; /* Message queue to close */ Return Value status; /* status */ Reentrant Description MSGQ_close closes a message queue. If any messages are in the message queue, they are deleted.
Page 269 MSGQ_count MSGQ_count Return the number of messages in a message queue C Interface Syntax status = MSGQ_count(msgqQueue, count); Parameters MSGQ_Queue msgqQueue; /* Message queue to count */ *count; /* Pointer to returned count */ Return Value status; /* status */ Reentrant This API determines the number of messages in a specific message Description...
Page 270 MSGQ_free MSGQ_free Free a message C Interface Syntax status = MSGQ_free(msg); Parameters MSGQ_Msg msg; /* Message to be freed */ Return Value status; /* status */ Reentrant Description MSGQ_free frees a message back to the allocator. If successful, this function returns SYS_OK. This call is non-blocking and can be called from a HWI, SWI or TSK.
Page 271 MSGQ_get MSGQ_get Receive a message from the message queue C Interface Syntax status = MSGQ_get(msgqQueue, msg, timeout); Parameters MSGQ_Queue msgqQueue; /* Message queue */ MSGQ_Msg *msg; /* Pointer to the returned message */ timeout; /* Duration to block if no message */ status;...
Page 272 MSGQ_getAttrs MSGQ_getAttrs Returns the attributes of a message queue C Interface Syntax status = MSGQ_getAttrs(msgqQueue, attrs); Parameters MSGQ_Queue msgqQueue; /* Message queue */ MSGQ_Attrs *attrs; /* Attributes of message queue */ Return Value status /* status */ Reentrant Description MSGQ_getAttrs fills in the attrs structure passed to it with the attributes of a local message queue.
Page 273 MSGQ_getDstQueue MSGQ_getDstQueue Get destination message queue field in a message C Interface Syntax MSGQ_getDstQueue(msg, msgqQueue); Parameters MSGQ_Msg msg; /* Message */ MSGQ_Queue *msgqQueue; /* Message queue */ Return Value Void Reentrant This API allows the application to determine the destination message Description queue of a message.
Page 274 MSGQ_getMsgId MSGQ_getMsgId Return the message ID from a message C Interface Syntax msgId = MSGQ_getMsgId(msg); Parameters MSGQ_Msg msg; /* Message */ Return Value Uint16 msgId; /* Message ID */ Reentrant Description MSGQ_getMsgId returns the message ID from a received message. This message ID is specified via the MSGQ_setMsgId function.
Page 275 MSGQ_getMsgSize MSGQ_getMsgSize Return the message size from a message C Interface Syntax size = MSGQ_getMsgSize(msg); Parameters MSGQ_Msg msg; /* Message */ Return Value Uint16 size; /* Message size */ Reentrant Description MSGQ_getMsgSize returns the size of the message buffer out of the received message.
Page 276 MSGQ_getSrcQueue MSGQ_getSrcQueue Extract the reply destination from a message C Interface Syntax status = MSGQ_getSrcQueue(msg, msgqQueue); Parameters MSGQ_Msg msg; /* Received message */ MSGQ_Queue *msgqQueue; /* Message queue */ Return Value status; /* status */ Reentrant Many times a receiver of a message wants to reply to the sender of the Description message (for example, to send an acknowledgement).
Page 277 MSGQ_isLocalQueue MSGQ_isLocalQueue Return whether message queue is local or on other processor C Interface Syntax flag = MSGQ_isLocalQueue(msgqQueue); Parameters MSGQ_Queue msgqQueue; /* Message queue */ Return Value Bool flag; /* status */ Reentrant Description This API determines whether the message queue is local (that is, opened on this processor) or remote (that is, opened on a different processor).
Page 278 MSGQ_locate MSGQ_locate Synchronously find a message queue C Interface Syntax status = MSGQ_locate(queueName, msgqQueue, locateAttrs); Parameters String queueName; /* Name of message queue to locate */ MSGQ_Queue *msgqQueue; /* Return located message queue here */ MSGQ_LocateAttrs *locateAttrs; /* Locate attributes */ status;...
Page 279 MSGQ_locate typedef struct MSGQ_LocateAttrs { timeout; } MSGQ_LocateAttrs; The timeout is the maximum time a transport can block on a synchronous locate in system clock ticks. The default attributes are as follows: 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.
Page 280 MSGQ_locateAsync MSGQ_locateAsync Asynchronously find a message queue C Interface Syntax status = MSGQ_locateAsync(queueName, replyQueue, locateAsyncAttrs); Parameters String queueName; /* Name of message queue to locate */ MSGQ_Queue replyQueue; /* Msgq to send locate message */ MSGQ_LocateAsyncAttrs *locateAsyncAttrs; /* Locate attributes */ status;...
Page 281 MSGQ_locateAsync Once the application receives an asynchronous locate message, it is responsible for freeing the message. The asynchronous locate message received by the replyQueue has the following structure: typedef struct MSGQ_AsyncLocateMsg { MSGQ_MsgHeader header; MSGQ_Queue msgqQueue; arg; } MSGQ_AsyncLocateMsg; Field Type Description header...
Page 282 MSGQ_open MSGQ_open Open a message queue C Interface Syntax status = MSGQ_open(queueName, msgqQueue, attrs); Parameters String queueName; /* Unique name of the message queue */ MSGQ_Queue *msgqQueue; /* Pointer to returned message queue */ MSGQ_Attrs *attrs; /* Attributes of the message queue */ status;...
Page 283 MSGQ_open Pend MSGQ_Pend Function pointer to a user-specified pend function. Post MSGQ_Post Function pointer to a user-specified post function. The default attributes are: MSGQ_Attrs MSGQ_ATTRS = { NULL, /* notifyHandle */ (MSGQ_Pend)SYS_zero, /* NOP pend */ FXN_F_nop /* NOP post */ The following typedefs are provided by the MSGQ module to allow easier casting of the pend and post functions: typedef Bool (*MSGQ_Pend)(Ptr notifyHandle, Uns timeout);...
Page 284 MSGQ_open The following notification attributes could be used if the reader is a SWI function (which cannot block): MSGQ_Attrs attrs = MSGQ_ATTRS; // default attributes // leave attrs.pend as a NOP attrs.notifyHandle = (Ptr)swiHandle; attrs.post = (MSGQ_Pend)SWI_post; The following notification attributes could be used if the reader is a TSK function (which can block): MSGQ_Attrs attrs = MSGQ_ATTRS;...
Page 285 MSGQ_put MSGQ_put Place a message on a message queue C Interface Syntax status = MSGQ_put(msgqQueue, msg); Parameters MSGQ_Queue msgqQueue; /* Destination message queue */ MSGQ_Msg msg; /* Message */ Return Value status; /* status */ Reentrant MSGQ_put places a message into the specified message queue. Description This function is performed by a writer.
Page 286 MSGQ_put ❏ If MSGQ_put does not return SYS_OK, the message is still owned by the caller and 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);...
Page 287 MSGQ_release MSGQ_release Release a located message queue C Interface Syntax status = MSGQ_release(msgqQueue); Parameters MSGQ_Queue msgqQueue; /* Message queue to release */ Return Value status; /* status */ Reentrant Description This function releases a located message queue. That is, it releases a message queue returned from MSGQ_locate or MSGQ_locateAsync.
Page 288 MSGQ_setErrorHandler MSGQ_setErrorHandler Set up handling of internal MSGQ errors C Interface Syntax status = MSGQ_setErrorHandler(errorQueue, poolId); Parameters MSGQ_Queue errorQueue; /* Message queue to receive errors */ Uint16 poolId; /* Allocator to allocate error messages */ Return Value status; /* status */ Reentrant Asynchronous errors that need to be communicated to the application Description...
Page 289 MSGQ_setErrorHandler The following table describes the fields in the MSGQ_AsyncErrorMsg structure: Field Type Description header MSGQ_MsgHeader Required field for every message errorType MSGQ_MqtError Error ID mqtId Uint16 ID of the transport that sent the error message parameter Uint16 Error-specific field The following table lists the valid errorType values and the meanings of their arg fields: errorType...
Page 290 MSGQ_setMsgId MSGQ_setMsgId Set the message ID in a message C Interface Syntax MSGQ_setMsgId(msg, msgId); Parameters MSGQ_MSG msg; /* Message */ Uint16 msgId; /* Message id */ Void Return Value Reentrant Description Inside each message is a message id field. This API sets this field. The value of msgId is application-specific.
Page 291 MSGQ_setMsgId 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"); MSGQ_getMsgId See Also MSGQ_setErrorHandler Application Program Interface 2-263...
Page 292 MSGQ_setSrcQueue MSGQ_setSrcQueue Set the reply destination in a message C Interface Syntax MSGQ_setSrcQueue(msg, msgqQueue); Parameters MSGQ_MSG msg; /* Message */ MSGQ_Queue msgqQueue; /* Message queue */ Return Value Void Reentrant This API allows the sender to specify a message queue that the receiver Description of the message can reply back to (via MSGQ_getSrcQueue).
Page 293: Pip Module
PIP Module 2.17 PIP Module Important Note: The PIP module is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 294 PIP Module ❏ Ptr writerAddr . Pointer to the address to begin writing to after calling PIP_alloc. ❏ Uns writerSize . Number of words available in the frame allocated with PIP_alloc. ❏ Uns writerNumFrames . Number of frames available to be written to. Configuration The following list shows the properties that can be configured in a Tconf script, along with their types and default values.
Page 295: Pipe Schematic
PIP Module Each pipe object maintains a buffer divided into a fixed number of fixed length frames, specified by the numframes and framesize properties. All I/O operations on a pipe deal with one frame at a time; although each frame has a fixed length, the application can put a variable amount of data in each frame up to the length of the frame.
Page 296 PIP Module Note: When DSP/BIOS starts up, it calls the notifyWriter function internally for each created pipe object to initiate the pipe’s I/O. The code that calls PIP_free or PIP_put should preserve any necessary registers. Often one end of a pipe is controlled by an HWI and the other end is controlled by a SWI function, such as SWI_andnHook.
Page 297 PIP Module The following properties can be set for a PIP object in the PIP Object Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏ comment . Type a comment to identify this PIP object. Tconf Name: comment Type: String Example: myPip.comment = "my PIP";...
Page 298 PIP Module notifyWriter function should not directly call any of the PIP module functions for the same pipe. Tconf Name: notifyWriterFxn Type: Extern Example: myPip.notifyWriterFxn = prog.extern("writerFxn"); ❏ nwarg0, nwarg1 . Two Arg type arguments for the notifyWriter function. Tconf Name: notifyWriterArg0 Type: Arg Tconf Name: notifyWriterArg1 Type: Arg...
Page 299 PIP_alloc PIP_alloc Allocate an empty frame from a pipe Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 300 PIP_alloc if (PIP_getReaderNumFrames(in) == 0 || PIP_getWriterNumFrames(out) == 0) { error; /* get input data and allocate output frame */ PIP_get(in); PIP_alloc(out); /* copy input data to output frame */ src = PIP_getReaderAddr(in); dst = PIP_getWriterAddr(out); size = PIP_getReaderSize(in); PIP_setWriterSize(out, size); for (;...
Page 301 PIP_free PIP_free Recycle a frame that has been read to a pipe Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 302 PIP_get PIP_get Get a full frame from the pipe Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 303 PIP_getReaderAddr PIP_getReaderAddr Get the value of the readerAddr pointer of the pipe Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 304 PIP_getReaderNumFrames PIP_getReaderNumFrames Get the number of pipe frames available for reading Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 305 PIP_getReaderSize PIP_getReaderSize Get the number of words of data in a pipe frame Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 306 PIP_getWriterAddr PIP_getWriterAddr Get the value of the writerAddr pointer of the pipe Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 307 PIP_getWriterNumFrames PIP_getWriterNumFrames Get number of pipe frames available to be written to Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 308 PIP_getWriterSize PIP_getWriterSize Get the number of words that can be written to a pipe frame Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 309 PIP_peek PIP_peek Get pipe frame size and address without actually claiming pipe frame Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 310 PIP_put PIP_put Put a full frame into the pipe Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 311 PIP_reset PIP_reset Reset all fields of a pipe object to their original values Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 312 PIP_setWriterSize PIP_setWriterSize Set the number of valid words written to a pipe frame Important Note: This API is being deprecated and will no longer be supported in the next major release of DSP/BIOS. We recommend that you use the SIO module instead. The PIP module is still supported in DSP/BIOS 5.32 and will be supported in any patch releases or minor enhancements to DSP/BIOS 5.32.
Page 313: Pool Module
POOL Module 2.18 POOL Module The POOL module describes the interface that allocators must provide. Functions None; this module describes an interface to be implemented by allocators Constants, Types, and POOL_Config POOL_config; Structures typedef struct POOL_Config { POOL_Obj *allocators; /* Array of allocators */ Uint16 numAllocators;...
Page 314: Allocators And Message Pools
POOL Module An application can use multiple allocators. The purpose of having multiple allocators is to allow an application to regulate its message usage. For example, an application can allocate critical messages from one pool of fast on-chip memory and non-critical messages from another pool of slower external memory.
Page 315 POOL Module The following is the POOL_Obj structure: typedef struct POOL_Obj { POOL_Init initFxn; /* Allocator init function */ POOL_Fxns *fxns; /* Interface functions */ params; /* Setup parameters */ object; /* Allocator’s object */ } POOL_Obj, *POOL_Handle; The fields in the POOL_Obj structure are as follows: Field Type Description...
Page 316: Buffer Layout As Defined By Staticpool_Params
POOL Module The following table describes the fields in this structure: Field Type Description addr 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 is a chance the buffer is not aligned, allow at least 7 extra MADUs of space to allow room for the alignment.
Page 317 POOL Module #pragma DATA_ALIGN(staticBuf0, 8) /* As required */ #pragma DATA_ALIGN(staticBuf1, 8) /* As required */ static Char staticBuf0[MSGSIZE0 * NUMMSGS]; static Char staticBuf1[MSGSIZE1 * NUMMSGS]; static MQASTATIC_Params poolParams0 = {staticBuf0, sizeof(staticBuf0), MSGSIZE0}; static MQASTATIC_Params poolParams1 = {staticBuf1, sizeof(staticBuf1), MSGSIZE1}; static STATICPOOL_Obj poolObj0, poolObj1;...
Page 318: Prd Module
PRD Module 2.19 PRD Module The PRD module is the periodic function manager. ❏ PRD_getticks. Get the current tick count. Functions ❏ PRD_start. Arm a periodic function for one-time execution. ❏ PRD_stop. Stop a periodic function from execution. ❏ PRD_tick. Advance tick counter, dispatch periodic functions. Configuration The following list shows the properties that can be configured in a Tconf Properties...
Page 319 PRD Module There can be several PRD objects, but all are driven by the same period counter. Each PRD object can execute its functions at different intervals based on the period counter. ❏ To schedule functions based on a real-time clock . Set the clock interrupt rate you want to use in the CLK Object Properties.
Page 320 PRD Module The following global properties can be set for the PRD module in the PRD Manager Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏ Object Memory . The memory segment containing the PRD objects. Tconf Name: OBJMEMSEG Type: Reference Example:...
Page 321 PRD Module ❏ mode . If "continuous" is used, the function executes every "period" number of ticks. If "one-shot" is used, the function executes just once after "period" ticks. Tconf Name: mode Type: EnumString Options: "continuous", "one-shot" Example: myPrd.mode = "continuous"; ❏...
Page 322 PRD_getticks PRD_getticks Get the current tick count C Interface Syntax num = PRD_getticks(); Parameters Void Return Value LgUns /* current tick counter */ Reentrant Description PRD_getticks returns the current period tick count as a 32-bit value. If the periodic functions are being driven by the on-device timer, the tick value is the number of low resolution clock ticks that have occurred since the program started running.
Page 323: Prd Tick Cycles
PRD_start PRD_start Arm a periodic function for one-shot execution C Interface Syntax PRD_start(prd); Parameters PRD_Handle prd; /* prd object handle*/ Return Value Void Reentrant Description PRD_start starts a period object that has its mode property set to one- shot in the configuration. Unlike PRD objects that are configured as continuous, one-shot PRD objects do not automatically continue to run.
Page 324 PRD_stop PRD_stop Stop a period object to prevent its function execution C Interface Syntax PRD_stop(prd); Parameters PRD_Handle prd; /* prd object handle*/ Return Value Void Reentrant Description PRD_stop stops a period object to prevent its function execution. In most cases, PRD_stop is used to stop a period object that has its mode property set to one-shot in the configuration.
Page 325 PRD_tick PRD_tick Advance tick counter, enable periodic functions C Interface Syntax PRD_tick(); Parameters Void Return Value Void Reentrant Description PRD_tick advances the period counter by one tick. Unless you are driving PRD functions using the on-device clock, PRD objects execute their functions at intervals based on this counter.
Page 326: Pwrm Module
PWRM Module 2.20 PWRM Module The PWRM module lets you reduce the power consumption of your DSP/BIOS application. The PWRM module is currently available for the ’C5509A EVM. Partial support for other ’C55x devices is also available. See the DSP/BIOS release notes to determine which features are supported on different ’C55x devices.
Page 327 PWRM Module Description The DSP/BIOS Power Manager, PWRM, is a DSP/BIOS module that lets you reduce the power consumption of your application in the following ways: ❏ You can idle specific clock domains to reduce active power consumption. ❏ You can specify a power-saving function to be called automatically at boot time.
Page 328 PWRM Module The following constants are used as return codes by various PWRM functions: Name Usage PWRM_SOK The operation succeeded. PWRM_EFAIL A general failure occurred. PWRM_EINVALIDEVENT The specified PWRM event type is invalid. PWRM_EINVALIDHANDLE The specified handle is invalid. PWRM_EINVALIDPOINTER A pointer is invalid.
Page 329 PWRM Module Name Usage 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 (OMAP 2420 only) The following list shows the properties that can be configured in a Tconf Configuration Properties...
Page 330 PWRM Module Name Type Default (Enum Options) PSLCONFIGLIB String "PSL_cfg_c5509a.a55L" ENABLESLEEP Bool true SLEEPIPORT Bool true (OMAP 2420 only) SLEEPHWA Bool true (OMAP 2420 only) SLEEPMPORT Bool true (OMAP 2420 only) SLEEPXPORT Bool true (OMAP 2420 only) SLEEPEMIF Bool true SLEEPCLKGEN Bool true...
Page 331 PWRM Module ❏ Call user hook function at boot time . Check this box if you want to specify a function to be called during application startup. Such a function is called before the main() function runs. Tconf Name: BOOTHOOK Type: Bool Example: bios.PWRM.BOOTHOOK = false;...
Page 332 PWRM Module ❏ MEM section for device database. Select the memory segment where PWRM should locate the resource database for the device. This property is writeable only if either "Enable device initialization by PWRM" or "Enable resource tracking by PWRM" is set to true. Tconf Name: DEVICEDBMEMSEG Type: Reference Example:...
Page 333 PWRM Module ❏ XPORT . Checking this box causes the XPORT clock domain to be idled during the DSP/BIOS idle loop. The DMA and CPU domains must be idled before you can choose to idle the XPORT domain. This setting can be modified at runtime using the PWRM_configure function.
Page 334 PWRM Module ❏ DMA . Checking this box causes the DMA clock domain to be idled during the DSP/BIOS idle loop. The DMA domain must remain idled if the CLKGEN domain is idled. This setting can be modified at runtime using the PWRM_configure function. Tconf Name: IDLEDMA Type: Bool Example:...
Page 335 PWRM Module if the new setpoint frequency is higher than that supported at the current voltage. This setting can be modified at runtime using the PWRM_configure function. Tconf Name: SCALEVOLT Type: Bool Example: bios.PWRM.SCALEVOLT = false; ❏ Wait while voltage is being scaled down .This property specifies whether PWRM functions should wait during down-voltage transitions.
Page 336 PWRM Module ❏ MPORT . Checking this box causes the MPORT clock domain to be idled during deep sleep. The DMA domain must be idled for deep sleep before you can choose to idle the MPORT domain. (OMAP 2420 only) Tconf Name: SLEEPMPORT Type: Bool Example:...
Page 337 PWRM Module ❏ CPU . Checking this box causes the CPU clock domain to be idled during deep sleep. The CPU domain must remain idled if the CLKGEN domain is idled. Tconf Name: SLEEPCPU Type: Bool Example: bios.PWRM.SLEEPCPU = true; ❏...
Page 338 PWRM_changeSetpoint PWRM_changeSetpoint Initiate a change to the V/F setpoint C Interface Syntax status = PWRM_changeSetpoint(newSetpoint, notifyTimeout); Parameters newSetpoint; /* new V/F setpoint */ notifyTimeout; /* maximum time to wait for notification */ Return Value PWRM_Status status; /* returned status */ Reentrant Description PWRM_changeSetpoint changes the voltage and frequency of the DSP...
Page 339 PWRM_changeSetpoint The notifyTimeout parameter is the maximum amount of time (in system clock ticks) to wait for registered notification functions (set by PWRM_registerNotify) to respond to a delayed completion, before declaring failure and returning PWRM_ETIMEOUT. For example, if notifyTimeout is set to 200, PWRM_changeSetpoint waits up to 200 ticks (typically 200 milliseconds) before declaring that a function has failed to respond.
Page 340 PWRM_changeSetpoint PWRM_changeSetpoint disables SWI and TSK scheduling when it begins making a change. However, HWIs may run during the notification process. After the setpoint has been changed, SWI and TSK scheduling is re-enabled, and a context switch occurs only if some other thread has since been made ready to run.
Page 341 PWRM_configure PWRM_configure Set new configuration properties for PWRM C Interface Syntax status = PWRM_configure(attrs); Parameters PWRM_Attrs attrs; /* configuration attributes */ Return Value PWRM_Status status; /* returned status */ Reentrant Description PWRM_configure specifies new configuration properties for the PWRM module. It overrides those specified in the static configuration. The PWRM_Attrs parameter you pass to PWRM_configure has the following structure: typedef struct PWRM_Attrs {...
Page 342 PWRM_configure idled on entry to the DSP/BIOS idle loop are written to the ICR register and the IDLE instruction is invoked again to restore the previous idle configuration. See the Idling tab of the configuration properties for descriptions of required interactions between idled clock domains. The bitmask can be formed using the following predefined mask constants: Name Usage...
Page 343 PWRM_getCapabilities PWRM_getCapabilities Get information on PWRM capabilities on the current platform C Interface Syntax status = PWRM_getCapabilities(capsMask); Parameters *capsMask; /* pointer to location for capabilities */ Return Value PWRM_Status status; /* returned status */ Reentrant Description PWRM_getCapabilities returns information about the PWRM module’s capabilities on the current platform.
Page 344 PWRM_getCapabilities Example PWRM_Status status; Uns capsMask; /* Query PWRM capabilities 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 &...
Page 345 PWRM_getCurrentSetpoint PWRM_getCurrentSetpoint Get the current setpoint C Interface Syntax status = PWRM_getCurrentSetpoint(setpoint); Parameters *setpoint; /* current V/F setpoint */ PWRM_Status status; /* returned status */ Return Value Reentrant Description PWRM_getCurrentSetpoint returns the V/F scaling setpoint currently in use. The setpoint parameter should point to the location where PWRM_getCurrentSetpoint should write the current setpoint.
Page 346 PWRM_getDependencyCount PWRM_getDependencyCount Get count of dependencies declared on resource C Interface Syntax status = PWRM_getDependencyCount(resourceID, count); Parameters resourceID; /* resource ID */ *count; /* pointer to where count is written */ Return Value PWRM_Status status; /* returned status */ Reentrant Description PWRM_getDependencyCount returns the number of dependencies that are currently declared on a resource.
Page 347 PWRM_getNumSetpoints PWRM_getNumSetpoints Get the number of setpoints supported by platform C Interface Syntax status = PWRM_getNumSetpoints(numberSetpoints); Parameters *numberSetpoints; /* number of supported setpoints */ PWRM_Status status; /* returned status */ Return Value Reentrant Description PWRM_getNumSetpoints returns the number of setpoints supported by the currently configured platform.
Page 348 PWRM_getSetpointInfo PWRM_getSetpointInfo Get frequency and CPU core voltage for a setpoint C Interface Syntax status = PWRM_getSetpointInfo(setpoint, frequency, voltage); Parameters setpoint; /* the setpoint to query */ float *frequency; /* DSP core frequency */ float *voltage; /* DSP voltage */ Return Value PWRM_Status status;...
Page 349 PWRM_getSetpointInfo Example PWRM_Status status; /* global arrays for saving setpoint info */ #define MAX_SETPOINTS 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; Application Program Interface 2-321...
Page 350 PWRM_getTransitionLatency PWRM_getTransitionLatency Get latency to scale between specific setpoints C Interface Syntax status = PWRM_getTransitionLatency(initialSetpoint, finalSetpoint, frequencyLatency, voltageLatency); Parameters initialSetpoint; /* setpoint to be scaled from */ finalSetpoint; /* setpoint to be scaled to */ *frequencyLatency; /* frequency transition latency */ *voltageLatency;...
Page 351 PWRM_getTransitionLatency Name Usage PWRM_EINVALIDVALUE The operation failed because the initialSetpoint or finalSetpoint parameter was invalid. PWRM_EINVALIDPOINTER The operation failed because the latency parameter was NULL. PWRM_EINITFAILURE A failure occurred while initializing V/F scal- ing support; V/F scaling is unavailable PWRM_ENOTIMPLEMENTED The operation failed because V/F scaling is not supported.
Page 352 PWRM_idleClocks PWRM_idleClocks Immediately idle clock domains C Interface Syntax status = PWRM_idleClocks(domainMask, idleStatus); Parameters domainMask; /* bitmask of clock domains to be idled */ *idleStatus; /* contents of ISTR after idling */ Return Value PWRM_Status status; /* returned status */ Reentrant Description PWRM_idleClocks immediately turns off the specified clock domains.
Page 353 PWRM_idleClocks PWRM_idleClocks returns one of the following constants as a status value of type PWRM_Status: 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.
Page 354 PWRM_registerNotify PWRM_registerNotify Register a function to be called on a specific power event C Interface Syntax status PWRM_registerNotify(eventType, eventMask, notifyFxn, clientArg, notifyHandle, delayedCompletionFxn); Parameters PWRM_Event eventType; /* type of power event */ LgUns eventMask; /* event-specific mask */ notifyFxn; /* function to call on event */ clientArg;...
Page 355 PWRM_registerNotify Note: Snooze mode is currently not implemented. The eventMask parameter is an event-specific mask. Currently eventMask is relevant only to setpoint changes, but it may be used in the future for other power events. For V/F setpoint registrations, this mask defines the setpoints the client supports.
Page 356 PWRM_registerNotify PWRM_registerNotify returns one of the following constants as a status value of type PWRM_Status: Name Usage PWRM_SOK The function was successfully registered. PWRM_EFAIL A general failure occurred. PWRM_EINVALIDPOINTER The operation failed because the notifyFxn, notifyHandle or delayedCompletionFxn parameter was NULL. PWRM_EINVALIDEVENT Operation failed because eventType is invalid.
Page 357 pwrmNotifyFxn pwrmNotifyFxn Function to be called on a registered power event C Interface Syntax status = notifyFxn(eventType, eventArg1, eventArg2, clientArg); Parameters PWRM_Event eventType; /* type of power event */ eventArg1; /* event-specific argument */ eventArg2; /* event-specific argument */ clientArg; /* arbitrary argument */ PWRM_NotifyResponse status;...
Page 358 pwrmNotifyFxn The notification function must return one of the following constants as a status value of type PWRM_NotifyResponse: Name Usage PWRM_NOTIFYDONE The client processed the notification function successfully. PWRM_NOTIFYNOTDONE The client must wait for interrupt processing to occur before it can proceed. The client must later call the delayedCompletionFxn specified when this function was registered with PWRM_registerNotify.
Page 359 PWRM_releaseDependency PWRM_releaseDependency Release a dependency that was previously declared C Interface Syntax status = PWRM_releaseDependency(resourceID); Parameters resourceID; /* resource ID */ PWRM_Status status; /* returned status */ Return Value Reentrant Description This function is the companion to PWRM_setDependency. It releases a resource dependency that was previously set.
Page 360 PWRM_setDependency PWRM_setDependency Declare a dependency upon a resource C Interface Syntax status = PWRM_setDependency(resourceID); Parameters resourceID; /* resource ID */ PWRM_Status status; /* returned status */ Return Value Reentrant Description This function sets a dependency on a resource. It is the companion to PWRM_releaseDependency.
Page 361 PWRM_sleepDSP PWRM_sleepDSP Transition the DSP to a new sleep state C Interface Syntax status = PWRM_sleepDSP(sleepCode, sleepArg, notifyTimeout); Parameters sleepCode; /* new sleep state */ LgUns sleepArg; /* sleepCode-specific argument */ notifyTimeout; /* maximum time to wait for notification */ Return Value PWRM_Status status;...
Page 362 PWRM_sleepDSP The notifyTimeout parameter is the maximum amount of time (in system clock ticks) to wait for registered notification functions (set by PWRM_registerNotify) to respond to a delayed completion, before declaring failure and returning PWRM_ETIMEOUT. PWRM_sleepDSP returns one of the following constants as a status value of type PWRM_Status: Name Usage...
Page 363 PWRM_unregisterNotify PWRM_unregisterNotify Unregister for an event notification from PWRM C Interface Syntax status = PWRM_unregisterNotify(notifyHandle); Parameters PWRM_NotifyHandle notifyHandle;/* handle to registered function */ Return Value PWRM_Status status; /* returned status */ Reentrant Description PWRM_unregisterNotify unregisters an event notification that was registered by PWRM_registerNotify.
Page 364: Que Module
QUE Module 2.21 QUE Module The QUE module is the atomic queue manager. ❏ QUE_create. Create an empty queue. Functions ❏ QUE_delete. Delete an empty queue. ❏ QUE_dequeue. Remove from front of queue (non-atomically). ❏ QUE_empty. Test for an empty queue. ❏...
Page 365 QUE Module Instance Configuration Parameters Name Type Default comment String "<add comments here>" Description The QUE module makes available a set of functions that manipulate queue objects accessed through handles of type QUE_Handle. Each queue contains an ordered sequence of zero or more elements referenced through variables of type QUE_Elem, which are generally embedded as the first field within a structure.
Page 366 QUE Module QUE Object Properties To create a QUE object in a configuration script, use the following syntax. The Tconf examples that follow 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: ❏...
Page 367 QUE_create QUE_create Create an empty queue C Interface Syntax queue = QUE_create(attrs); Parameters QUE_Attrs *attrs; /* pointer to queue attributes */ Return Value QUE_Handle queue; /* handle for new queue object */ QUE_create creates a new queue which is initially empty. If successful, Description QUE_create returns the handle of the new queue.
Page 368 QUE_delete QUE_delete Delete an empty queue C Interface Syntax QUE_delete(queue); Parameters QUE_Handle queue; /* queue handle */ Return Value Void QUE_delete uses MEM_free to free the queue object referenced by Description queue. QUE_delete calls MEM_free to delete the QUE object. MEM_free must acquire a lock to the memory before proceeding.
Page 369 QUE_dequeue QUE_dequeue Remove from front of queue (non-atomically) C Interface Syntax elem = QUE_dequeue(queue); Parameters QUE_Handle queue; /* queue object handle */ Return Value elem; /* pointer to former first element */ QUE_dequeue removes the element from the front of queue and returns Description elem.
Page 370 QUE_empty QUE_empty Test for an empty queue C Interface Syntax empty = QUE_empty(queue); Parameters QUE_Handle queue; /* queue object handle */ Return Value Bool empty; /* TRUE if queue is empty */ QUE_empty returns TRUE if there are no elements in queue, and FALSE Description otherwise.
Page 371 QUE_enqueue QUE_enqueue Insert at end of queue (non-atomically) C Interface Syntax QUE_enqueue(queue, elem); Parameters QUE_Handle queue; /* queue object handle */ elem; /* pointer to queue element */ Return Value Void Description QUE_enqueue inserts elem at the end of queue. The elem parameter must be a pointer to an element to be placed in the QUE.
Page 372 QUE_get QUE_get Get element from front of queue (atomically) C Interface Syntax elem = QUE_get(queue); Parameters QUE_Handle queue; /* queue object handle */ Return Value Void *elem; /* pointer to former first element */ QUE_get removes the element from the front of queue and returns elem. Description The return value, elem, is a pointer to the element at the front of the QUE.
Page 373 QUE_head QUE_head Return element at front of queue C Interface Syntax elem = QUE_head(queue); Parameters QUE_Handle queue; /* queue object handle */ Return Value QUE_Elem *elem; /* pointer to first element */ QUE_head returns a pointer to the element at the front of queue. The Description element is not removed from the queue.
Page 374 QUE_insert QUE_insert Insert in middle of queue (non-atomically) C Interface Syntax QUE_insert(qelem, elem); Parameters qelem; /* element already in queue */ elem; /* element to be inserted in queue */ Return Value Void Description QUE_insert inserts elem in the queue in front of qelem. The qelem parameter is a pointer to an existing element of the QUE.
Page 375 QUE_new QUE_new Set a queue to be empty C Interface Syntax QUE_new(queue); Parameters QUE_Handle queue; /* pointer to queue object */ Return Value Void QUE_new adjusts a queue object to make the queue empty. This Description operation is not atomic. A typical use of QUE_new is to initialize a queue object that has been statically declared instead of being created with QUE_create.
Page 376 QUE_next QUE_next Return next element in queue (non-atomically) C Interface Syntax elem = QUE_next(qelem); Parameters qelem; /* element in queue */ Return Value elem; /* next element in queue */ QUE_next returns elem which points to the element in the queue after Description qelem.
Page 377 QUE_prev QUE_prev Return previous element in queue (non-atomically) C Interface Syntax elem = QUE_prev(qelem); Parameters qelem; /* element in queue */ Return Value elem; /* previous element in queue */ QUE_prev returns elem which points to the element in the queue before Description qelem.
Page 378 QUE_put QUE_put Put element at end of queue (atomically) C Interface Syntax QUE_put(queue, elem); Parameters QUE_Handle queue; /* queue object handle */ Void *elem; /* pointer to new queue element */ Return Value Void Description QUE_put puts elem at the end of queue. The elem parameter is a pointer to an element to be placed at the end of the QUE.
Page 379 QUE_remove QUE_remove Remove from middle of queue (non-atomically) C Interface Syntax QUE_remove(qelem); Parameters qelem; /* element in queue */ Return Value Void QUE_remove removes qelem from the queue. Description The qelem parameter is a pointer to an existing element to be removed from the QUE.
Page 380 QUE_remove Constraints and QUE_remove should not be called when qelem is equal to the queue Calling Context itself. See Also QUE_head QUE_insert QUE_next QUE_prev 2-352...
Page 381: Rtdx Module
RTDX Module 2.22 RTDX Module The RTDX modules manage the real-time data exchange settings. ❏ RTDX_CreateInputChannel RTDX Data Declaration ❏ RTDX_CreateOutputChannel Macros ❏ RTDX_disableInput Function Macros ❏ RTDX_disableOutput ❏ RTDX_enableInput ❏ RTDX_enableOutput ❏ RTDX_read ❏ RTDX_readNB ❏ RTDX_sizeofInput ❏ RTDX_write ❏...
Page 382 RTDX Module Data channels are represented by global structures. A data channel can be used for input or output, but not both. The contents of an input or output structure are not known to the user. A channel structure has two states: enabled and disabled.
Page 383 RTDX Module You should allow all interrupts to be disabled inside critical RTDX sections if your application makes any RTDX calls from SWI or TSK threads. If your application does not make RTDX calls from SWI or TSK threads, you may modify bits in this mask to enable specific high-priority interrupts.
Page 384 RTDX_channelBusy RTDX_channelBusy Return status indicating whether data channel is busy C Interface Syntax int RTDX_channelBusy( RTDX_inputChannel *pichan ); Parameters pichan /* Identifier for the input data channel */ Return Value /* Status: 0 = Channel is not busy. */ /* non-zero = Channel is busy. */ Reentrant Description RTDX_channelBusy is designed to be used in conjunction with...
Page 385 RTDX_CreateInputChannel RTDX_CreateInputChannel Declare input channel structure C Interface Syntax RTDX_CreateInputChannel( ichan ); Parameters ichan /* Label for the input channel */ Return Value none Reentrant Description This macro declares and initializes to 0, the RTDX data channel for input. Data channels must be declared as global objects. A data channel can be used either for input or output, but not both.
Page 386 RTDX_CreateOutputChannel RTDX_CreateOutputChannel Declare output channel structure C Interface Syntax RTDX_CreateOutputChannel( ochan ); Parameters ochan /* Label for the output channel */ Return Value none Reentrant Description This macro declares and initializes the RTDX data channels for output. Data channels must be declared as global objects. A data channel can be used either for input or output, but not both.
Page 387 RTDX_disableInput RTDX_disableInput Disable an input data channel C Interface Syntax void RTDX_disableInput( RTDX_inputChannel *ichan ); Parameters ichan /* Identifier for the input data channel */ Return Value void Reentrant Description A call to a disable function causes the specified input channel to be disabled.
Page 388 RTDX_disableOutput RTDX_disableOutput Disable an output data channel C Interface Syntax void RTDX_disableOutput( RTDX_outputChannel *ochan ); Parameters ochan /* Identifier for an output data channel */ Return Value void Reentrant Description A call to a disable function causes the specified data channel to be disabled.
Page 389 RTDX_enableInput RTDX_enableInput Enable an input data channel C Interface Syntax void RTDX_enableInput( RTDX_inputChannel *ichan ); Parameters ochan /* Identifier for an output data channel */ ichan /* Identifier for the input data channel */ Return Value void Reentrant Description A call to an enable function causes the specified data channel to be enabled.
Page 390 RTDX_enableOutput RTDX_enableOutput Enable an output data channel C Interface Syntax void RTDX_enableOutput( RTDX_outputChannel *ochan ); Parameters ochan /* Identifier for an output data channel */ Return Value void Reentrant Description A call to an enable function causes the specified data channel to be enabled.
Page 391 RTDX_isInputEnabled RTDX_isInputEnabled Return status of the input data channel C Interface Syntax RTDX_isInputEnabled( ichan ); Parameter ichan /* Identifier for an input channel. */ Return Value /* Not enabled. */ non-zero /* Enabled. */ Reentrant 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.
Page 392 RTDX_isOutputEnabled RTDX_isOutputEnabled Return status of the output data channel C Interface Syntax RTDX_isOutputEnabled(ohan ); Parameter ochan /* Identifier for an output channel. */ Return Value /* Not enabled. */ non-zero /* Enabled. */ Reentrant Description 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.
Page 393 RTDX_read RTDX_read Read from an input channel C Interface Syntax int RTDX_read( RTDX_inputChannel *ichan, void *buffer, int bsize ); ichan /* Identifier for the input data channel */ Parameters buffer /* A pointer to the buffer that receives the data */ bsize /* The size of the buffer in address units */ Return Value...
Page 394 RTDX_readNB RTDX_readNB Read from input channel without blocking C Interface Syntax int RTDX_readNB( RTDX_inputChannel *ichan, void *buffer, int bsize ); Parameters ichan /* Identifier for the input data channel */ buffer /* A pointer to the buffer that receives the data */ bsize /* The size of the buffer in address units */ RTDX_OK...
Page 395 RTDX_sizeofInput RTDX_sizeofInput Return the number of MADUs read from a data channel C Interface Syntax int RTDX_sizeofInput( RTDX_inputChannel *pichan ); Parameters pichan /* Identifier for the input data channel */ Return Value /* Number of sizeof units of data actually */ /* supplied in buffer */ Reentrant Description...
Page 396 RTDX_write RTDX_write Write to an output channel C Interface Syntax int RTDX_write( RTDX_outputChannel *ochan, void *buffer, int bsize ); Parameters ochan /* Identifier for the output data channel */ buffer /* A pointer to the buffer containing the data */ bsize /* The size of the buffer in address units */ Return Value...
Page 397: Sem Module
SEM Module 2.23 SEM Module The SEM module is the semaphore manager. ❏ SEM_count. Get current semaphore count Functions ❏ SEM_create. Create a semaphore ❏ SEM_delete. Delete a semaphore ❏ SEM_new. Initialize a semaphore ❏ SEM_pend. Wait for a counting semaphore ❏...
Page 398 SEM Module Description The SEM module makes available a set of functions that manipulate semaphore objects accessed through handles of type SEM_Handle. Semaphores can be used for task synchronization and mutual exclusion. Semaphores can be counting semaphores or binary semaphores. The APIs for binary and counting semaphores cannot be mixed for a single semaphore.
Page 399 SEM Module tasks are waiting, SEM_post simply increments the semaphore count and returns. (SEM_postBinary sets the semaphore count to non-zero and returns.) SEM Manager The following global property can be set for the SEM module in the SEM Properties Manager Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏...
Page 400 SEM_count SEM_count Get current semaphore count C Interface Syntax count = SEM_count(sem); Parameters SEM_Handle sem; /* semaphore handle */ Return Value count; /* current semaphore count */ SEM_count returns the current value of the semaphore specified by sem. Description 2-372...
Page 401 SEM_create SEM_create Create a semaphore C Interface Syntax sem = SEM_create(count, attrs); Parameters count; /* initial semaphore count */ SEM_Attrs *attrs; /* pointer to semaphore attributes */ Return Value SEM_Handle sem; /* handle for new semaphore object */ Description SEM_create creates a new semaphore object which is initialized to count.
Page 402 SEM_delete SEM_delete Delete a semaphore C Interface Syntax SEM_delete(sem); Parameters SEM_Handle sem; /* semaphore object handle */ Return Value Void SEM_delete uses MEM_free to free the semaphore object referenced by Description sem. SEM_delete calls MEM_free to delete the SEM object. MEM_free must acquire a lock to the memory before proceeding.
Page 403 SEM_new SEM_new Initialize semaphore object C Interface Syntax Void SEM_new(sem, count); Parameters SEM_Handle sem; /* pointer to semaphore object */ count; /* initial semaphore count */ Return Value Void Description 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.
Page 404 SEM_pend SEM_pend Wait for a semaphore C Interface Syntax status = SEM_pend(sem, timeout); Parameters SEM_Handle sem; /* semaphore object handle */ timeout; /* return after this many system clock ticks */ Return Value Bool status; /* TRUE if successful, FALSE if timeout */ Description SEM_pend and SEM_post are for use with counting semaphores, which keep track of the number of times the semaphore has been posted.
Page 405 SEM_pendBinary SEM_pendBinary Wait for a binary semaphore C Interface Syntax status = SEM_pendBinary(sem, timeout); Parameters SEM_Handle sem; /* semaphore object handle */ timeout; /* return after this many system clock ticks */ Return Value Bool status; /* TRUE if successful, FALSE if timeout */ Description SEM_pendBinary and SEM_postBinary are for use with binary semaphores.
Page 406 SEM_pendBinary ❏ This API cannot be called from the program’s 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.
Page 407 SEM_post SEM_post Signal a semaphore C Interface Syntax SEM_post(sem); Parameters SEM_Handle sem; /* semaphore object handle */ Return Value Void SEM_pend and SEM_post are for use with counting semaphores, which Description 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.
Page 408 SEM_postBinary SEM_postBinary Signal a binary semaphore C Interface Syntax SEM_postBinary(sem); Parameters SEM_Handle sem; /* semaphore object handle */ Return Value Void SEM_pendBinary and SEM_postBinary are for use with binary Description semaphores. These are semaphores that can have only two states: available and unavailable.
Page 409 SEM_reset SEM_reset Reset semaphore count C Interface Syntax SEM_reset(sem, count); Parameters SEM_Handle sem; /* semaphore object handle */ count; /* semaphore count */ Return Value Void Description SEM_reset resets the semaphore count to count. No task switch occurs when calling SEM_reset. ❏...
Page 410: Sio Module
SIO Module 2.24 SIO Module The SIO module is the stream input and output manager. ❏ SIO_bufsize. Size of the buffers used by a stream Functions ❏ SIO_create. Create stream ❏ SIO_ctrl. Perform a device-dependent control operation ❏ SIO_delete. Delete stream ❏...
Page 411 SIO Module SIO_Attrs SIO_ATTRS = { /* nbufs */ /* segid */ /* align */ FALSE, /* flush */ SIO_STANDARD, /* model */ SYS_FOREVER /* timeout */ NULL /* callback */ Configuration The following list shows the properties that can be configured in a Tconf Properties script, along with their types and default values.
Page 412 SIO Module Description The stream manager provides efficient real-time device-independent I/O through a set of functions that manipulate stream objects accessed through handles of type SIO_Handle. The device independence is afforded by having a common high-level abstraction appropriate for real- time applications, continuous streams of data, that can be associated with a variety of devices.
Page 413 SIO Module var mySio = bios.SIO.create("mySio"); The following properties can be set for an SIO object in the SIO Object Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏ comment . Type a comment to identify this SIO object. Tconf Name: comment Type: String Example:...
Page 414 SIO Module ❏ Buffer alignment . Specify the memory alignment to use for stream buffers if Model is Standard. For example, if you select 16, the buffer must begin at an address that is a multiple of 16. The default is 1, which means the buffer can begin at any address.
Page 415 SIO Module ❏ use callback function . Check this box if you want to use this SIO object with a callback function. In most cases, the callback function is SWI_andnHook or a similar function that posts a SWI. Checking this box allows the SIO object to be used with SWI threads. Tconf Name: useCallBackFxn Type: Bool Example:...
Page 416 SIO_bufsize SIO_bufsize Return the size of the buffers used by a stream C Interface Syntax size = SIO_bufsize(stream); Parameters SIO_Handle stream; Return Value size_t size; SIO_bufsize returns the size of the buffers used by stream. Description This API can be used only if the model is SIO_STANDARD. SIO_segid See Also 2-388...
Page 417 SIO_create SIO_create Open a stream C Interface Syntax stream = SIO_create(name, mode, bufsize, attrs); Parameters String name; /* name of device */ mode; /* SIO_INPUT or SIO_OUTPUT */ size_t bufsize; /* stream buffer size */ SIO_Attrs *attrs; /* pointer to stream attributes */ SIO_Handle stream;...
Page 418 SIO_create struct SIO_Attrs { /* stream attributes */ nbufs; /* number of buffers */ segid; /* buffer segment ID */ size_t align; /* buffer alignment */ Bool flush; /* TRUE->don't block in DEV_idle */ model; /* SIO_STANDARD,SIO_ISSUERECLAIM */ timeout; /* passed to DEV_reclaim */ SIO_Callback *callback;...
Page 419 SIO_create ❏ callback. Specifies pointer channel-specific callback information. The SIO_Callback structure is defined by the SIO module to match the DEV_Callback structure. This structure contains the callback function and two function arguments. The callback function is typically SWI_andnHook or a similar function that posts a SWI.
Page 420 SIO_ctrl SIO_ctrl Perform a device-dependent control operation C Interface Syntax status = SIO_ctrl(stream, cmd, arg); Parameters SIO_Handle stream; /* stream handle */ cmd; /* command to device */ arg; /* arbitrary argument */ Return Value status; /* device status */ Description SIO_ctrl causes a control operation to be issued to the device associated with stream.
Page 421 SIO_delete SIO_delete Close a stream and free its buffers C Interface Syntax status = SIO_delete(stream); Parameters SIO_Handle stream; /* stream object */ Return Value status; /* result of operation */ SIO_delete idles the device before freeing the stream object and buffers. Description If the stream being deleted was opened for input, then any pending input data is discarded.
Page 422 SIO_flush SIO_flush Flush a stream C Interface Syntax status = SIO_flush(stream); Parameters SIO_Handle stream; /* stream handle */ Return Value status; /* result of operation */ SIO_flush causes all pending data to be discarded regardless of the Description mode of the stream. SIO_flush differs from SIO_idle in that SIO_flush never suspends program execution to complete processing of data, even for a stream created in output mode.
Page 423 SIO_get SIO_get Get a buffer from stream C Interface Syntax nmadus = SIO_get(stream, bufp); Parameters SIO_Handle stream /* stream handle */ *bufp; /* pointer to a buffer */ Return Value nmadus; /* number of MADUs read or error if negative */ Description SIO_get exchanges an empty buffer with a non-empty buffer from stream.
Page 424 SIO_get For other architectures, size_t is: ❏ ’C28x - unsigned long ❏ ’C54x/’C55x/’C6x - unsigned int Since this operation is generally accomplished by redirection rather than by copying data, references to the contents of the buffer pointed to by bufp must be recomputed after the call to SIO_get. A task switch occurs when calling SIO_get if there are no non-empty data buffers in stream.
Page 425 SIO_idle SIO_idle Idle a stream C Interface Syntax status = SIO_idle(stream); Parameters SIO_Handle stream; /* stream handle */ Return Value status; /* result of operation */ If stream is being used for output, SIO_idle causes any currently buffered Description data to be transferred to the output device associated with stream. SIO_idle suspends program execution for as long as is required for the data to be consumed by the underlying device.
Page 426 SIO_issue SIO_issue Send a buffer to a stream C Interface Syntax status = SIO_issue(stream, pbuf, nmadus, arg); Parameters SIO_Handle stream; /* stream handle */ pbuf; /* pointer to a buffer */ size_t nmadus; /* number of MADUs in the buffer */ arg;...
Page 427 SIO_issue the data that it was issued with. arg provides a user argument as a method for a client to associate additional information with a particular buffer of data. SIO_issue is used in conjunction with SIO_reclaim to operate a stream opened in SIO_ISSUERECLAIM mode.
Page 428 SIO_put SIO_put Put a buffer to a stream C Interface Syntax nmadus = SIO_put(stream, bufp, nmadus); Parameters SIO_Handle stream; /* stream handle */ *bufp; /* pointer to a buffer */ size_t nmadus; /* number of MADUs in the buffer */ Return Value nmadus;...
Page 429 SIO_put Since this operation is generally accomplished by redirection rather than by copying data, references to the contents of the buffer pointed to by bufp must be recomputed after the call to SIO_put. A task switch occurs when calling SIO_put if there are no empty data buffers in the stream.
Page 430 SIO_ready SIO_ready Determine if device for stream is ready C Interface Syntax status = SIO_ready(stream); Parameters SIO_Handle stream; Return Value status; /* result of operation */ SIO_ready returns TRUE if a stream is ready for input or output. Description If you are using SIO objects with SWI threads, you may want to use SIO_ready to avoid calling SIO_reclaim when it may fail because no buffers are available.
Page 431 SIO_reclaim SIO_reclaim Request a buffer back from a stream C Interface Syntax nmadus = SIO_reclaim(stream, pbufp, parg); Parameters SIO_Handle stream; /* stream handle */ *pbufp; /* pointer to the buffer */ *parg; /* pointer to a user argument */ Return Value nmadus;...
Page 432 SIO_reclaim Failure of SIO_reclaim indicates that no buffer was returned to the client. Therefore, if SIO_reclaim fails, the client should not attempt to de- reference pbufp, since it is not guaranteed to contain a valid buffer pointer. An inconsistency exists between the sizes of buffers in a stream and the return types corresponding to these sizes.
Page 433 SIO_reclaim A task switch occurs when calling SIO_reclaim if timeout is not set to 0, and there are no data buffers available to be returned. ❏ The Constraints and stream must created with attrs.model Calling Context SIO_ISSUERECLAIM. ❏ There must be at least one outstanding SIO_issue when an SIO_reclaim call is made.
Page 434 SIO_reclaimx SIO_reclaimx Request a buffer back from a stream, including frame status C Interface Syntax nmadus = SIO_reclaimx(stream, *pbufp, *parg, *pfstatus); Parameters SIO_Handle stream; /* stream handle */ *pbufp; /* pointer to the buffer */ *parg; /* pointer to a user argument */ *pfstatus;...
Page 435 SIO_segid SIO_segid Return the memory segment used by the stream C Interface Syntax segid = SIO_segid(stream); Parameters SIO_Handle stream; Return Value segid; /* memory segment ID */ SIO_segid returns the identifier of the memory segment that stream uses Description for buffers. See Also SIO_bufsize Application Program Interface...
Page 436 SIO_select SIO_select Select a ready device C Interface Syntax mask = SIO_select(streamtab, nstreams, timeout); Parameters SIO_Handle streamtab; /* stream table */ nstreams; /* number of streams */ timeout; /* return after this many system clock ticks */ Return Value mask; /* stream ready mask */ Description SIO_select waits until one or more of the streams in the streamtab[] array...
Page 437 SIO_select ❏ streamtab must contain handles of type SIO_Handle returned from Constraints and Calling Context 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. ❏...
Page 438 SIO_staticbuf SIO_staticbuf Acquire static buffer from stream C Interface Syntax nmadus = SIO_staticbuf(stream, bufp); SIO_Handle stream; /* stream handle */ Parameters *bufp; /* pointer to a buffer */ Return Value nmadus; /* number of MADUs in buffer */ Description SIO_staticbuf returns buffers for static streams that were configured statically.
Page 439 SIO_staticbuf ❏ SIO_staticbuf should only be called for streams that are defined Constraints and Calling Context 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.
Page 440: Sts Module
STS Module 2.25 STS Module The STS module is the statistics objects manager. ❏ STS_add. Update statistics using provided value Functions ❏ STS_delta. Update statistics using difference between provided value and setpoint ❏ STS_reset. Reset values stored in STS object ❏...
Page 441: Statistics Units For Hwi, Pip, Prd, And Swi Modules
STS Module Name Type Default (Enum Options) numB Int32 numC Int32 Description The STS module manages objects called statistics accumulators. Each STS object accumulates the following statistical information about an arbitrary 32-bit wide data series: ❏ Count . The number of values in an application-supplied data series ❏...
Page 442 STS Module operation accumulates the difference between the value you pass and the previous value and updates the previous value to the value you pass. By using custom STS objects and the STS operations, you can do the following: ❏ Count the number of occurrences of an event . You can pass a value of 0 to STS_add.
Page 443: Statistics Accumulation On The Host
STS Module maximum value, the last 32-bit value passed to the object, the number of samples (up to 2 - 1 samples), and the 32-bit sum of all samples. These statistics are accumulated on the target in real-time until the host reads and clears these values on the target.
Page 444 STS Module ❏ prev . The initial 32-bit history value to use in this object. Tconf Name: previousVal Type: Int32 Example: mySts.previousVal = 0; ❏ unit type . The unit type property enables you to choose the type of time base units. ■...
Page 445 STS_add STS_add Update statistics using the provided value C Interface Syntax STS_add(sts, value); Parameters STS_Handle sts; /* statistics object handle */ LgInt value; /* new value to update statistics object */ Return Value Void Reentrant Description STS_add updates a custom STS object’s Total, Count, and Max fields using the data value you provide.
Page 446 STS_delta STS_delta Update statistics using difference between provided value & setpoint C Interface Syntax STS_delta(sts,value); Parameters STS_Handle sts; /* statistics object handle */ LgInt value; /* new value to update statistics object */ Return Value Void Reentrant Description Each STS object contains a previous value that can be initialized with Tconf or with a call to STS_set.
Page 447 STS_reset STS_reset Reset the values stored in an STS object C Interface Syntax STS_reset(sts); Parameters STS_Handle sts; /* statistics object handle */ Return Value Void Reentrant Description STS_reset resets the values stored in an STS object. The Count and Total fields are set to 0 and the Max field is set to the largest negative number.
Page 448 STS_set STS_set Save a value for STS_delta C Interface Syntax STS_set(sts, value); Parameters STS_Handle sts; /* statistics object handle */ LgInt value; /* new value to update statistics object */ Return Value Void Reentrant Description STS_set can be used in conjunction with STS_delta to monitor the difference between a variable and a desired value or to benchmark program performance.
Page 449 STS_set 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 Application Program Interface 2-421...
Page 450: Swi Module
SWI Module 2.26 SWI Module The SWI module is the software interrupt manager. ❏ SWI_andn. Clear bits from SWI's mailbox; post if becomes 0. Functions ❏ SWI_andnHook. Specialized version of SWI_andn for use as hook function for configured DSP/BIOS objects. Both its arguments are of type (Arg).
Page 451 SWI Module struct SWI_Attrs { /* SWI attributes */ SWI_Fxn fxn; /* address of SWI function */ arg0; /* first arg to function */ arg1; /* second arg to function */ priority; /* Priority of SWI object */ mailbox; /* check for SWI posting */ SWI_Attrs SWI_ATTRS = { /* Default attribute values */ (SWI_Fxn)FXN_F_nop, /* SWI function */...
Page 452 SWI Module Note: SWI functions are called after the processor register state has been saved. SWI functions can be written in C or assembly and must follow the C calling conventions described in the compiler manual. Note: RTS Functions Callable from TSK Threads Only Many runtime support (RTS) functions use lock and unlock functions to prevent reentrancy.
Page 453 SWI Module Treat mailbox Treat mailbox Does not modify as bitmask as counter mailbox Always post SWI_or SWI_inc SWI_post Post if SWI_andn SWI_dec becomes 0 The SWI_disable and SWI_enable operations allow you to post several SWIs and enable them all for execution at the same time. The SWI priorities then determine which SWI runs first.
Page 454 SWI Module SWI Manager The following global property can be set for the SWI module in the SWI Properties Manager Properties dialog of the DSP/BIOS Configuration Tool or in a Tconf script: ❏ Object Memory . The memory segment that contains the SWI objects.
Page 455 SWI Module ❏ mailbox . The initial value of 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.
Page 456 SWI_andn SWI_andn Clear bits from SWI’s mailbox and post if mailbox becomes 0 C Interface Syntax SWI_andn(swi, mask); Parameters SWI_Handle swi; /* SWI object handle*/ mask /* inverse value to be ANDed */ Return Value Void Reentrant Description SWI_andn is used to conditionally post a software interrupt. SWI_andn clears the bits specified by a mask from SWI’s internal mailbox.
Page 457 SWI_andn The following figure shows an example of how a mailbox with an initial value of 3 can be cleared by two calls to SWI_andn with values of 2 and 1. The entire mailbox could also be cleared with a single call to SWI_andn with a value of 3.
Page 458 SWI_andnHook SWI_andnHook Clear bits from SWI’s mailbox and post if mailbox becomes 0 C Interface Syntax SWI_andnHook(swi, mask); Parameters swi; /* SWI object handle*/ mask /* value to be ANDed */ Return Value Void Reentrant Description SWI_andnHook is a specialized version of SWI_andn for use as hook function for configured DSP/BIOS objects.
Page 459 SWI_create SWI_create Create a software interrupt C Interface Syntax swi = SWI_create(attrs); Parameters SWI_Attrs *attrs; /* pointer to swi attributes */ Return Value SWI_Handle swi; /* handle for new swi object */ SWI_create creates a new SWI object. If successful, SWI_create returns Description the handle of the new SWI object.
Page 460 SWI_create The mailbox attribute is used either to determine whether to post the SWI or as a value that can be evaluated within the SWI function. All default attribute values are contained in the constant SWI_ATTRS, which can be assigned to a variable of type SWI_Attrs prior to calling SWI_create.
Page 461 SWI_dec SWI_dec Decrement SWI’s mailbox value and post if mailbox becomes 0 C Interface Syntax SWI_dec(swi); Parameters SWI_Handle swi; /* SWI object handle*/ Return Value Void Reentrant Description SWI_dec is used to conditionally post a software interrupt. SWI_dec decrements the value in SWI’s mailbox by 1. If SWI’s mailbox value becomes 0, SWI_dec posts the SWI.
Page 462 SWI_delete SWI_delete Delete a software interrupt C Interface Syntax SWI_delete(swi); Parameters SWI_Handle swi; /* SWI object handle */ Return Value Void SWI_delete uses MEM_free to free the SWI object referenced by swi. Description SWI_delete calls MEM_free to delete the SWI object. MEM_free must acquire a lock to the memory before proceeding.
Page 463 SWI_disable SWI_disable Disable software interrupts C Interface Syntax SWI_disable(); Parameters Void Return Value Void Reentrant Description SWI_disable and SWI_enable control software interrupt processing. SWI_disable disables all other SWI functions from running until SWI_enable is called. Hardware interrupts can still run. SWI_disable and SWI_enable let you ensure that statements that must be performed together during critical processing are not interrupted.
Page 464 SWI_enable SWI_enable Enable software interrupts C Interface Syntax SWI_enable(); Parameters Void Return Value Void Reentrant Description SWI_disable and SWI_enable control software interrupt processing. SWI_disable disables all other SWI functions from running until SWI_enable is called. Hardware interrupts can still run. See the SWI_disable section for details.
Page 465 SWI_getattrs SWI_getattrs Get attributes of a software interrupt C Interface Syntax SWI_getattrs(swi, attrs); Parameters SWI_Handle swi; /* handle of the swi */ SWI_Attrs *attrs; /* pointer to swi attributes */ Return Value Void Description SWI_getattrs retrieves attributes of an existing SWI object. The swi parameter specifies the address of the SWI object whose attributes are to be retrieved.
Page 466 SWI_getattrs The following example uses SWI_getattrs: extern SWI_Handle swi; SWI_Attrs attrs; SWI_getattrs(swi, &attrs); attrs.priority = 5; SWI_setattrs(swi, &attrs); ❏ SWI_getattrs cannot be called from a SWI or HWI. Constraints and Calling Context ❏ The attrs parameter cannot be NULL. See Also SWI_create SWI_delete SWI_setattrs...
Page 467 SWI_getmbox SWI_getmbox Return a SWI’s mailbox value C Interface Syntax num = Uns SWI_getmbox(); Parameters Void Return Value /* mailbox value */ Reentrant Description SWI_getmbox returns the value that SWI’s mailbox had when the SWI started running. DSP/BIOS saves the mailbox value internally so that SWI_getmbox can access it at any point within a SWI object’s function.
Page 468 SWI_getpri SWI_getpri Return a SWI’s priority mask C Interface Syntax key = SWI_getpri(swi); Parameters SWI_Handle swi; /* SWI object handle*/ Return Value /* Priority mask of swi */ Reentrant Description SWI_getpri returns the priority mask of the SWI passed in as the argument.
Page 469 SWI_inc SWI_inc Increment SWI’s mailbox value and post the SWI C Interface Syntax SWI_inc(swi); Parameters SWI_Handle swi; /* SWI object handle*/ Return Value Void Reentrant Description SWI_inc increments the value in SWI’s mailbox by 1 and posts the SWI regardless of the resulting mailbox value. You can decrement a mailbox value using SWI_dec, which only posts the SWI if the mailbox value is 0.
Page 470 SWI_isSWI SWI_isSWI Check to see if called in the context of a SWI C Interface Syntax result = SWI_isSWI(Void); Void Parameters Return Value Bool result; /* TRUE if in SWI context, FALSE otherwise */ Reentrant Description This macro returns TRUE when it is called within the context of a SWI or PRD function.
Page 471 SWI_or SWI_or OR mask with the value contained in SWI’s mailbox field C Interface Syntax SWI_or(swi, mask); Parameters SWI_Handle swi; /* SWI object handle*/ mask; /* value to be ORed */ Return Value Void Reentrant Description SWI_or is used to post a software interrupt. SWI_or sets the bits specified by a mask in SWI’s mailbox.
Page 472 SWI_orHook SWI_orHook OR mask with the value contained in SWI’s mailbox field C Interface Syntax SWI_orHook(swi, mask); Parameters swi; /* SWI object handle*/ mask; /* value to be ORed */ Return Value Void Reentrant Description SWI_orHook is used to post a software interrupt, and should be used when hook functionality is required for DSP/BIOS hook objects.
Page 473 SWI_post SWI_post Post a software interrupt C Interface Syntax SWI_post(swi); Parameters SWI_Handle swi; /* SWI object handle*/ Return Value Void Reentrant Description SWI_post is used to post a software interrupt regardless of the mailbox value. No change is made to the SWI object’s mailbox value. To have a PRD object post a SWI object’s function, you can set _SWI_post as the function property of a PRD object and the name of the SWI object you want to post its function as the arg0 property.
Page 474 SWI_raisepri SWI_raisepri Raise a SWI’s priority C Interface Syntax key = SWI_raisepri(mask); mask; /* mask of desired priority level */ Parameters Return Value key; /* key for use with SWI_restorepri */ Reentrant SWI_raisepri is used to raise the priority of the currently running SWI to Description the priority mask passed in as the argument.
Page 475 SWI_restorepri SWI_restorepri Restore a SWI’s priority C Interface Syntax SWI_restorepri(key); Parameters key; /* key to restore original priority level */ Return Value Void Reentrant Description SWI_restorepri restores the priority to the SWI's priority prior to the SWI_raisepri call returning the key. SWI_restorepri can be used in conjunction with SWI_raisepri to provide a mutual exclusion mechanism without disabling all SWIs.
Page 476 SWI_self SWI_self Return address of currently executing SWI object C Interface Syntax curswi = SWI_self(); Void Parameters Return Value SWI_Handle swi; /* handle for current swi object */ Reentrant Description SWI_self returns the address of the currently executing SWI. ❏ SWI_self cannot be called from an HWI or TSK level. Constraints and Calling Context ❏...
Page 477 SWI_setattrs SWI_setattrs Set attributes of a software interrupt C Interface Syntax SWI_setattrs(swi, attrs); Parameters SWI_Handle swi; /* handle of the swi */ SWI_Attrs *attrs; /* pointer to swi attributes */ Return Value Void Description SWI_setattrs sets attributes of an existing SWI object. The swi parameter specifies the address of the SWI object whose attributes are to be set.
Page 478 SWI_setattrs The following example uses SWI_setattrs: extern SWI_Handle swi; SWI_Attrs attrs; SWI_getattrs(swi, &attrs); attrs.priority = 5; SWI_setattrs(swi, &attrs); ❏ SWI_setattrs must not be used to set the attributes of a SWI that is Constraints and Calling Context preempted or is ready to run. ❏...
Page 479: Sys Module
SYS Module 2.27 SYS Module The SYS modules manages system settings. ❏ SYS_abort. Abort program execution Functions ❏ SYS_atexit. Stack an exit handler ❏ SYS_error. Flag error condition ❏ SYS_exit. Terminate program execution ❏ SYS_printf. Formatted output ❏ SYS_putchar. Output a single character ❏...
Page 480 SYS Module Module Configuration Parameters Name Type Default TRACESIZE Numeric TRACESEG Reference prog.get("DARAM") ABORTFXN Extern prog.extern("UTL_doAbort") ERRORFXN Extern prog.extern("UTL_doError") EXITFXN Extern prog.extern("UTL_halt") PUTCFXN Extern prog.extern("UTL_doPutc") Description The SYS module makes available a set of general-purpose functions that provide basic system services, such as halting program execution and printing formatted text.
Page 481 SYS Module ❏ Abort Function . The function to run if the application aborts by calling SYS_abort. The default function is _UTL_doAbort, which logs an error message and calls _halt. 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.
Page 482 SYS_abort SYS_abort Abort program execution C Interface Syntax SYS_abort(format, [arg,] ...); Parameters String format; /* format specification string */ arg; /* optional argument */ Return Value Void Description SYS_abort aborts program execution by calling the function bound to the configuration parameter Abort function, 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_abort.
Page 483 SYS_atexit SYS_atexit Stack an exit handler C Interface Syntax success = SYS_atexit(handler); Parameters handler /* exit handler function */ Return Value Bool success /* handler successfully stacked */ SYS_atexit pushes handler onto an internal stack of functions to be Description executed when SYS_exit is called.
Page 484 SYS_error SYS_error Flag error condition C Interface Syntax SYS_error(s, errno, [arg], ...); Parameters String /* error string */ errno; /* error code */ arg; /* optional argument */ Return Value Void Description SYS_error is used to flag DSP/BIOS error conditions. Application programs should call SYS_error to handle program errors.
Page 485 SYS_exit SYS_exit Terminate program execution C Interface Syntax SYS_exit(status); Parameters status; /* termination status code */ Return Value Void SYS_exit first pops a stack of handlers registered through the function Description SYS_atexit, and then terminates program execution by calling the function bound to the configuration parameter Exit function, passing on its original status parameter.
Page 486: Conversion Characters Recognized By Sys_Printf
SYS_printf SYS_printf Output formatted data C Interface Syntax SYS_printf(format, [arg,] ...); Parameters String format; /* format specification string */ arg; /* optional argument */ Return Value Void Description SYS_printf provides a subset of the capabilities found in the standard C library function printf.
Page 487 SYS_printf A dash (-) symbol causes the converted argument to be left-justified within a field of width characters with blanks following. A 0 (zero) causes the converted argument to be right-justified within a field of size width with leading 0s. If neither a dash nor 0 are given, the converted argument is right-justified in a field of size width, with leading blanks.
Page 488: Conversion Characters Recognized By Sys_Sprintf
SYS_sprintf SYS_sprintf Output formatted data C Interface Syntax SYS_sprintf (buffer, format, [arg,] ...); Parameters String buffer; /* output buffer */ String format; /* format specification string */ arg; /* optional argument */ Return Value Void Description SYS_sprintf provides a subset of the capabilities found in the standard C library function printf.
Page 489 SYS_sprintf Between the % and the conversion character, the following symbols or specifiers contained within square brackets can appear, in the order shown. %[-][0][width]type A dash (-) symbol causes the converted argument to be left-justified within a field of width characters with blanks following. A 0 (zero) causes the converted argument to be right-justified within a field of size width with leading 0s.
Page 490: Conversion Characters Recognized By Sys_Vprintf
SYS_vprintf SYS_vprintf Output formatted data C Interface Syntax SYS_vprintf(format, vargs); Parameters String format; /* format specification string */ va_list vargs; /* variable argument list reference */ Return Value Void Description SYS_vprintf provides a subset of the capabilities found in the standard C library function printf.
Page 491 SYS_vprintf Between the % and the conversion character, the following symbols or specifiers contained within square brackets can appear, in the order shown. %[-][0][width]type A dash (-) symbol causes the converted argument to be left-justified within a field of width characters with blanks following. A 0 (zero) causes the converted argument to be right-justified within a field of size width with leading 0s.
Page 492: Conversion Characters Recognized By Sys_Vsprintf
SYS_vsprintf SYS_vsprintf Output formatted data C Interface Syntax SYS_vsprintf(buffer, format, vargs); Parameters String buffer; /* output buffer */ String format; /* format specification string */ va_list vargs; /* variable argument list reference */ Return Value Void Description SYS_vsprintf provides a subset of the capabilities found in the standard C library function printf.
Page 493 SYS_vsprintf Between the % and the conversion character, the following symbols or specifiers contained within square brackets can appear, in the order shown. %[-][0][width]type A dash (-) symbol causes the converted argument to be left-justified within a field of width characters with blanks following. A 0 (zero) causes the converted argument to be right-justified within a field of size width with leading 0s.
Page 494 SYS_putchar SYS_putchar Output a single character C Interface Syntax SYS_putchar(c); Parameters Char /* next output character */ Return Value Void SYS_putchar outputs the character c by calling the system-dependent Description function bound to the configuration parameter Putc function. ((Putc function))(c) For systems with limited I/O capabilities, the function bound to Putc function might simply place c into a global buffer that can be examined after program termination.
Page 495: Events And Statistics Traced By Trc
TRC Module 2.28 TRC Module The TRC module is the trace manager. ❏ TRC_disable. Disable trace class(es) Functions ❏ TRC_enable. Enable trace type(s) ❏ TRC_query. Query trace class(es) Description The TRC module manages a set of trace control bits which control the real-time capture of program information through event logs and statistics accumulators.
Page 496 TRC Module All trace constants except TRC_GBLTARG are switched off initially. To → enable tracing you can use calls to TRC_enable or the DSP/BIOS Control Panel, which uses the TRC module internally. You do not need to enable tracing for messages written with LOG_printf or LOG_event and statistics added with STS_add or STS_delta.
Page 497 TRC_disable TRC_disable Disable trace class(es) C Interface Syntax TRC_disable(mask); Parameters mask; /* trace type constant mask */ Return Value Void Reentrant Description TRC_disable disables tracing of one or more trace types. Trace types are specified with a 32-bit mask. (See the TRC Module topic for a list of constants to use in the mask.) The following C code would disable tracing of statistics for software interrupts and periodic functions:...
Page 498 TRC_enable TRC_enable Enable trace type(s) C Interface Syntax TRC_enable(mask); Parameters mask; /* trace type constant mask */ Return Value Void Reentrant Description TRC_enable enables tracing of one or more trace types. Trace types are specified with a 32-bit mask. (See the TRC Module topic for a list of constants to use in the mask.) The following C code would enable tracing of statistics for software interrupts and periodic functions:...
Page 499 TRC_query TRC_query Query trace class(es) C Interface Syntax result = TRC_query(mask); Parameters mask; /* trace type constant mask */ Return Value result /* indicates whether all trace types enabled */ Reentrant Description TRC_query determines whether particular trace types are enabled. TRC_query returns 0 if all trace types in the mask are enabled.
Page 500: Tsk Module
TSK Module 2.29 TSK Module The TSK module is the task manager. ❏ TSK_checkstacks. Check for stack overflow Functions ❏ TSK_create. Create a task ready for execution ❏ TSK_delete. Delete a task ❏ TSK_deltatime. Update task STS with time difference ❏...
Page 501 TSK Module Constants, Types, typedef struct TSK_OBJ *TSK_Handle; /* task object handle*/ and Structures struct TSK_Attrs { /* task attributes */ priority; /* execution priority */ stack; /* pre-allocated stack */ size_t stacksize; /* stack size in MADUs */ #ifdef _55_ size_t sysstacksize;...
Page 502 TSK Module Configuration The following list shows the properties that can be configured in a Tconf Properties script, along with their types and default values. For details, see the TSK Manager Properties and TSK Object Properties headings. For descriptions of data types, see Section 1.4, DSP/BIOS Tconf Overview , page 1-3.
Page 503 TSK Module Name Type Default (Enum Options) exitFlag Bool true allocateTaskName Bool false order Int16 Description The TSK module makes available a set of functions that manipulate task objects accessed through handles of type TSK_Handle. Tasks represent independent threads of control that conceptually execute functions in parallel within a single C program;...
Page 504 TSK Module A single set of hook functions can be specified for the TSK module itself. To create additional sets of hook functions, use the HOOK Module. When you create the first HOOK object, any TSK module hook functions you have specified are automatically placed in a HOOK object called HOOK_KNL.
Page 505: Function Callability
TSK Module The Switch function and Ready function are called in such a way that they can use only functions allowed within a SWI handler. See Appendix A, Function Callability Table, for a list of functions that can be called by SWI handlers.
Page 506 TSK Module ❏ Default task priority . The default priority level for tasks that are created dynamically with TSK_create. This property applies to TSK objects created both with Tconf and with TSK_create. Tconf Name: PRIORITY Type: EnumInt Options: 1 to 15 Example: bios.TSK.PRIORITY = 1;...
Page 507 TSK Module ❏ Switch function . The name of a function to 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:...
Page 508 TSK Module same page. Automatically allocating the stack is recommended, since TSK_create makes sure this condition is satisfied. Tconf Name: manualStack Type: Extern Example: myTsk.manualStack = prog.extern("myStack"); ❏ Stack size . Enter the size (in MADUs) of the stack space to allocate for this task.
Page 509 TSK Module -pm or -op2 options, you should precede C functions called by task threads with the FUNC_EXT_CALLED pragma. See the online help for the C compiler for details. Tconf Name: fxn Type: Extern Example: myTsk.fxn = prog.extern("tskFxn"); ❏ Task function argument 0-7 . The arguments to pass to the task function.
Page 510 TSK_checkstacks TSK_checkstacks Check for stack overflow C Interface Syntax TSK_checkstacks(oldtask, newtask); Parameters TSK_Handle oldtask; /* handle of task switched from */ TSK_Handle newtask; /* handle of task switched to */ Return Value Void Description TSK_checkstacks calls SYS_abort with an error message if either oldtask or newtask has a stack in which the last location no longer contains the initial value TSK_STACKSTAMP.
Page 511 TSK_create TSK_create Create a task ready for execution C Interface Syntax task = TSK_create(fxn, attrs, [arg,] ...); Parameters fxn; /* pointer to task function */ TSK_Attrs *attrs; /* pointer to task attributes */ arg; /* task arguments */ Return Value TSK_Handle task;...
Page 512 TSK_create TSK_exit is automatically called if and when the task returns from fxn. If attrs is NULL, the new task is assigned a default set of attributes. Otherwise, the task’s attributes are specified through a structure of type TSK_Attrs, which is defined as follows. struct TSK_Attrs { /* task attributes */ priority;...
Page 513 TSK_create number of MADUs to be allocated for the task’s private system stack. This attribute defaults to the value of the configuration parameter Default system stack size (preset to 256). The stackseg attribute specifies the memory segment to use when allocating the task stack with MEM_alloc;...
Page 514 TSK_create ❏ The stackseg 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. MEM_alloc See Also SYS_error TSK_delete TSK_exit 2-486...
Page 515 TSK_delete TSK_delete Delete a task C Interface Syntax TSK_delete(task); Parameters TSK_Handle task; /* task object handle */ Return Value Void Description TSK_delete removes the task from all internal queues and calls MEM_free to free the task object and stack. task should be in a state that does not violate any of the listed constraints.
Page 516 TSK_deltatime TSK_deltatime Update task statistics with time difference C Interface Syntax TSK_deltatime(task); Parameters TSK_Handle task; /* task object handle */ Return Value Void This function accumulates the time difference from when a task is made Description ready to the time TSK_deltatime is called. These time differences are accumulated in the task’s internal STS object and can be used to determine whether or not a task misses real-time deadlines.
Page 517 TSK_deltatime /* Get time difference and add it to task's STS object */ TSK_deltatime(TSK_self()); In the example above, the task blocks on SIO_get and the device driver posts a semaphore that readies the task. DSP/BIOS sets the task’s statistics object with the current time when the semaphore becomes available and the task is made ready to run.
Page 518 TSK_disable TSK_disable Disable DSP/BIOS task scheduler C Interface Syntax TSK_disable(); Parameters Void Return Value Void TSK_disable disables the DSP/BIOS task scheduler. The current task Description continues to execute (even if a higher priority task can become ready to run) until TSK_enable is called. TSK_disable does not disable interrupts, but is instead used before disabling interrupts to make sure a context switch to another task does not occur when interrupts are disabled.
Page 519 TSK_enable TSK_enable Enable DSP/BIOS task scheduler C Interface Syntax TSK_enable(); Parameters Void Return Value Void TSK_enable is used to reenable the DSP/BIOS task scheduler after Description TSK_disable has been called. Since TSK_disable calls can be nested, the task scheduler is not enabled until TSK_enable is called the same number of times as TSK_disable.
Page 520 TSK_exit TSK_exit Terminate execution of the current task C Interface Syntax TSK_exit(); Parameters Void Return Value Void TSK_exit terminates execution of the current task, changing its mode Description from TSK_RUNNING to TSK_TERMINATED. If all tasks have been terminated, or if all remaining tasks have their exitflag attribute set to FALSE, then DSP/BIOS terminates the program as a whole by calling the function SYS_exit with a status code of 0.
Page 521 TSK_getenv TSK_getenv Get task environment pointer C Interface Syntax environ = TSK_getenv(task); Parameters TSK_Handle task; /* task object handle */ Return Value environ; /* task environment pointer */ TSK_getenv returns the environment pointer of the specified task. The Description environment pointer, environ, references an arbitrary application-defined data structure.
Page 522 TSK_geterr TSK_geterr Get task error number C Interface Syntax errno = TSK_geterr(task); Parameters TSK_Handle task; /* task object handle */ Return Value errno; /* error number */ Each task carries a task-specific error number. This number is initially Description SYS_OK, but it can be changed by TSK_seterr. TSK_geterr returns the current value of this number.
Page 523 TSK_getname TSK_getname Get task name C Interface Syntax name = TSK_getname(task); Parameters TSK_Handle task; /* task object handle */ Return Value String name; /* task name */ TSK_getname returns the task’s name. Description For tasks created with Tconf, the name is available to this function only if the "Allocate Task Name on Target"...
Page 524 TSK_getpri TSK_getpri Get task priority C Interface Syntax priority = TSK_getpri(task); Parameters TSK_Handle task; /* task object handle */ Return Value priority; /* task priority */ TSK_getpri returns the priority of task. Description See Also TSK_setenv TSK_seterr TSK_setpri 2-496...
Page 525 TSK_getsts TSK_getsts Get the handle of the task’s STS object C Interface Syntax sts = TSK_getsts(task); Parameters TSK_Handle task; /* task object handle */ Return Value STS_Handle sts; /* statistics object handle */ This function provides access to the task’s internal STS object. For Description example, you can want the program to check the maximum value to see if it has exceeded some value.
Page 526 TSK_isTSK TSK_isTSK Check to see if called in the context of a TSK C Interface Syntax result = TSK_isTSK(Void); Parameters Void Return Value Bool result; /* TRUE if in TSK context, FALSE otherwise */ Reentrant Description This macro returns TRUE when it is called within the context of a TSK or IDL function.
Page 527 TSK_itick TSK_itick Advance the system alarm clock (interrupt use only) C Interface Syntax TSK_itick(); Parameters Void Return Value Void TSK_itick increments the system alarm clock, and readies any tasks Description blocked on TSK_sleep or SEM_pend whose timeout intervals have expired. ❏...
Page 528 TSK_self TSK_self Returns handle to the currently executing task C Interface Syntax curtask = TSK_self(); Parameters Void Return Value TSK_Handle curtask; /* handle for current task object */ TSK_self returns the object handle for the currently executing task. This Description function is useful when inspecting the object or when the current task changes its own priority through TSK_setpri.
Page 529 TSK_setenv TSK_setenv Set task environment C Interface Syntax TSK_setenv(task, environ); Parameters TSK_Handle task; /* task object handle */ environ; /* task environment pointer */ Return Value Void Description TSK_setenv sets the task environment pointer to environ. The environment pointer, environ, references an arbitrary application-defined data structure.
Page 530 TSK_seterr TSK_seterr Set task error number C Interface Syntax TSK_seterr(task, errno); Parameters TSK_Handle task; /* task object handle */ 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.
Page 531 TSK_setpri TSK_setpri Set a task’s execution priority C Interface Syntax oldpri = TSK_setpri(task, newpri); Parameters TSK_Handle task; /* task object handle */ newpri; /* task’s new priority */ Return Value oldpri; /* task’s old priority */ Description TSK_setpri sets the execution priority of task to newpri, and returns that task’s old priority value.
Page 532 TSK_settime TSK_settime Reset task statistics previous value to current time C Interface Syntax TSK_settime(task); Parameters TSK_Handle task; /* task object handle */ Return Value Void Your application can call TSK_settime before a task enters its processing Description loop in order to ensure your first call to TSK_deltatime is as accurate as possible and doesn’t reflect the time difference since the time the task was created.
Page 533 TSK_settime In the previous example, the task blocks on SIO_get and the device driver posts a semaphore that readies the task. DSP/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.
Page 534 TSK_sleep TSK_sleep Delay execution of the current task C Interface Syntax TSK_sleep(nticks); Parameters nticks; /* number of system clock ticks to sleep */ Return Value Void TSK_sleep changes the current task’s mode from TSK_RUNNING to Description TSK_BLOCKED, and delays its execution for nticks increments of the system clock.
Page 535 TSK_stat TSK_stat Retrieve the status of a task C Interface Syntax TSK_stat(task, statbuf); Parameters TSK_Handle task; /* task object handle */ TSK_Stat *statbuf; /* pointer to task status structure */ Return Value Void Description TSK_stat retrieves attribute values and status information about a task. Status information is returned through statbuf, which references a structure of type TSK_Stat defined as follows: struct TSK_Stat {...
Page 536 TSK_tick TSK_tick Advance the system alarm clock C Interface Syntax TSK_tick(); Parameters Void Return Value Void TSK_tick increments the system clock, and readies any tasks blocked on Description TSK_sleep or SEM_pend whose timeout intervals have expired. TSK_tick can be invoked by an HWI or by the currently executing task. The latter is particularly useful for testing timeouts in a controlled environment.
Page 537 TSK_time TSK_time Return current value of system clock C Interface Syntax curtime = TSK_time(); Parameters Void Return Value curtime; /* current time */ TSK_time returns the current value of the system alarm clock. Description Note that since the system clock is usually updated asynchronously via TSK_itick or TSK_tick, curtime can lag behind the actual system time.
Page 538 TSK_yield TSK_yield Yield processor to equal priority task C Interface Syntax TSK_yield(); Parameters Void Return Value Void TSK_yield yields the processor to another task of equal priority. Description A task switch occurs when you call TSK_yield if there is an equal priority task ready to run.
Page 539: Std.h And Stdlib.h Functions
std.h and stdlib.h functions 2.30 std.h and stdlib.h functions This section contains descriptions of special utility macros found in std.h and DSP/BIOS standard library functions found in stdlib.h. ❏ ArgToInt. Cast an Arg type parameter as an integer type. Macros ❏...
Page 540 std.h and stdlib.h functions Note: RTS Functions Callable from TSK Threads Only Many runtime support (RTS) functions use lock and unlock functions to prevent reentrancy. However, DSP/BIOS SWI and HWI threads cannot call LCK_pend and LCK_post. As a result, RTS functions that call LCK_pend or LCK_post must not be called in the context of a SWI or HWI thread .
Page 541: A Function Callability And Error Tables
Appendix A Function Callability and Error Tables This appendix provides tables describing TMS320C55x errors and function callability. Topic Page A.1 Function Callability Table ........A–2 A.2 DSP/BIOS Error Codes .
Page 542: A-1 Function Callability
Function Callability Table Function Callability Table The following table indicates what types of threads can call each of the DSP/BIOS functions. The Possible Context Switch column indicates whether another thread may be run as a result of this function. For example, the function may block on a resource or it may make another thread ready to run.
Page 543 Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? C55_l2DisableMIR, C55_l2DisableMIR1 C55_l2EnableMIR, C55_l2EnableMIR1 C55_l2SetIntPriority C55_plug CLK_countspms CLK_cpuCyclesPerHtime CLK_cpuCyclesPerLtime CLK_gethtime CLK_getltime CLK_getprd CLK_reconfig CLK_start CLK_stop DEV_createDevice Yes* DEV_deleteDevice Yes* DEV_match GBL_getClkin GBL_getFrequency GBL_getProcId GBL_getVersion...
Page 544 Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? HST_getpipe HWI_disable HWI_dispatchPlug HWI_enable Yes* HWI_enter HWI_exit HWI_isHWI HWI_restore Yes* IDL_run LCK_create Yes* LCK_delete Yes* LCK_pend Yes* LCK_post Yes* LOG_disable LOG_enable LOG_error LOG_event LOG_message...
Page 545 Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? MSGQ_close MSGQ_count Yes* Yes* MSGQ_free MSGQ_get Yes* Yes* Yes* MSGQ_getAttrs MSGQ_getDstQueue MSGQ_getMsgId MSGQ_getMsgSize MSGQ_getSrcQueue MSGQ_isLocalQueue MSGQ_locate MSGQ_locateAsync MSGQ_open Yes* Yes* Yes* MSGQ_put MSGQ_release MSGQ_setErrorHandler...
Page 546 Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? PWRM_changeSetpoint Yes* PWRM_configure PWRM_getCapabilities PWRM_getCurrentSetpoint PWRM_getDependencyCount PWRM_getNumSetpoints PWRM_getSetpointInfo PWRM_getTransitionLatency PWRM_idleClocks PWRM_registerNotify Yes* PWRM_releaseDependency PWRM_setDependency PWRM_sleepDSP Yes* PWRM_unregisterNotify QUE_create Yes* QUE_delete Yes* QUE_dequeue QUE_empty QUE_enqueue...
Page 547 Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? RTDX_isOutputEnabled RTDX_read RTDX_readNB RTDX_sizeofInput RTDX_write SEM_count SEM_create Yes* SEM_delete Yes* Yes* SEM_new SEM_pend Yes* Yes* Yes* SEM_pendBinary Yes* Yes* Yes* SEM_post Yes* SEM_postBinary Yes*...
Page 548 Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? SWI_create Yes* SWI_dec Yes* SWI_delete Yes* SWI_disable SWI_enable Yes* SWI_getattrs SWI_getmbox SWI_getpri SWI_inc Yes* SWI_isSWI SWI_or Yes* SWI_orHook Yes* SWI_post Yes* SWI_raisepri SWI_restorepri SWI_self...
Page 549: Rts Function Calls
Function Callability Table Function Callable Callable Callable by Possible Callable by TSKs? by SWIs? HWIs? Context from Switch? main()? TSK_exit Yes* TSK_getenv TSK_geterr TSK_getname TSK_getpri TSK_getsts TSK_isTSK TSK_itick TSK_self TSK_setenv TSK_seterr TSK_setpri Yes* TSK_settime TSK_sleep Yes* TSK_stat Yes* Yes* TSK_tick Yes* TSK_time TSK_yield...
Page 550 Function Callability Table Function Callable Callable Callable by Possible by TSKs? by SWIs? HWIs? Context Switch? srand Yes* strftime Yes* vfprintf Yes* vprintf Yes* vsprintf Yes* Note: *See section 2.30, std.h and stdlib.h functions, page 2-511 for more information. A-10...
Page 551: Error Codes
DSP/BIOS Error Codes DSP/BIOS Error Codes Table A-3 Error Codes Name Value SYS_Errors[Value] "(SYS_OK)” SYS_OK "(SYS_EALLOC): segid = %d, size = %u, align = %u" SYS_EALLOC Memory allocation error. SYS_EFREE "(SYS_EFREE): segid = %d, ptr = ox%x, size = %u" The memory free function associated with the indicated memory segment was unable to free the indicated size of memory at the address indicated by SYS_ENODEV...
Page 552 A-12...
Page 553 Appendix B C55x DSP/BIOS Register Usage This appendix provides tables describing the TMS320C55x register conventions in terms of preservation across multi-threaded context switching and preconditions. Topic Page B.1 Overview..........B–2 B.2 Register Conventions .
Page 554: B.2 Register Conventions
Overview Overview In a multi-threaded application using DSP/BIOS, it is necessary to know which registers can or cannot be modified. Furthermore, users need to understand which registers are preserved across task context switches and interrupts. Register Conventions The following definitions describe the various possible register handling behaviors: ❏...
Page 555 Register Conventions Register Register Name Type Notes BK03, BK47, BKC Circular Buffer Size Registers BRC0, BRC1 Block-repeat counters BRS1 BRC1 save register BSA01, BSA23, Circular Buffer Start Address Regis- BSA45, BSA67, BSAC ters (X)CDP Coefficient Data Pointer CFCT Control-flow context register Computed Single Repeat DBIER0, DBIER1 Debug Interrupt Enable Registers...
Page 556: B.3 Status Register Conventions
Status Register Conventions Status Register Conventions The status registers (ST0-ST2) are automatically preserved by hardware during interrupt processing such that upon return from an HWI, these status registers are returned to the state they were in prior to the interrupt. ST3 bits are generally propagated except as shown below.
Page 557 Status Register Conventions Register Status Bit Status Bit Name Type Notes External flag Hold mode INTM Interrupt Mask Restored after int Computation mode for the D unit Restored after int SATD Saturation mode for the D unit Restored after int SXMD Sign-extension mode for the D unit Restored after int...
Page 559 Appendix C DSP/BIOS for OMAP 2320 This appendix describes things you need to know about DSP/BIOS in order to use it with the OMAP 2320 platform. Topic Page C.1 Overview..........C–2 C.2 OMAP 2320 and the CLK Module .
Page 560: C.2 Omap 2320 And The Clk Module
Overview Overview DSP/BIOS has been enhanced to provide seamless support for the core timers and Level 2 Interrupt Controller (L2IC) present within the OMAP 2320. The CLK module functionality is now driven by the core timers. The HWI module APIs can define and manipulate level 2 interrupts in addition to level 1 interrupts.
Page 561 OMAP 2320 and the CLK Module In the Gconf configuration tool, the CLK properties for the OMAP 2320 are as follows: DSP/BIOS for OMAP 2320...
Page 562: C.3 Omap 2320 And The Hwi Module
OMAP 2320 and the HWI Module OMAP 2320 and the HWI Module With the introduction of the OMAP family of dual-core ARM + ‘C55x devices, many more interrupt sources have been defined than can be terminated on the legacy ‘C55x level 1 interrupt controller, which has a limit of 32 interrupts.
Page 563 OMAP 2320 and the HWI Module C.3.2 Level 2 Interrupt Objects and Properties There are 64 new HWI interrupt objects defined to correspond to level 2 interrupts 0 through 63. These objects are named HWI_L2_INT0 through HWI_L2_INT63. The following parameters have been added to HWI interrupt objects to allow for static configuration of the level 2 interrupt priorities, mirmask, and mir1mask: ❏...
Page 564 OMAP 2320 and the HWI Module The following Tconf statements configure the level 2 interrupt 0 to have a priority of 63 (lowest priority) and a mirmask of 0xffffffff (no other level 2 interrupts enabled while servicing this interrupt): // valid priority values: 0-63 bios.HWI_L2_INT0.priority = 63;...
Page 565 OMAP 2320 and the HWI Module C.3.4 HWI_enter and HWI_exit APIs The HWI_enter and HWI_exit assembly language macros have been enhanced to support selective interrupt nesting control of level 2 interrupts. This matches the way level 1 interrupts are controlled. The argument lists for these macros have two additional interrupt mask arguments.
Page 566: C.4 Omap 2320 And The C55 Module
OMAP 2320 and the C55 Module OMAP 2320 and the C55 Module In addition to extensions to the HWI module, the following extensions have been made to the C55 module to support the OMAP 2320 level 2 interrupts. C.4.1 C55_plug API For C55_plug, the range of vector IDs is extended from 0-31 to 0-95.
Page 567: C.6 Usage Examples
Usage Examples Usage Examples The following examples provide examples that use the HWI and C55 APIs related to the OMAP 2320. C.6.1 Installing and Enabling a Single Level 2 Interrupt This C code example plugs and enables the 23xx Level 2 interrupt #1. ======== l2_example1.c ======== DSP/BIOS Level 2 interrupt example #include <std.h>...
Page 568 Usage Examples C.6.2 Installing and Enabling Multiple Level 2 Interrupts This C code example plugs and enables level 2 interrupts numbers 10, 11, 12, and 13 and sets their priority levels to 0, 1, 2, 3 respectively (0 = highest priority). The default interrupt nesting behavior (all other interrupts enabled while l2FiqFunc is called) is configured.
Page 569 Usage Examples C.6.3 Enabling an L2 Interrupt Using "interrupt" Keyword This C code example plugs and enables OMAP 23xx level 2 interrupt 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;...
Page 570 Usage Examples C.6.4 Assembly Language ISR Using HWI_enter, HWI_exit This assembly code example uses the MIR mask arguments. ;# DSP/BIOS Level 2 interrupt example ; Include files .include log.h55 .include hwi.h55 .include c55.h55 .global _l2FiqFunc .global _intCount .ref _trace .ref _reportInfo _myIsr: HWI_enter C55_ALL_AR_DR_REGS, C55_ALL_ACC_REGS, C55_ALL_MISC1_REGS, C55_ALL_MISC2_REGS,...
Page 571 Usage Examples C.6.5 Statically Configuring a Level 2 Interrupt This example plugs and enables Level 2 interrupt number 43. All other level 1 and level 2 interrupts are disabled by the DSP/BIOS dispatcher during the execution of "myIsr". ======== l2_example4.c ======== DSP/BIOS Level 2 interrupt example #include <std.h>...
Page 572 C-14...
Page 573: This Appendix Describes Things You Need To Know About Dsp/Bios In Order To Use It With The
Appendix D DSP/BIOS for OMAP 2420 This appendix describes things you need to know about DSP/BIOS in order to use it with the OMAP 2420 platform. Topic Page D.1 Overview..........D–2 D.2 OMAP 2420 and the CLK Module .
Page 574: D.2 Omap 2420 And The Clk Module
Overview Overview DSP/BIOS has been enhanced to provide seamless support for the General Purpose Timers (GP Timers) and Level 2 Interrupt Controller (L2IC) present within the OMAP 2420. The CLK module functionality is now driven by GP Timers. The HWI module APIs can define and manipulate level 2 interrupts in addition to level 1 interrupts.
Page 575 OMAP 2420 and the CLK Module ❏ ENABLECLK. For OMAP 2420, this property enables/disables only the low-resolution timer. For example, these statements disable the low-resolution clock: bios.PRD.USECLK = false; bios.CLK.ENABLECLK = false; ❏ ENABLEHTIME. For OMAP 2420, this property enables/disables the high-resolution clock independent of the low-resolution clock.
Page 576 OMAP 2420 and the CLK Module In addition, you must route the appropriate clock sources to each GP timer (32KHz to the low-resolution timer, SYSCLK to the high-resolution timer). This can also be 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 */...
Page 577: D.3 Omap 2420 And The Hwi Module
OMAP 2420 and the HWI Module OMAP 2420 and the HWI Module With the introduction of the OMAP family of dual-core ARM + ‘C55x devices, many more interrupt sources have been defined than can be terminated on the legacy ‘C55x level 1 interrupt controller, which has a limit of 32 interrupts.
Page 578 OMAP 2420 and the HWI Module D.3.2 Level 2 Interrupt Objects and Properties There are 32 new HWI interrupt objects defined to correspond to level 2 interrupts 0 through 31. These objects are named HWI_L2_INT0 through HWI_L2_INT31. The following parameters have been added to HWI interrupt objects to allow for static configuration of the level 2 interrupt priorities and mirmask: ❏...
Page 579 OMAP 2420 and the HWI Module // valid priority values: 0-31 bios.HWI_L2_INT0.priority = 31; // use dispatcher and enable setting iMirMask, mirmask bios.HWI_L2_INT0.useDispatcher = true; // setting to "bitmask" enables writing to mirmask bios.HWI_L2_INT0.iMirMask = "bitmask"; // no other L2 interrupts while servicing HWI_L2_INT0 bios.HWI_L2_INT0.mirmask = 0xffffffff;...
Page 580 OMAP 2420 and the HWI Module HWI_enter C55_AR_DR_X_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: D.4 Omap 2420 And The C55 Module
OMAP 2420 and the C55 Module OMAP 2420 and the C55 Module In addition to extensions to the HWI module, the following extensions have been made to the C55 module to support the OMAP 2420 level 2 interrupts. D.4.1 C55_plug API For C55_plug, the range of vector IDs is extended from 0-31 to 0-63.
Page 582: D.6 Usage Examples
Usage Examples Usage Examples The following examples provide examples that use the HWI and C55 APIs related to the OMAP 2420. D.6.1 Installing and Enabling a Single Level 2 Interrupt This C code example plugs and enables the 24xx Level 2 interrupt #1. ======== l2_example1.c ======== DSP/BIOS Level 2 interrupt example #include <std.h>...
Page 583 Usage Examples D.6.2 Installing and Enabling Multiple Level 2 Interrupts This C code example plugs and enables level 2 interrupts numbers 10, 11, 12, and 13 and sets their priority levels to 0, 1, 2, 3 respectively (0 = highest priority). The default interrupt nesting behavior (all other interrupts enabled while l2FiqFunc is called) is configured.
Page 584 Usage Examples D.6.3 Enabling an L2 Interrupt Using "interrupt" Keyword This C code example plugs and enables OMAP 24xx level 2 interrupt 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;...
Page 585 Usage Examples D.6.4 Assembly Language ISR Using HWI_enter, HWI_exit This assembly code example uses the MIR mask arguments. ;# DSP/BIOS Level 2 interrupt example ; Include files .include log.h55 .include hwi.h55 .include c55.h55 .global _l2FiqFunc .global _intCount .ref _trace .ref _reportInfo _myIsr: HWI_enter C55_ALL_AR_DR_REGS, C55_ALL_ACC_REGS, C55_ALL_MISC1_REGS, C55_ALL_MISC2_REGS,...
Page 586 Usage Examples D.6.5 Statically Configuring a Level 2 Interrupt This example plugs and enables Level 2 interrupt number 7. All other level 1 and level 2 interrupts are disabled by the DSP/BIOS dispatcher during the execution of "myIsr". ======== l2_example4.c ======== DSP/BIOS Level 2 interrupt example #include <std.h>...
Page 587 Index board clock frequency 2-109 board input clock 2-112 board name 2-109 abort function 2-453 Bool data type 1-4 aborting program 2-454 Boolean values 1-4 AC registers, conventions for B-2 BR registers, conventions for B-3 allocators BSA registers, conventions for B-3 for messages sent by MSGQ module 2-233 BUF module 2-15 interface for 2-285...
Page 588 Index C55_disableInt function 2-28, C-8, D-9 control call on 2-124 C55_enableIER0 function 2-29 opening 2-125, 2-129 C55_enableIER1 function 2-29 consumer, of data pipe 2-267 C55_enableInt function 2-31, C-8, D-9 context C55_l2AckInt function 2-32, C-8, D-9 CLK, checking for 2-170 C55_l2DisableMIR function 2-33, C-8, D-9 HWI, checking for 2-170 C55_l2DisableMIR1 function 2-34 SWI, checking for 2-442...
Page 589 Index String 1-4 configuration properties for 2-92 DBIER0 register, conventions for B-3 global properties 2-93 DBIER1 register, conventions for B-3 object properties 2-94 deep sleep, enabling 2-307 DNL driver 2-62, 2-95 default values DOV driver 2-62, 2-96 for properties 1-4 DP register, conventions for B-3 dependencies DPI driver 2-62, 2-99...
Page 590 Index exit handler GBL_setProcId function 2-117 stacking 2-455 Gconf Extern data type 1-4 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 f32toi16 function 2-86 getenv function 2-511 false/true values 1-4 not callable from SWI or HWI A-9 fixed-size buffers GIO module 2-118...
Page 591 Index configuration properties 2-137 IER0 register, conventions for B-3 function callability A-3 IER1 register, conventions for B-3 functions in, list of 1-8, 2-137 IFR0 register, conventions for B-3 object properties 2-139 IFR1 register, conventions for B-3 properties 2-139 initialization 2-137 HOOK_getenv function 2-141 input channels HOOK_setenv function 2-142...
Page 592 Index object properties 2-177 functions in, list of 1-10, 2-195 LCK_create function 2-178 global properties 2-196 LCK_delete function 2-179 object properties 2-196 LCK_pend function 2-180 MBX_create function 2-197 thread restrictions for 2-512 MBX_delete function 2-198 LCK_post function 2-182 MBX_pend function 2-199 thread restrictions for 2-512 MBX_post function 2-200 Level 2 Interrupt Controller (L2IC) C-2, D-2...
Page 593 Index ID for, setting 2-262 MSGQ_count function 2-241 ID of, determining 2-246 MSGQ_free function 2-242 number of, in message queue 2-241 MSGQ_get function 2-243 placing in message queue 2-257 MSGQ_getAttrs function 2-244 receiving from message queue 2-243 MSGQ_getDstQueue function 2-245 reply destination of, determining 2-248 MSGQ_getMsgId function 2-246 reply destination of, setting 2-264...
Page 594 Index unsigned integers 2-12 recycling frame that has been read to 2-273 output channels writerAddr point of, getting 2-278 declaring 2-358 POOL module 2-285 disabling 2-360 configuration properties 2-285 enabling 2-362 functions in, list of 2-285 status of, determining 2-364 global properties 2-289 writing to 2-368 posted mode 2-111...
Page 595 Index global properties 2-302 PWRM_changeSetpoint function 2-310 PWRM_configure function 2-313 rand function PWRM_getCapabilities function 2-315 not callable from SWI or HWI A-9 PWRM_getCurrentSetpoint function 2-317 REA0 register, conventions for B-3 PWRM_getDependencyCount function 2-318 REA1 register, conventions for B-3 PWRM_getNumSetpoints function 2-319 reader, of data pipe 2-267 PWRM_getSetpointInfo function 2-320 readers, MSGQ module 2-231, 2-233...
Page 596 Index SIO_issue function 2-398 SIO_ISSUERECLAIM streaming model DPI and 2-100 scaling operation 2-105 SIO_put function 2-400 SEM module 2-369 SIO_ready function 2-402 configuration properties 2-369 SIO_reclaim function 2-403 function callability A-7 SIO_reclaimx function 2-406 functions in, list of 1-14, 2-369 SIO_segid function 2-407 global properties 2-371 SIO_select function 2-408...
Page 597 Index saving values for delta 2-420 SWI_dec function 2-433 tracing 2-467 SWI_delete function 2-434 updating 2-417 SWI_enable function 2-436 updating with delta 2-418 SWI_getattrs function 2-437 statistics object manager 2-412 SWI_getmbox function 2-439 status register conventions B-4 SWI_getpri function 2-440 std.h library SWI_inc function 2-441 functions in 2-511...
Page 598 Index writing error message to 2-188 counts per millisecond 2-48 writing program-supplied message to 2-190 reprogramming after frequency scaling 2-303 system settings, managing 2-451 resetting 2-54 timer counter 2-41 timer divide-down register 2-39 timer period register resetting 2-54 T0 register, conventions for B-3 trace buffer T1 register, conventions for B-3 memory segment for 2-452...
Page 599 Index TSK_setpri function 2-503 changing 2-310 TSK_settime function 2-504 determining 2-317 TSK_sleep function 2-506 frequency and voltage of, determining 2-320 TSK_stat function 2-507 latency to scale between 2-322 TSK_tick function 2-508 number of determining 2-319 TSK_time function 2-509 variables TSK_yield function 2-510 manipulating with interrupts disabled 2-2 vfprintf function not callable from SWI or HWI A-10...